Протокол интеграции 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/
Функции
Запрос на получение списка шаблонов.
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 |