Протокол интеграции Viber
ВНИМАНИЕ
Для использования данного вида интеграции вам необходимо зарегистрироваться на серверной платформе Stream Telecom либо с помощью менеджера компании.
Также необходимо зарегистрировать имя отправителя Viber. Для этого обратитесь в службу поддержки Stream Telecom.
Пароль для интеграции задается в настройках пользователя во вкладке Настройки API.
Общие положения
Серверная платформа Stream Telecom (далее Платформа) и клиент сервиса (далее Клиент) обмениваются HTTPS URL – encoded запросами, используя форматы передач данных JSON в соответствии с принципами REST. Действие над данными задается с помощью методов GET или POST в кодировке UTF-8.
Точка доступа
Запросы Клиента должны передаваться на Платформу по URL: http://gateway.api.sc/rest/Send/SendIM/ViberOne/
Функции
ЕДИНИЧНАЯ ОТПРАВКА VIBER
Примеры запросов
- Пример 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=testpass
&sourceAddressIM=testvibername
&textIM= Привет вайбер
&phone= 79211234567
&validityPeriod= 7200
- Пример 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=testpass
&sourceAddressIM=testvibername
&phone= 79211234567
&imageURL= https://my.site.com/images/image.jpg
&validityPeriod= 7200
- Пример 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=testpass
&sourceAddressIM=testvibername
&textIM= Привет вайбер
&phone= 79211234567
&imageURL= https://my.site.com/images/image.jpg
&buttonText= Нажми на кнопку
&buttonURL= stream-telecom.ru
&validityPeriod= 7200
Описание параметров запроса
Название |
Обязательное поле |
Тип данных |
Описание |
---|---|---|---|
login |
Да |
String |
Логин от учетной записи Stream Telecom |
pass |
Да |
String |
Пароль для API Stream Telecom |
sourceAddressIM |
Да |
String |
Имя отправителя, зарегистрированное для Viber |
textIM |
Да |
String |
Текст отправляемого сообщения Viber (Сообщение не должно содержать более 1000 символов) |
phone |
Да |
Integer |
Номер получателя сообщения Viber |
imageURL* |
Нет |
String |
URL изображения в формате: https://my.site.com/images/image.jpg Длина URL изображения не более 1000 символов. |
buttonText** |
Нет |
String |
Наименование кнопки. |
buttonURL** |
Нет |
String |
URL кнопки в формате: https://my.site.com/ Длина URL кнопки для перехода не более 1000 символов. |
sourceAddressSMS |
Нет |
String |
Имя отправителя СМС (при наличии параметров sourceAddressSMS и textSMS абоненту будет активирована каскадная отправка) |
textSMS |
Нет |
String |
Текст сообщения СМС (при наличии параметров sourceAddressSMS и textSMS абоненту будет активирована каскадная отправка) |
validityPeriod |
Нет |
Integer |
Время ожидания доставки сообщения в секундах. По умолчанию 7200 секунд. По истечению данного периода сообщение получит статус просрочено Min=15, Max=86400 |
Пример ответа
"18516"
Описание параметров ответа
Наименование параметра |
Описание |
---|---|
Возвращаемое значение |
Id сообщения Viber |
ВАЖНО!
*При отправке сообщения с картинкой необходимо указывать только imageURL.
**Для отправки сообщения с кнопкой обязательные параметры: imageURL + buttonText + textIM+ buttonURL. В противном случае будет отправлено сообщение без кнопки!
ПАКЕТНАЯ ОТПРАВКА
Примеры запросов
- Пакетная отправка
Адрес сервера: 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.com ",
"buttonURL":" https://myurl.com ",
"buttonText":"CLICK ME",
"sourceAddressSMS":"TESTSMS",
"textSMS":"СМС сообщение"
},
"2":
{
"type_viber":"image",
"phone":"79121231233",
"validityPeriod":"7200",
"imageURL":"https://myimage.com"
},
"3":
{
"type_viber":"text",
"phone":"79121231232",
"validityPeriod":"7200",
"sourceAddressIM":"Stream Tele",
"textIM":"Текст вайбер сообщения"
}
}
}
- Пример запроса отправки на несколько номеров
Адрес сервера: https://gateway.api.sc/rest/Send/SendIM/ViberBulk/
{
"login":"testuser",
"pass":"testpass",
"sourceAddressIM":"TEST VIBER",
"textIM":"Тестовое сообщение",
"type_viber":"text",
"phones":
{
"1":{"phone":"79121231234"},
"2":{"phone":"79121231233"},
"3":{"phone":"79121231232"}
}
}
Описание параметров запроса
Название |
Обязательное поле |
Тип данных |
Описание |
---|---|---|---|
login |
Да |
String |
Логин от учетной записи Stream Telecom |
pass |
Да |
String |
Пароль для API Stream Telecom |
sourceAddressIM |
Да |
String |
Имя отправителя, зарегистрированное для Viber |
textIM |
Да |
String |
Текст отправляемого сообщения Viber (Сообщение не должно содержать более 1000 символов) |
phone |
Да |
Integer |
Номер получателя сообщения Viber |
imageURL |
Нет |
String |
URL изображения в формате: https://my.site.com/images/image.jpg Длина URL изображения не более 1000 символов. |
buttonText |
Нет |
String |
Наименование кнопки. |
buttonURL |
Нет |
String |
URL кнопки в формате: https://my.site.com/ Длина URL кнопки для перехода не более 1000 символов. |
sourceAddressSMS |
Нет |
String |
Имя отправителя СМС (при наличии параметров sourceAddressSMS и textSMS абоненту будет активирована каскадная отправка) |
textSMS |
Нет |
String |
Текст сообщения СМС (при наличии параметров sourceAddressSMS и textSMS абоненту будет активирована каскадная отправка) |
validityPeriod |
Нет |
Integer |
Время ожидания доставки сообщения в секундах. По умолчанию 7200 секунд. По истечению данного периода сообщение получит статус просрочено Min=15, Max=86400 |
Пример ответа
{
"1": {"id": "3258315028721143935"},
"2": {"id": "3258315028721143968"},
"3": {"id": "3258315028721143968"}
}
КАСКАДНАЯ ОТПРАВКА
Каскад – это комбинация действий, которая приводит к отправке СМС в случае недоставки сообщения по VIBER.
Примеры запросов
- Единичная отправка 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
&textSMS=Тестовое сообщение
&validityPeriod= 7200
- Пакетная отправка c использованием метода каскад
Адрес сервера: 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.com ",
"buttonURL":" https://myurl.com ",
"buttonText":"CLICK ME",
"sourceAddressSMS":"TESTSMS",
"textSMS":"СМС сообщение"
},
"2":
{
"type_viber":"image",
"phone":"79121231233",
"validityPeriod":"7200",
"imageURL":"https://myimage.com ",
"sourceAddressSMS":"TESTSMS",
"textSMS":"СМС сообщение"
},
"3":
{
"type_viber":"text",
"phone":"79121231232",
"validityPeriod":"7200",
"sourceAddressIM":"Stream Tele",
"textIM":"Текст вайбер сообщения",
"sourceAddressSMS":"TESTSMS",
"textSMS":"СМС сообщение"},
}
}
}
- Отправка на несколько номеров с использованием метода каскад
Адрес сервера: https://gateway.api.sc/rest/Send/SendIM/ViberBulk/
{
"login":"testuser",
"pass":"testpass",
"sourceAddressIM":"TEST VIBER",
"textIM":"Тестовое сообщение",
"type_viber":"text",
"sourceAddressSMS":"TESTSMS",
"textSMS":"СМС сообщение"},
"phones":
{
"1":{"phone":"79121231234"},
"2":{"phone":"79121231233"},
"3":{"phone":"79121231232"}
}
}
Описание параметров запроса
Название |
Обязательное поле |
Тип данных |
Описание |
---|---|---|---|
login |
Да |
String |
Логин от учетной записи Stream Telecom |
pass |
Да |
String |
Пароль для API Stream Telecom |
sourceAddressIM |
Да |
String |
Имя отправителя, зарегистрированное для Viber |
textIM |
Да |
String |
Текст отправляемого сообщения Viber (Сообщение не должно содержать более 1000 символов) |
phone |
Да |
Integer |
Номер получателя сообщения Viber |
imageURL |
Нет |
String |
URL изображения в формате: https://my.site.com/images/image.jpg Длина URL изображения не более 1000 символов. |
buttonText |
Нет |
String |
Наименование кнопки. |
buttonURL |
Нет |
String |
URL кнопки в формате: https://my.site.com/ Длина URL кнопки для перехода не более 1000 символов. |
sourceAddressSMS |
Нет |
String |
Имя отправителя СМС (при наличии параметров sourceAddressSMS и textSMS абоненту будет активирована каскадная отправка) |
textSMS |
Нет |
String |
Текст сообщения СМС (при наличии параметров sourceAddressSMS и textSMS абоненту будет активирована каскадная отправка) |
validityPeriod |
Нет |
Integer |
Время ожидания доставки сообщения в секундах. По умолчанию 7200 секунд. По истечению данного периода сообщение получит статус просрочено Min=15, Max=86400 |
Пример ответа
- В случае единичной отправки
"18516"
- В случае пакетной отправки
{
"1": {"id": "3258315028721143935"},
"2": {"id": "3258315028721143968"},
"3": {"id": "3258315028721143968"}
}
Описание параметров ответа
Наименование параметра |
Описание |
---|---|
Возвращаемое значение |
Id сообщения Viber |
Примеры запросов
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 |
Просрочено |
Ошибки 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 |
ФОРМИРОВАНИЕ ДЕТАЛЬНОЙ СТАТИСТИКИ ПО РАССЫЛКАМ
Вы можете выполнить не более 4 запросов на формирование детальной статистики по рассылкам в час.
- Запрос на получение детальной статистики по рассылкам за заданный указанный период времени по номеру телефона, статусу, отправителю и данным подлогинов
GET
https://gateway.api.sc/rest/Statistic/all_stat.php/?login=testuser&pass=testpass
&startDateTime=2012-01-18T00:00:00&endDateTime=2012-01-18T23:59:00
POST
HTTP/1.1
Host https://gateway.api.sc/rest/Statistic/all_stat.php
Content-Type: application/x-www-form-urlencoded
HTTP/1.1 100 Continue
login=testuser
&pass=testpass
&startDateTime=2012-01-18T00:00:00
&endDateTime=2012-01-18T23:59:00
Наименование поля |
Обязательное поле |
Описание |
---|---|---|
login |
Да |
Логин от учетной записи Stream Telecom |
pass |
Да |
Пароль для API Stream Telecom |
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 -по умолчанию). |
zip |
Нет |
Указывает на формат выгрузки. Допустимые значения: 0, 1 (0 – по умолчанию). |
id_smpp |
Нет |
Указывает на необходимость добавления в выгрузку идентификаторов сообщений. Допустимые значения: true, false (false – по умолчанию) |
Ответ
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 |
Запрос более двух отчетов одновременно не разрешен, отправьте запрос позднее |
Request per hour limit exceeded |
Превышен лимит запросов в час (не более 4) |
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
https://gateway.api.sc/rest/Statistic/all_stat.php/?login=testuser&pass=testpass&id_report=12124
POST
HTTP/1.1
Host https://gateway.api.sc/rest/Statistic/all_stat.php
Content-Type: application/x-www-form-urlencoded
HTTP/1.1 100 Continue
login=testuser
&pass=testpass
&id_report=12124
Ответ
В зависимости от передаваемых настроек, файл детальной статистики в формате xlsx или архив, содержащий данный файл.