Viber HTTP API¶

Общие сведения¶

Сервис позволяет отправлять сообщения Viber-мессенджера через платформу Devino Telecom. Можно производить пакетные рассылки, отправлять транзакционные сообщения, а также осуществлять переотправку SMS в случае недоставки Viber-сообщений.

Внимание

Для использования данного вида интеграции необходимо обратиться к менеджеру компании либо в техническую поддержку для настройки доступа.

Данным методом можно отправлять не более 100 сообщений.

API поддерживает базовую авторизацию через заголовок Authorization.

В заголовке запроса необходимо передать логин и пароль из личного кабинета в формате login:password в кодировке base64. Например:

Authorization: Basic dGVzdGVyOjExMTExMQ==

Точка подключения:

https://viber.devinotele.com:444

Отправка сообщения¶

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

Метод отправляет различные типы сообщений на указанные номера получателя. Параметры сообщения и адреса получателей передаются в теле запроса в формате JSON.

Типы сообщений, допустимые к отправке:

Тип сообщения	Возможность переотправки	contentType
Текст + кнопка	Да	button
Текст + картинка + кнопка	Да	button
Текст	Да	text
Картинка	Нет	image

Отправка текстового сообщений¶

Запрос на отправку текстового сообщения собирается с указанием contentType: "text". Возможна переотправка по SMS.

Параметры тела запроса отправки сообщения¶

Параметр	Тип данных	Допустимые значения	Описание
resendSms	boolean	`true` – переотправка включена `false` – переотправка отключена	Признак переотправки сообщения. Если параметр не указан, переотправка отключена
subject обязательный	string	Все подписи предварительно должны регистрироваться на платформе провайдера. Длина подписи не более 11 символов	Подпись сообщения, которая отображается в мессенджере получателя
priority обязательный	string	`low` – низкий приоритет `normal` – нормальный приоритет `high` – высокий приоритет `realtime` – высочайший приоритет	Приоритет сообщения. Используется для управления оперативностью доставки сообщения получателю. Для транзакционных сообщений приоритет должен быть высоким, для рекламы низким.
validityPeriodSec обязательный	integer	`30` – `86400`.	Время ожидания доставки Viber-сообщения в секундах
allowUseSessions	boolean	`true` – Использовать режим сессии `false` – Не использовать режим сессии(по умолчанию)	Включает или отключает сессионный режим Внимание!!! Для активации режима сессий требуется выполнение определенных условий, описанных в разделе Сессии
comment	string		Произвольный текстовый комментарий.
type обязательный	string	`viber` – Viber messenger	Тип отправляемого сообщения. Определяет канал, который используется для доставки сообщения на мобильный телефон получателя
contentType обязательный	string	`text` – текстовое сообщение `image` – изображение `button` – гиперссылка в виде кнопки	Тип содержимого сообщения.
content обязательный	Составной тип	Определяется значением contentType	Содержимое сообщения. Зависит от значения contentType
address обязательный	Address	Номер телефона получателя в международном формате (в формате E.164)	Номер телефона получателя, на который отправляется сообщение
smsText обязательный	string		Текст SMS-сообщения
smsSrcAddress обязательный	string	Адрес отправителя SMS должен быть согласован в личном кабинете. Длина адреса может быть не более 11 латинский символов или цифр	Адрес отправителя SMS-сообщения
smsValidityPeriodSec обязательный	integer	`60` – `86400`	Время жизни SMS-сообщения в секундах. Если параметр не указан, то время жизни будет выставлено по умолчанию SMS-центром оператора

Пример запроса на отправку текстового сообщения¶

С переотправкой в SMS

{
    "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
        } 
    ]
}

С активацией Viber сессий

{
    "messages" : [ 
        {
            "subject" : "Subject",
            "priority" : "high",
            "validityPeriodSec" : 3600,
            "allowUseSessions": true,
            "comment" : "comment",
            "type" : "viber",
            "contentType" : "text",
            "content" : {
                    "text" : "Message text"
                },
            "address" : "79250000000",
            "smsText":"1sms Message text",
            "smsSrcAddress":"1TEST",
            "smsValidityPeriodSec":5000
        } 
    ]
}

Параметры ответа на запрос отправки сообщения¶

Параметр	Тип данных	Допустимые значения	Описание
status	string	Список возможных кодов и их значений указан в таблице кодов возврата	Статус ответа провайдера на запрос отправки сообщения
providerId	integer	Положительные целые числа	Параметр возвращается только если код ответа провайдера для сообщения равен `ok`. На стороне клиента providerId должен сохраняться для последующего запроса статуса сообщения
code	string	Список возможных кодов и их значений указан в таблице кодов возврата	Код ответа провайдера для конкретного сообщения

Пример ответа¶

{
    "status" : "ok",
    "messages": [ 
        {
            "providerId" : 3158611117333282816,
            "code" : "ok"
        } 
    ]
}

Отправка текста с кнопкой¶

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

Запрос для отправки получателю текста с кнопкой в качестве сообщения отличается от запроса для отправки простого текстового сообщения. В данном случае в параметре contentType следует указать значение button и заполнить дополнительные атрибуты text, caption, action и imageUrl (при необходимости добавить изображение) составного поля content. Данный тип сообщений поддерживается только в Viber. Возможна переотправка по SMS.

Параметры содержимого для отправки кнопки¶

