Протокол интеграции HTTP(s) (POST) для отправки сообщений WhatsApp

ВНИМАНИЕ

Для использования данного вида интеграции Вам необходимо зарегистрироваться на серверной платформе Stream Telecom, либо зарегистрироваться через менеджера компании. Отправитель WhatsApp регистрируется путем подачи заявки менеджерам нашей компании.

Пароль для интеграции задается в настройках пользователя во вкладке Настройки API.

Варианты:

1) Регистрация в личном кабинете

2) Регистрация через менеджера компании Stream Telecom

Общие положения

Серверная платформа Stream-Telecom и клиент компании (далее ЗАКАЗЧИК) обмениваются HTTPS URL- encoded запросами, используя форматы передач данных JSON, параметры запроса включаются в текст запроса в кодировке UTF-8. Обмен данными построен по схеме запрос/ответ с использованием метода POST и не требует постоянного TCP/IP соединения.

Отправлять сообщения WhatsApp можно в следующем виде:

Текст
Изображение
Текст с изображением

Точка доступа

Запросы ЗАКАЗЧИКА должны передаваться на сервер ИСПОЛНИТЕЛЯ по URL: http://gateway.api.sc/rest/Send/SendIM/Wa/

(ssl: https://gateway.api.sc/rest/Send/SendIM/Wa/)

Stream_Telecom_WHATSAPP_1.8.pdf

Функции

Запрос на получение списка шаблонов.

GET-запрос

https://gateway.api.sc/rest/Template/Wa/?login=userlogin&pass=userpassword&originator=WAOriginator

Название	Обязательное поле	Тип данных	Описание
login	Да	String	Логин от учетной записи Stream Telecom
pass	Да	String	Пароль API от учетной записи Stream Telecom
originator	Да	String	Имя отправителя WhatsApp

Ответ

[
    {
        "template_id": "135795",
        "originator": "WAoriginator",
        "template": "Новое предложение на сайте! \nДо {{1}} получите -{{2}}% на первые {{3}} заказов от {{4}}р.",
        "header_type": "",
        "header_template": "",
        "footer_template": "",
        "button1": "",
        "button2": "",
        "button3": "",
        "button_url": "https://mysite.com/{{1}}",
        "button_url_text": "Подробнее",
        "button_phone_number": "",
        "button_phone_text": ""
    }
]

Название	Описание
template_id	Идентификатор шаблона
originator	Имя отправителя WhatsApp
template	Текст шаблона
header_type	Тип заголовка (текст заголовка, изображение, документ или видео)
header_template	Текст заголовка
footer_template	Текст подписи
button1	Текстовая кнопка 1
button2	Текстовая кнопка 2
button3	Текстовая кнопка 3
button_url	Адрес кнопки с ссылкой
button_url_text	Текст кнопки с ссылкой
button_phone_number	Номер кнопки с телефоном
button_phone_text	Текст кнопки с телефоном

Запрос на получение списка имён отправителей.

GET-запрос

https://gateway.api.sc/rest/Originator/Wa/?login=userlogin&pass=userpassword&simple=true

Название	Обязательное поле	Тип данных	Описание
login	Да	String	Логин от учетной записи Stream Telecom
pass	Да	String	Пароль API от учетной записи Stream Telecom
simple	Нет	Boolean	Параметр, при передаче значения true в котором, будет получен список имен отправителей по WA Simple

Ответ

[
    {  
        "originator": "WAorginator",
        "phone": "79876543210",
    },
    {
        "originator": "WAorginator",
        "phone": "79876543211",
    },
    "..."
]

Название	Описание
originator	Имя отправителя WhatsApp
phone	Номер отправителя WhatsApp

    Пример POST запроса:
  
    HTTP/1.1
  
    HOST: http://gateway.api.sc/rest/Send/SendIM/Wa/
  
    Content-Type: application/x-www-form-urlencoded
  
    HTTP/1.1 100 Continue
  
    login=testuser
  
    &pass=userpassword
  
    &sourceAddress=whatsappname
  
    &text=Привет WhatsApp
  
    &imageURL=https://site.com/image.jpg
  
    &documentURL=https://site.com/document.pdf
  
    &audioURL=https://site.com/audio.mp3
  
    &videoURL=https://site.com/video.mp4
  
    &phone=79211234567
  
    &buttons[0][text]=button0_text
  
    &buttons[0][url]=button0_url
  
    &buttons[1][text]=button1_text
  
    &buttons[1][phone]=button1_phone
  
    &simple=false

Ответ

В ответ возвращается цифровой id сообщения WhatsApp

Название	Обязательное поле	Тип данных	Описание
login	Да	String	Логин от учетной записи Stream Telecom
pass	Да	String	Пароль API от учетной записи Stream Telecom
sourceAddress	Да	String	Имя отправителя, зарегистрированное для WhatsApp
text	Нет	String	Текст отправляемого сообщения WhatsApp. Сообщение не должно содержать более 1000 символов. (необязателен, если используется параметр imageURL)
imageURL	Нет	String	URL адрес изображения. Рекомендовано использовать изображение размером 400x400px с расширением .jpg или .png
documentURL	Нет	String	URL адрес документа. Поддерживаемые форматы: .pdf, .doc/.docx
audioURL	Нет	String	URL адрес аудиофайла. Поддерживаемые форматы: acc, mp3, amr, audio/mpeg, audio/ogg, codecs=opus
videoURL	Нет	String	URL адрес видеофайла. Поддерживаемые форматы: video/mp4 с кодеком H.264 и AAC audio
phone	Да	Integer	Номер получателя сообщения WhatsApp
buttons[0..2][text]	Нет	String	Текст кнопки. Длина до 21 символа. Не будет передано по WA Simple
buttons[0..2][payload]	Нет	String	Скрытый текст, который будет передан во входящем сообщении. Длина до 128 символов. Не будет передано по WA Simple
buttons[0..2][url]	Нет	String	URL сайта. Использование доступно только при отправке зарегистрированного шаблонного сообщения (HSM). Не будет передано по WA Simple
buttons[0..2][phone]	Нет	String	Номер телефона в формате +СХХХ ХХХ-ХХ-ХХ, Где С – код страны, Х – номер телефона. Использование доступно только при отправке зарегистрированного шаблонного сообщения (HSM). Не будет передано по WA Simple
simple	Нет	Boolean	Параметр, при передаче значения true в котором, отправка будет осуществляться по каналу WA Simple. При отправке через WA Simple кнопки отправлены не будут

    Пример POST запроса:
  
    HTTP/1.1
  
    HOST: http://gateway.api.sc/rest/Send/SendIM/Wa/
  
    Content-Type: application/x-www-form-urlencoded
  
    HTTP/1.1 100 Continue
  
    login=testuser
  
    &pass=userpassword
  
    &sourceAddress=whatsappname
  
    &text=Привет WhatsApp
  
    &imageURL=https://site.com/image.jpg
  
    &documentURL=https://site.com/document.pdf
  
    &audioURL=https://site.com/audio.mp3
  
    &videoURL=https://site.com/video.mp4
  
    &phone=79211234567
  
    &buttons[0][text]=text 1
  
    &buttons[0][payload]=text 1
  
    &buttons[1][text]=text 2
  
    &buttons[1][payload]=text 2
  
    &ttl=172800
  
    &sourceAddressSMS=SMS_Sender
  
    &textSMS=Привет WhatsApp

Ответ

В ответ возвращается цифровой id сообщения WhatsApp

Название	Обязательное поле	Тип данных	Описание
login	Да	String	Логин от учетной записи Stream Telecom
pass	Да	String	Пароль API от учетной записи Stream Telecom
sourceAddress	Да	String	Имя отправителя, зарегистрированное для WhatsApp
text	Нет	String	Текст отправляемого сообщения WhatsApp. Сообщение не должно содержать более 1000 символов. (необязателен, если используется параметр imageURL)
imageURL	Нет	String	URL адрес изображения. Рекомендовано использовать изображение размером 400x400px с расширением .jpg или .png
documentURL	Нет	String	URL адрес документа. Поддерживаемые форматы: .pdf, .doc/.docx
audioURL	Нет	String	URL адрес аудиофайла. Поддерживаемые форматы: acc, mp3, amr, audio/mpeg, audio/ogg, codecs=opus
videoURL	Нет	String	URL адрес видеофайла. Поддерживаемые форматы: video/mp4 с кодеком H.264 и AAC audio
phone	Да	Integer	Номер получателя сообщения WhatsApp
buttons[0..2][text]	Нет	String	Текст кнопки. Длина до 21 символа. Не будет передано по WA Simple
buttons[0..2][payload]	Нет	String	Скрытый текст, который будет передан во входящем сообщении. Длина до 128 символов. Не будет передано по WA Simple
buttons[0..2][url]	Нет	String	URL сайта. Использование доступно только при отправке зарегистрированного шаблонного сообщения (HSM). Не будет передано по WA Simple
buttons[0..2][phone]	Нет	String	Номер телефона в формате +СХХХ ХХХ-ХХ-ХХ, Где С – код страны, Х – номер телефона. Использование доступно только при отправке зарегистрированного шаблонного сообщения (HSM). Не будет передано по WA Simple
simple	Нет	Boolean	Параметр, при передаче значения true в котором, отправка будет осуществляться по каналу WA Simple. При отправке через WA Simple кнопки отправлены не будут
ttl	Нет	Integer	Срок жизни WhatsApp сообщения – количество секунд, по истечении которого будет отправлено СМС. По умолчанию 86400 (24 часа)
sourceAddressSMS	Нет	String	Имя отправителя из личного кабинета, от которого будет отправлено СМС в случае недоставки сообщения WhatsApp или истечения его срока жизни
textSMS	Нет	String	Текст СМС, которое будет отправлено в случае недоставки сообщения WhatsApp или истечения его срока жизни

Пример POST запроса:

HTTP/1.1

HOST: http://gateway.api.sc/rest/State/Wa/

Content-Type: application/x-www-form-urlencoded

HTTP/1.1 100 Continue

&pass=userpassword

&messageId=12

&simple=true

Название	Обязательное поле	Тип данных	Описание
login	Да	String	Логин от учетной записи Stream Telecom
pass	Да	String	Пароль API от учетной записи Stream Telecom
messageId	Да	String	Id сообщения WhatsApp (можно указывать несколько id через запятую)
simple	Нет	Boolean	Параметр, при передаче значения true в котором, возвращается статус WA Simple сообщения

Ответ

{

"12": {

"wa": {

"error": 0,

"state": "read",

"state_error": "null",

"state_time": "2017-04-10 11:07:55",

"price": 0

}

}

}

Параметр	Описание
12	Id сообщения WhatsApp
wa	Тип сообщения
error (boolean)	0 – запрос успешный, 1 – имеется ошибка в запросе
state	Статус сообщения
state_error	Причина, по которой сообщение не было доставлено абоненту
state_time	Время получения статуса
price	Цена за сообщение

Получение входящих сообщений может быть настроено как для бизнес–сообщений, так и для WA Simple.

Пользователю требуется прислать адрес своего скрипта-обработчика, который будет принимать данные о сообщениях, отправленных в аккаунт whatsapp.

При получении запроса от абонента платформа вызывает URL скрипта-обработчика пользователя.

Пример запроса:

  http://www.my_site.ru/sms.php
?date=@@MSGDATE@@&text=@@FULLSMS@@&smsid=@@MESSAGEID@@
    
&sender=@@SENDER@@&receiver=@@RECIP@@&prefix=@@PREFIX@@

Параметр	Описание
date	Дата и время сообщения в системе
text	Сообщение, которое отправил абонент
smsid	Идентификатор сообщения
sender	Номер телефона отправителя
receiver	Номер телефона получателя
prefix	Аккаунта WhatsApp, на который отправлено сообщение

Все параметры необязательны для ответа и являются информационными. Информационные параметры используются при создании собственного сервиса.

Пример ответа:

smsid=5094

Параметр	Описание
smsid	Идентификатор сообщения, он передается в http-запросе от платформы при вызове скрипта-обработчика пользователем

Пример скрипта на PHP:

<?php

$smsid = $_GET['smsid'];

echo "smsid=" . $smsid . "\n";

?>

Статусы WhatsApp

Статус	Описание
DELIVERED	Доставлено
UNDELIVERED	Не доставлено
SENT	Отправлено
READ	Прочитано

Ошибки WhatsApp

Ошибка	Описание
user-blocked	Абонент заблокировал рассылку
not-template-match	Не найден подходящий шаблон сообщения
filtered	Сообщение содержит запрещенные к использованию слова

Коды ошибок REST

REST error code	HTTP status code	Описание
-	200	OperationComplete
1	400	ArgumentCanNotBeNullOrEmpty
2	400	InvalidArgument
3	400	InvalidSessionID
4	401	UnauthorizedAccess
5	403	NotEnoughCredits
6	400	InvalidOperation
7	403	Forbidden
8	500	GatewayError
9	500	InternalServerError

Протокол интеграции HTTP(s) (POST) для отправки сообщений WhatsApp

Функции

Точный расчет

Авторизация

Регистрация

Восстановление пароля