VIBER¶
Для отправки сообщений Вам понадобятся:
- учетная запись devino.online;
- согласованное имя отправителя;
- API Key для авторизации.
Отправка¶
Для отправки SMS-сообщения используйте вызов POST /viber/messages
Запрос¶
Параметры запроса¶
Параметр | Тип данных | Описание и Допустимые значения |
---|---|---|
shortenUrl (optional) |
boolean | Флаг, который сокращает длинну ссылки: если true , то ссылка будет сокращена. По умолчанию false . |
Тело запроса¶
Параметр | Тип данных | Описание и допустимые значения |
---|---|---|
from | string | Имя отправителя |
to | string | Номер телефона в международном формате |
text (optional) |
string | Текст сообщения, до 1000 символов |
image (optional) |
string | URL на изображение в форматах JPG, JPEG или PNG |
action (optional) |
string | URL или deep-link, который откроется по нажатию на кнопку |
caption (optional) |
string | Текст кнопки, не более 30 UTF-8 символов |
validity (optional) |
integer | Срок жизни сообщения в секундах, по умолчанию сутки |
priority (optional) |
priority | Приоритет отправки сообщения |
scheduledTime (optional) |
string | Время по UTC, в которое необходимо отправить сообщение Формат: YYYY-MM-DD hh:mm:ss |
callbackUrl (optional) |
string | URL, на который будет отправлено уведомление об изменении статуса сообщения. Валидный URL со схемой http или https |
options (optional) |
object | Валидный JSON, который будет передан в уведомлении об изменении статуса |
Помимо этого для каждого сообщения из запроса применяются следующие проверки:
validity
- Срок жизни сообщения в секундах- Минимальное значение: 15 Максимальное значение: 1209600, 14 дней По умолчанию: 86400, 1 сутки
priority
- Приоритет отправки сообщения-
LOW
иMEDIUM
- низкий и средний приоритеты, по умолчаниюLOW
. Обычно используются для отправки рекламы.HIGH
- рекомендуем использовать такой приоритет для сообщений, использующих шаблоны.REALTIME
- максимально возможный приоритет. Используйте его, когда отвечаете на входящее сообщение от пользователя.При использовании любого другого значения сообщение будет отклонено.
Возможные комбинации текста, кнопок и картинок¶
Не смотря на то, что параметры text
, action
, caption
и image
в описании являются необязательными,
необходимо указать хотя бы один или несколько в соответствии со следующим списком возможных комбинаций:
text
image
text
,action
,caption
text
,action
,caption
,image
Ответ¶
Параметр | Тип данных | Описание и допустимые значения |
---|---|---|
code | string | Указывает на результат обработки сообщения 1. OK - Успешно обработано 2. REJECTED - Произоошла ошибка во время обработки запроса |
reasons (optional) |
Array[String, String] | Массив ошибок, произошедших во время обработки сообщения Указывается только при code=REJECTED |
reasons.key | string | Код ошибки |
reasons.ref | string | Ссылка на параметр, в котором произошла ошибка |
messageId (optional) |
string | Идентификатор сообщения Указывается только при code=OK |
Примеры запросов¶
curl -X POST \
-H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
-H 'Content-Type: application/json' \
-d '{
"messages": [
{
"from": "MyCompany",
"to": "79034567890",
"text": "Code: 1234"
}
]
}' https://api.devino.online/viber/messages
Ответ
{
"result": [
{
"code": "OK",
"messageId": "3482512350952730368"
}
]
}
curl -X POST \
-H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
-H 'Content-Type: application/json' \
-d '{
"messages": [
{
"from": "MyCompany",
"to": "79034567890",
"text": "Code: 1234",
"image": "https://cdn.mycompany.com/viber.png",
"action": "https://mycompany.com/promo?code=1234",
"caption": "Activate!"
}
]
}' https://api.devino.online/viber/messages
Ответ
{
"result": [
{
"code": "OK",
"messageId": "3482512350952730368"
}
]
}
Webhooks¶
Входящие уведомления¶
Как подключить
Для получения входящих Viber-сообщений от пользователей свяжитесь с менеджером компании или обратиться в техническую поддержку, сообщив URL веб-сервера обработки входящих уведомлений.
Пример запроса
{
"incomingMessageId": "3777714415805253122",
"to": "MyCompany",
"from": "79101111111",
"text": "Входящее сообщение",
"ts": "1587721283000"
}
Параметры
Параметр | Тип данных | Описание |
---|---|---|
incomingMessageId | string | Индификатор сообщения |
to | string | Адрес получателя |
from | string | Адрес отправителя |
text | string | Текст сообщения |
ts | string | Timestamp с миллисекундами получения сообщения |
Уведомления об изменении статусов¶
При формировании статуса сообщения будет отправлен POST-запрос на URL, указанный при отправке сообщения
в параметре callbackUrl
. В ответ на запрос ожидается 200 OK
.
В случае, если на запрос вернётся 500 Internal Error
, то будут предприниматься попытки доставки статуса 5 раз с интервалом в минуту.
[
{
"messageId": "3597958273915257088",
"ts": 1613411223173,
"status": "DELIVERED",
"errorCode": 0
}
]
[
{
"messageId": "3597958273915257088",
"ts": 1613411436590,
"status": "CLICKED",
"errorCode": 0,
"ip": "127.0.0.1",
"browser": "Chrome 8",
"os": "Windows 10",
"userAgent": "WINDOWS_10-CHROME8"
}
]
[
{
"messageId": "3597958273915257088",
"ts": 1613411223173,
"status": "REJECTED",
"errorCode": 2012
}
]
Параметры
Параметр | Тип данных | Статус | Описание и Допустимые значения |
---|---|---|---|
messageId | long | any | Уникальный идентификатор сообщения на платформе |
ts | int | any | Указывает на время создания объекта status |
status | enum | any | Код статуса доставки Viber сообщения Подробнее см. раздел Возможные статусы |
errorCode (optional) |
int | rejected undeliverable |
Причина, по которой сообщение не было доставлено |
ip (optional) |
string | clicked opened |
IP-адрес пользователя |
browser (optional) |
string | clicked opened |
Браузер пользователя |
os (optional) |
string | clicked opened |
Операционная система пользователя |
userAgent (optional) |
string | any | Заголовок User-Agent |
Возможные статусы¶
Параметр | Описание |
---|---|
SCHEDULED | Сообщение было отложено |
ENROUTE | Сообщение находится в очереди на отправку |
SENT | Было отправлено в сеть поставщика |
DELIVERED | Сообщение доставлено абоненту |
EXPIRED | Сообщение было просрочено по сроку жизни |
SEEN | Сообщение было прочитано |
CLICKED | Был переход по ссылке из сообщения |
UNDELIVERABLE | Сообщение невозможно доставить, причина в коде ошибки |
REJECTED | Сообщение было отклонено Viber или Devino |
UNKNOWN | Произошла неизвестная ошибка |
SUBSCRIBED | Пользователь подписался |
UNSUBSCRIBED | Пользователь отписался |