Протокол интеграции HTTP(s) (POST) для отправки сообщений WhatsApp
ВНИМАНИЕ
Для использования данного вида интеграции Вам необходимоПароль для интеграции задается в настройках пользователя во вкладке Настройки API.
Варианты:
1) Регистрация в личном кабинете
2) Регистрация через менеджера компании Stream Telecom
Общие положения
Серверная платформа Stream-Telecom и клиент компании (далее ЗАКАЗЧИК) обмениваются HTTPS URL- encoded запросами, используя форматы передач данных JSON, параметры запроса включаются в текст запроса в кодировке UTF-8. Обмен данными построен по схеме запрос/ответ с использованием метода POST и не требует постоянного TCP/IP соединения.
Отправлять сообщения WhatsApp можно в следующем виде:
- Текст
- Изображение
- Текст с изображением
Точка доступа
Запросы ЗАКАЗЧИКА должны передаваться на сервер ИСПОЛНИТЕЛЯ по URL:
(ssl:
Функции
Запрос на получение списка шаблонов.
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
login=testuser
&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 |
Id сообщения WhatsApp |
wa |
Тип сообщения |
error (boolean) |
0 – запрос успешный, 1 – имеется ошибка в запросе |
state |
Статус сообщения |
state_error |
Причина, по которой сообщение не было доставлено абоненту |
state_time |
Время получения статуса |
price |
Цена за сообщение |
Получение входящих сообщений может быть настроено как для бизнес–сообщений, так и для WA Simple.
Пользователю требуется прислать адрес своего скрипта-обработчика, который будет принимать данные о сообщениях, отправленных в аккаунт whatsapp.
При получении запроса от абонента платформа вызывает URL скрипта-обработчика пользователя.
Пример запроса:
?date=@@MSGDATE@@&text=@@FULLSMS@@&smsid=@@MESSAGEID@@
&sender=@@SENDER@@&receiver=@@RECIP@@&prefix=@@PREFIX@@
Параметр |
Описание |
---|---|
date |
Дата и время сообщения в системе |
text |
Сообщение, которое отправил абонент |
smsid |
Идентификатор сообщения |
sender |
Номер телефона отправителя |
receiver |
Номер телефона получателя |
prefix |
Аккаунта WhatsApp, на который отправлено сообщение |
Все параметры необязательны для ответа и являются информационными. Информационные параметры используются при создании собственного сервиса.
Пример ответа:
Параметр |
Описание |
---|---|
smsid |
Идентификатор сообщения, он передается в http-запросе от платформы при вызове скрипта-обработчика пользователем |
Пример скрипта на PHP:
Статусы 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 |