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" : 54321,
            "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",
            "contentType" : "text",
            "content" : {
                "text" : "Message text"
            },
            "address" : "79250000002"
    } ]
}

В данном примере второе сообщение будет отправлено с текстом «Message text» и с более низким приоритетом.

Проверка статуса доставки сообщения

https://viber.devinotele.com:444/status

Данный метод предназначен для проверки статусов по ранее полученным providerId на запросы “/send” В одном запросе можно передавать не более 100 ID сообщений.

Пример запроса:

https://viber.devinotele.com:444/status

{
   "messages" :
       [3158611117333282816, 3158611117333282817,3158611117333282818, 3158611117333282819, 3158611117333282820 ]
}

Пример ответа на запрос статуса доставки:

{

   "status": "ok",
   "messages": [
       {
           "providerId": 3158611117333282816,
           "code": "ok",
           "smsStates": [
               {
                   "id": 583465579822710784,
                   "state": "delivered"
               },
               {
                   "id": 583465579822710785,
                   "state": "delivered"
               },
               {
                   "id": 583465579822710786,
                   "state": "delivered"
               },
               {
                   "id": 583465579822710787,
                   "state": "delivered"
               },
               {
                   "id": 583465579822710788,
                   "state": "delivered"
               },
               {
                   "id": 583465579822710789,
                   "state": "delivered"
               },
               {
                   "id": 583465579822710790,
                   "state": "delivered"
               },
               {
                   "id": 583465579822710791,
                   "state": "delivered"
               },
               {
                   "id": 583465579822710792,
                   "state": "delivered"
               },
               {
                   "id": 583465579822710793,
                   "state": "delivered"
               },
               {
                   "id": 583465579822710794,
                   "state": "delivered"
               },
               {
                   "id": 583465579822710795,
                   "state": "delivered"
               },
               {
                   "id": 583465579822710796,
                   "state": "delivered"
               },
               {
                   "id": 583465579822710797,
                   "state": "delivered"
               }
           ]
       },
       {
           "providerId": 3158611117333282818,
           "code": "ok",
           "smsStates": [
               {
                   "id": 583465579822710798,
                   "state": "delivered"
               }
           ]
       },
       {
           "providerId": 3158611117333282820,
           "code": "ok",
           "smsStates": [
               {
                   "id": 583465579822710799,
                   "state": "delivered"
               }
           ]
       },
       {
           "providerId": 3158611117333282817,
           "code": "ok",
           "status": "read",
           "statusAt": "2016-08-10 15:28:50"
       },
       {
           "providerId": 3158611117333282819,
           "code": "ok",
           "status": "read",
           "statusAt": "2016-08-10 15:28:50"
       }
   ]
}

Описание полей ответа на запрос статуса доставки

Параметр Тип данных Описание Допустимые значения Обязательное поле
status String Результат обработки запроса Возможные коды ошибок и их описание определены в таблице кодов возврата Да
code String Результат обработки запроса для конкретного сообщения с провайдеским идентификатором Возможные коды ошибок и их описание определены в таблице кодов возврата Да
smsStates Массив (Составное поле) Текущий статус доставки СМС сообщения. Указывается, только если была переотправка сообщения.   Нет
smsStates.state String Код статуса доставки СМС сообщения enqueued – сообщение находится в очереди на отправку. sent – сообщение отправлено абоненту delivered – сообщение доставлено абоненту. undelivered – сообщение отправлено, но не доставлено абоненту. Нет
smsStates.id Long ID СМС сообщения с СМС-Центра провайдера. Если сообщение многосегментное, то будет возвращен ID для каждого сегмента сообщения и его статус.   Да
Status String Код статуса доставки Viber сообщения. enqueued – сообщение находится в очереди на отправку. sent – сообщение отправлено абоненту delivered – сообщение доставлено абоненту. read – сообщение просмотрено абонентом. undelivered – сообщение отправлено, но не доставлено абоненту. failed – сообщение не было отправлено в результат сбоя. cancelled –отправка сообщения отменена. Да
statusAt DateTime Дата и время получения статуса по UTC   Да
error String Причина, по которой сообщение не было доставлено абоненту (status=undelivered) user-blocked – абонент заблокирован not-viber-user – абонент не является пользователем Viber. Нет
vp_expired   сообщение просрочено, финальный статус не получен в рамках заданного validity period    

Прием входящих сообщений

Прием входящих сообщений может использоваться для сбора обратной связи от Абонентов после рекламной/сервисной рассылки с помощью Viber.

Платформа Devino передает HTTP-POST запрос с данными в формате JSON по URL сервера, содержащий пачку новых входящих Viber-сообщений по факту обработки платформой.

Предупреждение

Внимание! Для подключения URL для приема входящих Viber-сообщений обратитесь к вашему менеджеру или напишите письмо в техническую поддержку support@devinotele.com

В случае, если сервер возвращает ошибку или не предоставляет ответ, то платформа будет совершать повторные запросы в течение 1 часа.

Пример запроса отправляемого на 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 системная ошибка
error-instant-message-client-id-not-unique клиентский идентификатор сообщения не уникален в рамках всего взаимодействия между клиентом и провайдером.
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 неверное время жизни для смс