Протокол интеграции Viber
ВНИМАНИЕ
Для использования данного вида интеграции Вам необходимо зарегистрироваться на серверной платформе Stream Telecom, либо зарегистрироваться через менеджера компании. Отправитель Viber регистрируется путем подачи заявки менеджерам нашей компании.
Пароль для интеграции задается в настройках пользователя во вкладке Настройки API.
Общие положения
Серверная платформа Stream Telecom (далее Платформа) и клиент сервиса (далее Клиент) обмениваются HTTPS URL – encoded запросами, используя форматы передач данных JSON, в соответствии с принципами REST. Действие над данными задается с помощью методов GET или POST в кодировке UTF-8.
Точка доступа
Запросы Клиента должны передаваться на Платформу по URL: http://gateway.api.sc/rest/Send/SendIM/ViberOne/
Функции
Примеры запросов
1. Пример POST-запроса: Только текст
HTTP/1.1
HOST: https://gateway.api.sc/rest/Send/SendIM/ViberOne/
Content-Type: application/x-www-form-urlencoded
HTTP/1.1 100 Continue
login=testuser
&pass=userpassword
&sourceAddressIM=testvibername
&textIM=Привет вайбер
&phone=79211234567
&validityPeriod=7200
Пример ответа
"14586"
Параметр |
Описание |
14586 |
Id сообщения Viber |
2. Пример POST-запроса: Только картинка
HTTP/1.1
HOST: https://gateway.api.sc/rest/Send/SendIM/ViberOne/
Content-Type: application/x-www-form-urlencoded
HTTP/1.1 100 Continue
login=testuser
&pass=userpassword
&sourceAddressIM=testvibername
&phone=79211234567
&imageURL=https://my.site.com/images/image.jpg
&validityPeriod=7200
Пример ответа
"14545"
Параметр |
Описание |
14545 |
Id сообщения Viber |
3. Пример POST-запроса с кнопкой, картинкой и текстом
HTTP/1.1
HOST: https://gateway.api.sc/rest/Send/SendIM/ViberOne/
Content-Type: application/x-www-form-urlencoded
HTTP/1.1 100 Continue
login=testuser
&pass=userpassword
&sourceAddressIM=testvibername
&textIM=Привет вайбер
&phone=79211234567
&imageURL=https://my.site.com/images/image.jpg
&buttonText=Нажми на кнопку
&buttonURL=stream-telecom.ru
&validityPeriod=7200
Пример ответа
"13566"
Параметр |
Описание |
13566 |
Id сообщения Viber |
4. Пример POST-запроса с кнопкой, картинкой и текстом, с методом каскад
Каскад – это комбинация действий, которая приводит к отправке СМС, в случае недоставки сообщения по VIBER.
HTTP/1.1
HOST: https://gateway.api.sc/rest/Send/SendIM/ViberOne/
Content-Type: application/x-www-form-urlencoded
HTTP/1.1 100 Continue
login=testuser
&pass=userpassword
&sourceAddressIM=testvibername
&textIM=Привет вайбер
&phone=79211234567
&imageURL=https://my.site.com/images/image.jpg
&buttonText=Нажми на кнопку
&buttonURL=stream-telecom.ru
&sourceAddressSMS=TestRusinfo (Имя отправителя по sms (каскад))
&textSMS=Тестовое сообщение (Текст резервного сообщения по sms (каскад))
&validityPeriod=7200
Пример ответа
"18516"
Параметр |
Описание |
18516 |
Id сообщения Viber |
Описание параметров запросов
Название |
Обязательное поле |
Тип данных |
Описание |
login |
Да |
String |
Логин от учетной записи Stream Telecom |
pass |
Да |
String |
Пароль для api (задается в личном кабинете во вкладке Настройка > Безопасность) |
sourceAddressIM |
Да |
String |
Имя отправителя, зарегистрированное для Viber |
textIM |
Да |
String |
Текст отправляемого сообщения Viber (Сообщение не должно содержать более 1000 символов) |
phone |
Да |
Integer |
Номер получателя сообщения Viber |
imageURL* |
Нет |
String |
URL изображения в формате: https://my.site.com/images/image.jpg. Длина URL изображения не более 1000 символов |
buttonText** |
Нет |
String |
Наименование кнопки. (не более 30 символов) |
buttonURL** |
Нет |
String |
URL кнопки в формате: https://my.site.com/. Длина URL кнопки для перехода не более 1000 символов |
sourceAddressSMS |
Нет |
String |
Имя отправителя SMS |
textSMS |
Нет |
String |
Текст сообщения SMS |
validityPeriod |
Нет |
Integer |
Время ожидания доставки сообщения в секундах. По умолчанию 7200 секунд Min=15, Max=86400 |
ВАЖНО!
*При отправке сообщения с картинкой, необходимо указывать только imageURL.
**Для отправки сообщения с кнопкой, обязательные параметры: imageURL+buttonText+textIM+buttonURL, в противном случае будет отправлено сообщение без кнопки.
Примеры запросов
1. Пример POST-запроса: Только текст
HTTP/1.1
HOST: https://gateway.api.sc/rest/State/Viber/
Content-Type: application/x-www-form-urlencoded
HTTP/1.1 100 Continue
login=testuser
&pass=userpassword
&messageId=12345
2. Пример GET-запроса: (в одну строку)
https://gateway.api.sc/rest/State/Viber/?login=testuser&pass=userpassword&messageId=12345
Название |
Обязательное поле |
Тип данных |
Описание |
login |
Да |
String |
Логин от учетной записи Stream Telecom |
pass |
Да |
String |
Пароль для api (задается в личном кабинете во вкладке Настройка > Безопасность) |
messageId |
Да |
String |
Id сообщения Viber(можно указывать несколько id через запятую) |
Пример ответа (в случае отправки только Viber)
{ "10889": { viber": { "error": 0, "state": "read", "state_error": "null", "state_time": "2017-04-10 11:07:55" } } }
Пример ответа (в случае отправки каскада)
{ "10891": { "viber": { "error": 0, "state": "undelivered", "state_error": "not-viber-user", "state_time": "2017-04-10 13:18:53" }, "sms": { "state": "delivered", "state_time": "2017-04-10 13:19:00" } } }
Пример ответа (в случае некорректного запроса)
{ "1089": { "error": 1, "error_info": "No data for this messageId", "state": "null", "state_time": "null" } }
Параметр |
Описание |
10887 |
Id сообщения Viber |
viber/sms |
Тип сообщения |
error (boolean) |
0 – запрос успешный, 1 – имеется ошибка в запросе |
state |
Статус сообщения |
state_error |
Причина, по которой сообщение не было доставлено абоненту |
state_time |
Время получения статуса |
error_info |
Описание ошибки |
Статусы viber
Статус |
Описание |
delivered |
Доставлено |
undelivered |
Не доставлено |
sent |
Отправлено |
read |
Прочитано |
Статусы смс
Статус |
Описание |
delivered |
Доставлено |
undelivered |
Не доставлено |
sent |
Отправлено |
expired |
Просрочено |
Примеры запросов
1. Пакетная отправка
Адрес сервера: https://gateway.api.sc/rest/Send/SendIM/ViberBulk/
{ "login":"testuser", "pass":"testpass", "sourceAddressIM":"TEST VIBER", "phones": { "1":{ "type_viber":"button", "phone":"79121231234", "validityPeriod":"7200", "textIM":"Тестовое сообщение", "imageURL":" https:\/\/myimage ", "buttonURL":" https:\/\/myurl ", "buttonText":"CLICK ME", "sourceAddressSMS":"TESTSMS", "textSMS":"SMS сообщение"}, "2":{ "type_viber":"image", "phone":"79121231233", "validityPeriod":"7200", "imageURL":"https:\/\/myimage"}, "3":{ "type_viber":"text", "phone":"79121231232", "validityPeriod":"7200", "sourceAddressIM":"Stream Tele", "textIM":"Текст вайбер сообщения"} } }
Пример ответа
{ "1": {"id": "3258315028721143935"}, "2": {"id": "3258315028721143968"}, "3": {"id": "3258315028721143968"} }
2.Пример запроса отправки на несколько номеров
Адрес сервера: https://gateway.api.sc/rest/Send/SendIM/ViberBulk/
{ "login":"testuser", "pass":"testpass", "sourceAddressIM":"TEST VIBER", "textIM":"Тестовое сообщение", "type_viber":"text", phones": { 4":{"phone":"79121231234"}, 5":{"phone":"79121231233"}, 6":{"phone":"79121231232"} } }
Пример ответа
{ 4": {"id": "3258315028721143940"}, 5": {"id": "3258315028721143956"}, 6": {"id": "3258315028721143969"} }
Описание параметров
Название |
Обязательное поле |
Тип данных |
Описание |
login |
Да |
String |
Логин от учетной записи StreamTelecom |
pass |
Да |
String |
Пароль для api (задается в личном кабинете во вкладке Настройка > Безопасность) |
sourceAddressIM |
Да |
String |
Имя отправителя, зарегистрированное для Viber |
type_viber |
Да |
String |
Тип сообщения Viber (button– текст с кнопкой и картинкой или текст с кнопкой, image – только картинка, text– только текст) |
textIM |
Да |
String |
Текст отправляемого сообщения Viber (Сообщение не должно содержать более 1000 символов) |
phone |
Да |
Integer |
Номер получателя сообщения Viber |
imageURL* |
Нет |
String |
URL изображения в формате:my.site.com/images/image.jpgДлина URL изображения не более 1000 символов. |
buttonText** |
Нет |
String |
Наименование кнопки. (не более 30 символов) |
buttonURL** |
Нет |
String |
URL кнопки в формате: my.site.com/Длина URLкнопки для перехода не более 1000 символов. |
sourceAddressSMS |
Нет |
String |
Имя отправителя SMS (при наличии параметров sourceAddressSMS и textSMS, абоненту будет активирована каскадная отправка) |
textSMS |
Нет |
String |
Текст сообщения SMS (при наличии параметров sourceAddressSMS и textSMS, абоненту будет активирована каскадная отправка) |
validityPeriod |
Нет |
Integer |
Время ожидания доставки сообщения Viber в секундах. По умолчанию 7200 секунд. (Min=15, Max=86400) |
Статусы Viber
Статус |
Описание |
delivered |
Доставлено |
undelivered |
Не доставлено |
sent |
Отправлено |
read |
Прочитано |
Статусы смс
Статус |
Описание |
delivered |
Доставлено |
undelivered |
Не доставлено |
sent |
Отправлено |
expired |
Просрочено |
Ошибки Viber
Статус |
Описание |
user-blocked |
Абонент заблокирован |
not-viber-user |
Абонент не является пользователем Viber |
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 |
Запрос на получение детальной статистики по рассылкам за заданный указанный период времени, по номеру телефона, статусу, отправителю и данным подлогинов.
Запрос
GET /?sessionId=967648e7c4bc5557182862a4f0490f5e &startDateTime=2012-01-18T00:00:00&endDateTime=2012-01-18T23:59:00 HTTP/1.1 Host gateway.api.sc/rest/Statistic/all_stat.php Content-Type: application/x-www-form-urlencoded |
POST sessionId=967648e7c4bc5557182862a4f0490f5e &startDateTime=2012-01-18T00:00:00&endDateTime=2012-01-18T23:59:00 HTTP/1.1 Host gateway.api.sc/rest/Statistic/all_stat.php Content-Type: application/x-www-form-urlencoded |
Наименование поля |
Описание |
sessionId |
API ключ (36 символов). Обязательный. |
startDateTime |
Дата и время начала периода, за который необходимо получить статистику, например 2012-01-18T00:00:00. Обязательный. |
endDateTime |
Дата и время конца периода, за который необходимо получить статистику, например 2012-01-18T23:59:00. Обязательный. |
state |
Формирование статистики по определенному статусу сообщений. Допустимые значения: deliver, not_deliver, expired, sent (доставлено, не доставлено, просрочено, в процессе) Необязательный. |
phone |
Формирование статистики по определенному номеру абонента. Необязательный. |
c_base |
Указывает на необходимость выгрузки данных с привязкой к базе адресатов. Допустимые значения: 0, 1 (0 -по умолчанию) Необязательный. |
sub_stat |
Указывает на необходимость выгрузки данных с подлогинов. Допустимые значения: 0, 1 (0 -по умолчанию) Необязательный. |
Ответ
HTTP/1.1 200 OK Cache-Control: private Connection: Keep-Alive Content-Type: application/json; charset=utf-8 12124 |
Наименование поля |
Описание |
Возвращаемое значение |
ID формируемого отчета. |
В случае отправки некорректного запроса, Вам вернется код возникшей ошибки
Текст ошибки |
Описание |
More than 2 reports at once are not allowed, make request later |
Запрос двух отчетов одновременно не разрешен, отправьте запрос позднее |
Bad Request |
Некорректный запрос |
Not correct format endDateTime |
Некорректный формат даты конца периода |
Not correct format startDateTime |
Некорректный формат даты начала периода |
SessionID expired |
Истек срок идентификатора сессии |
Not correct length originator |
Некорректная длина имени отправителя |
Not correct length phone |
Некорректная длина номера телефона |
Phone must be numeric |
Номер телефона должен иметь числовой формат |
EndDateTime can not be null or empty\r\nParameter name: endDateTime |
Параметр endDateTime не может быть нулевым или пустым |
StartDateTime can not be null or empty\r\nParameter name: startDateTime |
Параметр startDateTime не может быть нулевым или пустым |
Id report not found |
Идентификатор отчета не найден |
Report is not ready yet |
Отчет не готов |
File not exist |
Файл не существует |
Запрос на получение файла с отчетом
GET /?sessionId=967648e7c4bc5557182862a4f0490f5e &id_report=12124 HTTP/1.1 Host gateway.api.sc/rest/Statistic/all_stat.php Content-Type: application/x-www-form-urlencoded |
POST sessionId=967648e7c4bc5557182862a4f0490f5e &id_report=12124 HTTP/1.1 Host gateway.api.sc/rest/Statistic/all_stat.php
Content-Type: application/x-www-form-urlencoded |
Архив с файлом детальной статистики в формате xlsx |