Параметр	Тип данных	Описание
text обязательный	string	Текст сообщения. Не менее 2 и не более 1000 символов
caption обязательный	string	Текст кнопки. Не более 30 символов
action обязательный	string	URL для перехода при нажатии на кнопку
imageUrl	string	URL изображения, которое размещено на сервере клиента

Пример запроса отправки кнопки¶

{
    "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
        }
    ]
}

Отправка изображения¶

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

Запрос для отправки получателю изображения отличается от запроса для отправки текстового сообщения. В данном случае в параметре contentType следует указать значение image и заполнить дополнительный атрибут imageUrl для составного параметра content. Переотправка не предполагается, так как отсутствует поле text. В случае указания resendSms = true для отправки image сервис возвращает ошибку валидации.

Параметры содержимого отправки изображения¶

Параметр	Тип данных	Описание
image обязательный	string	URL изображения, которое размещено на сервере клиента

Пример запроса отправки изображения¶

{
    "resendSms" : "false",
    "messages" : [ 
        {
            "subject" : "Subject",
            "priority" : "high",
            "validityPeriodSec" : 3600,
            "comment" : "comment",
            "type" : "viber",
            "contentType" : "image",
            "content" : {
            "imageUrl" : "http://company.com/image.jpg"
                },
            "address" : "79250000000"
        }
    ]
}

Отправка нескольких сообщений¶

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

Чтобы не дублировать данные, при осуществлении массовой рассылки однотипных сообщений можно использовать секцию запроса messageCommonData. Данные оттуда будут использованы для всех сообщений в запросе, но могут быть переопределены этими сообщениями.

Пример отправки нескольких сообщений¶

{
    "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 и с более низким приоритетом.

Сессии¶

Сессии в Viber позволяют общаться с пользователями по фиксированной цене за определенное время и количество сообщений.

Для открытия сессии требуется выполнение всех трех условий:

Пользователю были отправлены сообщения типов текст или изображение или файл.
При отправке сообщения, в объекте сообщения указан параметр "allowUseSessions": true.
От пользователя пришло входящее сообщение.

Примечание

Вы можете отправить до 5 последовательных сообщений сеансового типа без ответа пользователя

Для окончания сессии требуется выполнение одного из трех условий:

С момента начала сессии прошло 24 часа.
Пользователю было отправлено больше 10 сообщений подряд.
Пользователю было отправлено больше 60 сообщений в рамках одной сессии.

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

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

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

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

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

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

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

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

{
    "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"
                }
            ]
        }
    ]
}

Прием статусов с помощью callback-запросов¶

Данный метод позволяет не запрашивать статус сообщения после доставки, а обрабатывать входящие события от платформы Devino Telecom на своем внутреннем ресурсе.

При получении статуса сообщения от Viber платформа Devino Telecom отправляет HTTP-POST запрос (JSON, UTF-8) на URL сервера. Если сервер возвращает ошибку или не возвращает ответ, платформа будет совершать повторные запросы в течение 24 часов. Ответ, сообщающий о приеме, должен быть 200 OK с пустым телом запроса.

Внимание

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

Параметры запроса со статусами доставки¶

Параметр	Тип данных	Допустимые значения	Описание
id	Long		Уникальный ID сообщения на платформе
receivedAt	timestamp		Дата и время получения статуса
Status	string	`VP_EXPIRED` – сообщение просрочено, финальный статус не получен в рамках заданного validityPeriod `DELIVERED` – сообщение доставлено получателю `READ` – сообщение просмотрено получателем `VISITED` получатель перешел по ссылке в сообщении `UNDELIVERED` – сообщение отправлено, но не доставлено получателю `FAILED` – сообщение не было отправлено в результате сбоя	Код статуса доставки Viber-сообщения.
errorCode	string	`USER_BLOCKED` – получатель заблокирован `NOT_VIBER_USER` – получатель не является пользователем Viber `ERROR_VP_EXPIRED` - сообщение просрочено, финальный статус не получен в рамках заданного validityPeriod `BAD_DATA` `BAD_PARAMETERS` `ERROR_INSTANT_MESSAGE_TYPE_FORMAT` `BLOCKED_MESSAGE_TYPE` `UNKNOWN_ERROR` - неизвестная ошибка `NO_SUITABLE_DEVICE`	Причина, по которой сообщение не было доставлено получателю (`status=undelivered`)

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

[
    {
        "id": 3158611117333282816,
        "receivedAt": "1527861323068",
        "status": "UNDELIVERED",
        "errorCode": "USER_BLOCKED"
    },
    ...
]

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

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

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

Внимание

Для подключения URL для приема входящих Viber-сообщений обратитесь к менеджеру компании или в техническую поддержку

Если сервер возвращает ошибку или не предоставляет ответ, платформа будет совершать повторные запросы в течение 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	Уникальный ID входящего сообщения на платформе
parentId обязательный	Long	Уникальный ID исходящего сообщения на платформе, ответ на которое был отправлен получателем
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	Неправильный формат ID изображения для содержимого сообщения

Коды возврата обработки сообщения в рамках запроса (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	Неправильный формат ID провайдера
error-instant-message-provider-id-duplicate	ID провайдера исходящего сообщения неуникален в рамках запроса проверки статуса
error-instant-message-provider-id-unknown	Исходящее сообщение с данным ID провайдера не найдено на платформе провайдера
error-resend-sms-error	Указаны поля для переотправки SMS, но переотправка не включена
error-resend-sms-validity-period-error	Неверный срок жизни для SMS
error-route-not-found	Не найден маршрут отправки SMS