Viber HTTP API¶
Общие сведения¶
API предоставляет интерфейс для автоматизации процесса отправки мгновенных сообщений Viber мессенджера через платформу Devino Telecom. С помощью API можно производить пакетные рассылки, отправлять транзакционные сообщения, а также осуществлять переотправку SMS в случае недоставки Viber сообщений одной командой.
Предупреждение
Внимание! Для использования данного вида интеграции необходимо обратиться к своему менеджеру, либо в техническую поддержку support@devinotele.com для настройки доступа.
Работа с API осуществляется с использованием метода HTTP-POST. Тела запроса клиента и ответа сервера представлены в формате JSON. Данные должны быть в кодировке UTF-8.
Данным методом можно отправлять не более 100 сообщений.
API поддерживает базовую авторизацию через заголовок Authorization (https://en.wikipedia.org/wiki/Basic_access_authentication). В заголовке запроса необходимо передать логин и пароль из Личного Кабинета в формате login:password в base64 кодировке.
Например:
Authorization: Basic dGVzdGVyOjExMTExMQ==
Точка подключения:
https://viber.devinotele.com:444
Используемые типы данных:
| Тип данных | Описание |
|---|---|
| Integer | Положительные числа больше нуля |
| DateTime | Значение, обозначающее дату и время, представляются в пакетах в формате «yyyy-MMdd hh:mm:ss», например, 1999-05-31 13:20:00 |
| Address | Адрес абонента. Номер мобильного телефона абонента в международном формате (в формате E.164). Например, 79031112233, для России или 491791112233 для Германии |
| String | Строка символов в формате UTF-8 |
Ограничения и допустимые значения описаны далее в разделе описания пакетов протокола
Отправка сообщения¶
https://viber.devinotele.com:444/send
Метод служит для отправки сообщения на указанные номера абонента. Параметры сообщения и адреса абонентов передаются в теле запроса в формате JSON.
Типы сообщений, допустимые к отправке:
| Тип сообщения | Возможность переотправки | contentType |
|---|---|---|
| Текст+кнопка | Да | button |
| Текст+картинка+кнопка | Да | button |
| Текст | Да | text |
| Картинка | Нет | image |
Отправка текстового сообщений¶
Запрос на отправку текстового сообщения собирается с указанием contentType: «text». Возможна переотправка по СМС.
Пример запроса:
https://viber.devinotele.com:444/send
{
"resendSms" : "true",
"messages" :
[ {
"subject" : "Subject",
"priority" : "high",
"validityPeriodSec" : 3600,
"comment" : "comment",
"type" : "viber",
"contentType" : "text",
"content" :
{
"text" : "Message text"
},
"address" : "79250000000",
"smsText":"1sms Message text",
"smsSrcAddress":"1TEST",
"smsValidityPeriodSec":5000
} ]
}
Описание полей тела запроса отправки сообщения:
| Параметр | Тип данных | Описание | Допустимые значения | Обязательное поле |
|---|---|---|---|---|
| resendSms | boolean | Признак переотправки сообщения, по умолчанию (если параметр не передаётся) - переотправка выключена | true – переотправка включена false– переотправка выключена | Нет |
| subject | String | Подпись для сообщения, которая отображается в мессенджере абонента | Все подписи предварительно должны регистрироваться на платформе провайдера Длина имени не более 11 символов. | да |
| priority | String | Приоритет сообщения. Используется для управления оперативностью доставки сообщения абоненту. Для транзакционных сообщений приоритет должен быть высоким, для рекламы низким. | low – низкий приоритет. normal – нормальный приоритет high – высокий приоритет. realtime – высочайший приоритет | Да |
| validityPeriodSec | Integer | Время ожидания доставки Viber сообщения в секундах | 30 – 86400. | Да |
| comment | String | Произвольный текстовый комментарий. | Нет | |
| type | String | Тип отправляемого сообщения. Определяет канал, которые используется для доставки сообщения на мобильный телефон абонента | viber – Viber messenger | Да |
| contentType | String | Тип содержимого сообщения. | text – текстовое сообщение image – изображение button – гиперссылка в виде кнопки | Да |
| content | Составной тип | Содержимое сообщения. Зависит от значения contentType | Определяется значением contentType | Да |
| address | Address | Номер телефона абонента, на который отправляется сообщение | Положительные целые числа. Номер мобильного телефона абонента в международном формате (в формате E.164) | Да |
| smsText | String | Текст СМС сообщения | Да | |
| smsSrcAddress | String | Адрес отправителя СМС сообщения | Адрес отправителя должен быть согласован на СМС в личном кабинете, длина имени не более 11 латинский символов или цифр. | Да |
| smsValidity PeriodSec | Integer | Время ожидания доставки СМС сообщения в секундах | 60 – 86400. Если параметр не указан, то время жизни сообщения будет выставлено по-умолчанию СМС-центром оператора. | Да |
Пример ответа:
{
"status" : "ok"
"messages" :
[ {
"providerId" : 3158611117333282816,
"code" : "ok"
} ]
}
Описание полей ответа на запрос отправки сообщения:
| Параметр | Тип данных | Описание | Допустимые значения | Обязательное поле |
|---|---|---|---|---|
| status | String | Статус ответа провайдера на запрос send | Список возможных кодов и их значений указан в таблице кодов возврата | Да |
| providerId | Integer | Поле возвращается только в случае когда код ответа провайдера для сообщения равен “ok”. На стороне клиента providerId должно сохраняться для последующего запроса статуса сообщения. | Положительные целые числа | Нет |
| code | String | Код ответа провайдера для конкретного сообщения | Список возможных кодов и их значений указан в таблице кодов возврата | Да |
Отправка текста с кнопкой¶
Запрос для отправки абоненту текста с кнопкой в качестве сообщения отличается от запроса для отправки простого текстового сообщения кодом contentType, в котором в данном случае нужно указать значение button и заполнить дополнительные атрибуты text, caption, aсtion и imageUrl (при необходимости добавить изображение) составного поля content. Данный тип сообщений поддерживается только в Viber. Возможна переотправка СМС.
Пример запроса отправки кнопки:
https://viber.devinotele.com:444/send
{
"resendSms" : "true",
"messages" :
[ {
"subject" : "Subject",
"priority" : "high",
"validityPeriodSec" : 3600,
"comment" : "comment",
"type" : "viber",
"contentType" : "button",
"content" : {
"text" : "text",
"caption" : "caption",
"action" : "http://company.com/resource",
"imageUrl" : "http://company.com/image.jpg"
},
"address" : "79250000000",
"smsText":"1sms Message text",
"smsSrcAddress":"1TEST",
"smsValidityPeriodSec":5000
} ]
}
Описание полей содержимого для отправки кнопки:
| Параметр | Тип данных | Описание | Обязательное поле |
|---|---|---|---|
| text | String | Текст сообщения. Не более 1000 символов. | Да |
| caption | String | Наименование кнопки. Не более 19 символов. | Да |
| action | String | URL страницы, на которую будет отправлен пользователь при нажатии на кнопку | Да |
| imageUrl | String | URL изображения, которое размещено на серверах Клиента | Нет |
Отправка изображения¶
Запрос для отправки абоненту изображения отличается от запроса для отправки текстового сообщения кодом contentType, в котором в данном случае нужно указать значение image и заполнить дополнительный атрибут imageUrl для составного параметра content. Переотправка не предполагается, т.к. отсутствует поле text. В случае указания resendSms = true для отправки image сервис возвращает ошибку валидации
Пример запроса отправки изображения:
https://viber.devinotele.com:444/send
{
"resendSms" : "false",
"messages" :
[ {
"subject" : "Subject",
"priority" : "high",
"validityPeriodSec" : 3600,
"comment" : "comment",
"type" : "viber",
"contentType" : "image",
"content" : {
"imageUrl" : "http://company.com/image.jpg"
},
"address" : "79250000000"
} ]
}
Описание полей содержимого отправки изображения:
| Параметр | Тип данных | Описание | Обязательное поле |
|---|---|---|---|
| image | String | URL изображения | Да |
Отправка нескольких сообщений¶
При осуществлении массовой рассылки однотипных сообщений, чтобы не дублировать данные, можно использовать секцию запроса messageCommonData, данные из которой будут использованы для всех сообщений в запросе, но могут быть переопределены ими.
Пример отправки нескольких сообщений:
https://viber.devinotele.com:444/send
{
"resendSms" : "false",
"commonData" : {
"subject" : "Subject",
"priority" : "high",
"validityPeriodSec" : 3600,
"comment" : "comment",
"type" : "viber",
"contentType" : "button",
"content" : {
"text" : "text",
"caption" : "caption",
"action" : "http://company.com/resource",
"imageUrl" : "http://company.com/image.jpg"
}
},
"messages" :
[ {
"address" : "79250000001"
},
{
"priority" : "low",
"content" : {
"text" : "Message text"
},
"address" : "79250000002"
} ]
}
В данном примере второе сообщение будет отправлено с текстом «Message text» и с более низким приоритетом.
Проверка статуса доставки сообщения¶
https://viber.devinotele.com:444/status
Данный метод предназначен для проверки статусов по ранее полученным providerId на запросы «/send» В одном запросе можно передавать не более 100 ID сообщений. Статусы по сообщениям можно запрашивать в течении 5 дней с даты отпарвки.
Пример запроса:
https://viber.devinotele.com:444/status
{
"messages" :
[3158611117333282816, 3158611117333282817, 3158611117333282818]
}
Пример ответа на запрос статуса доставки:
{
"status": "ok",
"messages": [
{
"providerId": 3158611117333282816,
"code": "ok",
"smsStates": [
{
"id": 583465579822710784,
"state": "delivered"
},
{
"id": 583465579822710785,
"state": "delivered"
}
]
},
{
"providerId": 3158611117333282817,
"code": "ok",
"status": "read",
"statusAt": "2016-08-10 15:28:50"
},
{
"providerId": 3158611117333282818,
"code": "ok",
"smsStates": [
{
"id": 583465579822710798,
"status": "delivered"
}
]
}
]
}
Описание полей ответа на запрос статуса доставки
| Параметр | Тип данных | Описание | Допустимые значения | Обязательное поле |
|---|---|---|---|---|
| status | String | Результат обработки запроса | Возможные коды ошибок и их описание определены в таблице кодов возврата | Да |
| code | String | Результат обработки запроса для конкретного сообщения с провайдеским идентификатором | Возможные коды ошибок и их описание определены в таблице кодов возврата | Да |
| smsStates | Массив (Составное поле) | Текущий статус доставки СМС сообщения. Указывается, только если была переотправка сообщения. | Нет | |
| smsStates.status | String | Код статуса доставки СМС сообщения | enqueued – сообщение находится в очереди на отправку. sent – сообщение отправлено абоненту delivered – сообщение доставлено абоненту. undelivered – сообщение отправлено, но не доставлено абоненту. | Нет |
| smsStates.id | Long | ID СМС сообщения с СМС-Центра провайдера. Если сообщение многосегментное, то будет возвращен ID для каждого сегмента сообщения и его статус. | Да | |
| Status | String | Код статуса доставки Viber сообщения. | enqueued – сообщение находится в очереди на отправку. sent – сообщение отправлено абоненту delivered – сообщение доставлено абоненту. read – сообщение просмотрено абонентом. visited абонент перешел по ссылке в сообщении. undelivered – сообщение отправлено, но не доставлено абоненту. failed – сообщение не было отправлено в результат сбоя. cancelled –отправка сообщения отменена. vp_expired – сообщение просрочено, финальный статус не получен в рамках заданного validity period | Да |
| statusAt | DateTime | Дата и время получения статуса по UTC | Да | |
| errorCode | String | Причина, по которой сообщение не было доставлено абоненту (status=undelivered) | user-blocked – абонент заблокирован not-viber-user – абонент не является пользователем Viber. | Нет |
Прием статусов с помощью callback-запросов¶
Данный метод позволяет не обращаться к API Devino каждый раз, когда требуется получить статус доставки сообщения, а обрабатывать входящие события от платформы Devino на своем внутреннем ресурсе.
При получении статуса сообщения от Viber платформа Devino отправляет HTTP-POST запрос (JSON, UTF-8) на URL сервера. В случае, если сервер возвращает ошибку или не предоставляет ответ, то платформа будет совершать повторные запросы в течение 24 часов. Ответ сообщающий о приеме должен быть 200 OK с пустым телом запроса.
Предупреждение
Внимание! Для подключения URL для приема статусов Viber-сообщений обратитесь к вашему менеджеру или напишите письмо в техническую поддержку support@devinotele.com
Пример запроса
[{
"id": 3158611117333282816,
"receivedAt": "1527861323068",
"status": "UNDELIVERED",
"errorCode": "USER_BLOCKED"
},
...
]
Описание полей запроса со статусами доставки
| Параметр | Тип данных | Описание | Допустимые значения | Обязательное поле |
|---|---|---|---|---|
| id | Long | Уникальный идентификатор сообщения на платформе | Да | |
| receivedAt | timestamp | Дата и время получения статуса | Да | |
| Status | String | Код статуса доставки Viber сообщения. | VP_EXPIRED – сообщение просрочено, финальный статус не получен в рамках заданного validity period DELIVERED – сообщение доставлено абоненту. READ – сообщение просмотрено абонентом. VISITED абонент перешел по ссылке в сообщении. UNDELIVERED – сообщение отправлено, но не доставлено абоненту. FAILED – сообщение не было отправлено в результат сбоя. | Да |
| errorCode | String | Причина, по которой сообщение не было доставлено абоненту (status=undelivered) | USER_BLOCKED – абонент заблокирован NOT_VIBER_USER – абонент не является пользователем Viber. ERROR_VP_EXPIRED - сообщение просрочено, финальный статус не получен в рамках заданного validity period BAD_DATA BAD_PARAMETERS ERROR_INSTANT_MESSAGE_TYPE_FORMAT BLOCKED_MESSAGE_TYPE UNKNOWN_ERROR - неизвестная ошибка NO_SUITABLE_DEVICE |
Нет |
Прием входящих сообщений¶
Прием входящих сообщений может использоваться для сбора обратной связи от Абонентов после рекламной/сервисной рассылки с помощью Viber.
Платформа Devino передает HTTP-POST запрос с данными в формате JSON по URL сервера, содержащий пачку новых входящих Viber-сообщений по факту обработки платформой.
Предупреждение
Внимание! Для подключения URL для приема входящих Viber-сообщений обратитесь к вашему менеджеру или напишите письмо в техническую поддержку support@devinotele.com
В случае, если сервер возвращает ошибку или не предоставляет ответ, то платформа будет совершать повторные запросы в течение 1 часа. Ответ сообщающий о приеме должен быть 200 OK с пустым телом запроса.
Пример запроса отправляемого на URL:
[
{
"id": 2,
"parentId": 1,
"receivedAt": "2007-11-29 00:00:00",
"subject": "test",
"address": "7916123456789",
"contentType": "text",
"content": "balance"
},
...
]
Описание полей запроса с входящими сообщениями
| Параметр | Тип данных | Описание | Обязательное поле |
|---|---|---|---|
| id | Long | Уникальный идентификатор входящего сообщения на платформе | Да |
| parentId | Long | Уникальный идентификатор исходящего сообщения на платформе, ответ на которое был отправлен получателем | Да |
| receivedAt | DateTime | Время получения входящего сообщения поставщиком | Да |
| subject | String | Адрес отправителя, с которого было отправлено исходящее сообщение | Да |
| address | String | Номер телефона, с которого отправлено входящее сообщение | Да |
| contentType | String | Всегда значение «text» - возможен прием только текстовых сообщений | Да |
| content | String | Текст входящего сообщения | Да |
Таблица кодов возврата¶
Коды возврата обработки запроса (status)
| Код | Описание |
|---|---|
| ok | Запрос был успешно обработан |
| error-syntax | ошибка синтаксиса |
| error-auth | ошибка аутентификации |
| error-system | системная ошибка |
| error-account-locked | аккаунт клиента заблокирован |
| error-instant-message-typeformat | неправильный формат типа исходящего сообщения |
| error-instant-message-content-type-format | неправильный формат типа содержимого сообщения |
| error-instant-message-content-image-id-format | неправильный формат идентификатора изображения для содержимого сообщения |
Коды возврата обработки сообщения в рамках запроса (code)
| Код | Описание |
|---|---|
| ok | исходящее сообщение успешно принято на отправку |
| error-system | системная ошибка |
| not-permitted | запрещено |
| error-subject-format | неправильный формат подписи |
| error-subject-unknown | указанная подпись не разрешена клиенту в конфигурации платформы провайдера |
| error-subject-not-specified | подпись не указана |
| error-address-format | неправильный формат номера абонента |
| error-address-unknown | отправка на номерную емкость, к которой относится номер абонента не разрешена клиенту в конфигурации платформы провайдера |
| error-address-not-specified | номер абонента не указан |
| error-priority-format | неправильный формат значения приоритета |
| error-comment-format | неправильный формат значения комментария |
| error-instant-message-type-format | неправильный формат типа сообщения |
| error-instant-message-type-not-specified | неправильный формат типа содержимого сообщения |
| error-content-type-format | неправильный формат содержимого сообщения |
| error-content-not-specified | содержимое сообщения не указано |
| error-validity-period-seconds-format | неправильно указано значение времени ожидания доставки |
| error-instant-message-provider-id-format | неправильный формат провайдерского идентификатора |
| error-instant-message-provider-id-duplicate | провайдерский идентификатор исходящего сообщения неуникален в рамках запроса проверки статуса |
| error-instant-message-provider-id-unknown | исходящее сообщение с данным провайдерским идентификатором не найдено на платформе провайдера |
| error-resend-sms-error | указаны поля для переотправки смс но переотправка не включена |
| error-resend-sms-validity-period-error | неверное время жизни для смс |
| error-route-not-found | нет маршрута |