VIBER¶
Отправка¶
Для отправки сообщений в Viber необходимо:
- Согласовать имя отправителя в личном кабинете.
- Вызвать POST /viber/messages, передавая параметры сообщения в теле запроса и данные авторизации в заголовке.
Параметры запроса¶
Параметр | Тип данных | Описание |
---|---|---|
shortenUrl (optional) |
boolean | При К примеру, если параметр активен, ссылка По умолчанию |
Тело запроса¶
Параметр | Тип данных | Описание |
---|---|---|
messages | array[Message] | Массив сообщений. |
Message¶
Параметр | Тип данных | Описание |
---|---|---|
from | string | Имя отправителя, которое используется при отправке сообщения. Можно использовать только те имена, которые доступны пользователю. |
to | string | Номер телефона в международном формате, согласно стандарту E.164. |
text (optional) |
string | Текст сообщения в кодировке UTF-8. Стандартное число символов - не более 1000. Если стандартное число символов в Viber-сообщении превышает 1000 символов, сообщение будет поделено на сегменты и доставлено последовательно, с сохранением смыслового содержания. |
image (optional) |
string | URL изображения в форматах JPG, JPEG или PNG. |
fileType (optional) |
string | Тип отправляемого файла. Максимальный размер файла - 200 MB. В параметре указывается тип файла без точки - например, Можно отправлять следующие типы файлов: ○ Документы: .doc, .docx, .rtf, .dot, .dotx, .odt ,odf, .fodt, .txt, .info |
fileName (optional) |
string | Название отправляемого файла с указанием расширения. Например, yourfile.docx . |
thumbnail (optional) |
string | Ссылка на превью видео в формате изображения. |
duration (optional) |
integer | Продолжительность видео в секундах. |
fileSize (optional) |
integer | Размер загружаемого видео в мегабайтах (MB ). |
caption (optional) |
string | Текст кнопки, не более 30 символов в кодировке UTF-8. |
action (optional) |
string | URL или deep link, на который перейдет пользователь после нажатия на кнопку. Также параметр используется для указания URL прикрепленного видео или файла. |
validity (optional) |
integer | Срок жизни сообщения в секундах. Минимальное значение: 15 |
priority (optional) |
string | Приоритет отправки сообщения.
|
scheduledTime (optional) |
integer | Запланированное UTC время отправки сообщения. Формат: |
callbackUrl (optional) |
string | URL, на который система будет отправлять уведомления об изменениях статуса сообщения. Любой валидный URL со схемой |
options (optional) |
object | Данные, которые будут указаны в коллбэке со статусом сообщения. Любой массив вида Чтобы начать сессию с пользователем, в данном объекте должен быть указан параметр |
Внимание
Для корректного отображения контента в чате, во всех ссылках на файлы и изображения должен использоваться протокол HTTPS
.
Возможные комбинации параметров¶
Несмотря на то, что некоторые параметры запроса являются необязательными, данные параметры формируют типы данных, из которых состоит сообщение внутри Viber. В запросе необходимо использовать хотя бы один из этих типов данных в соответствии со списком:
- Текст:
text
- Изображение:
image
- Текст с кнопкой:
text
,caption
,action
- Текст с изображением и кнопкой:
text
,image
,caption
,action
- Прикрепляемый файл:
fileType
,fileName
,action
- Видео:
thumbnail
,duration
,fileSize
,action
- Видео с текстом:
text
,thumbnail
,duration
,fileSize
,action
- Видео с текстом и кнопкой:
text
,thumbnail
,duration
,fileSize
,caption
,action
(в данном случаеaction
будет означать URL прикрепленного видео)
Примеры запросов¶
{
"messages": [
{
"from": "MyCompany",
"to": "79034567890",
"text": "Code: 1234",
"image": "https://cdn.mycompany.com/viber.png",
"action": "https://mycompany.com/promo?code=1234",
"caption": "Activate!"
}
]
}
{
"messages": [
{
"from": "MyCompany",
"to": "79034567890",
"thumbnail": "https://myvideo.com/thumbnail.jpg",
"duration": 433,
"fileSize": 32,
"action": "https://myvideosource.com/video.mp4"
}
]
}
{
"messages": [
{
"from": "MyCompany",
"to": "79034567890",
"fileType": "docx",
"fileName": "myfile.docx",
"action": "https://myfilesource.com/myfile.docx"
}
]
}
Параметры ответа¶
Параметр | Тип данных | Описание |
---|---|---|
code | string | Указывает на результат обработки сообщения. 1. |
messageId | string | ID сообщения. Указывается только при "code": "OK" . |
reasons | array | Массив ошибок, произошедших во время обработки сообщения. Указывается только при "code": "REJECTED" . |
reasons.key | string | Код ошибки. |
reasons.ref | string | Ссылка на параметр, в котором произошла ошибка. |
reasons.defaultMessage | string | Сообщение с описанием ошибки. |
Примеры ответов¶
{
"result": [
{
"code": "OK",
"messageId": "3702436063699518976"
}
]
}
{
"result": [
{
"code": "REJECTED",
"messageId": null,
"reasons": [
{
"key": "text.image.file.or.video.must.be.not.null",
"defaultMessage": "#text.image.file.or.video.must.be.not.null; Field text,image,file or video must be not null"
},
{
"key": "illegal.combination",
"ref": "contentCombinationValid",
"defaultMessage": "#illegal.combination;"
}
]
}
]
}
Входящие сообщения¶
Как подключить
Для получения входящих Viber-сообщений от пользователей обратитесь к менеджеру компании или в техническую поддержку. Также будет необходимо сообщить URL веб-сервера для обработки входящих сообщений.
Параметры¶
Параметр | Тип данных | Описание |
---|---|---|
incomingMessageId | string | ID входящего сообщения. |
to | string | Имя получателя. |
from | string | Номер телефона отправителя. |
text | string | Текст сообщения. |
contentUrl | string | Ссылка на файл, прикрепленный к сообщению. Генерируется внутри Viber и действует 7 суток. |
contentName | string | Название файла, прикрепленного к сообщению. |
ts | string | Время получения сообщения (timestamp) в миллисекундах. |
Примеры¶
{
"incomingMessageId": "3777714415805253122",
"to": "MyCompany",
"from": "79101111111",
"text": "Входящее сообщение",
"ts": "1587721283000"
}
{
"incomingMessageId": "3777714415805253122",
"to": "MyCompany",
"from": "79101111111",
"contentUrl": "https://dl-media.viber.com/20/media/42.pdf",
"contentName": "userfile.pdf",
"ts": "1587721283000"
}
{
"incomingMessageId": "3777714415805253122",
"to": "MyCompany",
"from": "79101111111",
"contentUrl": "https://dl-media.viber.com/18/media/234.mp4",
"contentName": "uservideo.mp4",
"ts": "1587721283000"
}
Сессии¶
Сессии в Viber позволяют общаться с пользователями по фиксированной цене за определенное время и количество сообщений.
Для открытия сессии требуется выполнение трех условий:
- Пользователю были отправлены сообщения типов текст или изображение.
- При отправке сообщения, в объекте
options
указан параметр"allowUseSessions" = true
. - От пользователя пришло входящее сообщение.
Для окончания сессии требуется выполнение одного из трех условий:
- С момента начала сессии прошло 24 часа.
- Пользователю было отправлено больше 10 сообщений подряд.
- Пользователю было отправлено больше 60 сообщений в рамках одной сессии.
Коллбэки¶
Как подключить
Для настройки коллбэков со статусами сообщений необходимо обратиться к менеджеру компании или в техническую поддержку.
Возможные статусы¶
Код | Описание |
---|---|
ACCEPTED | Сообщение было принято на доставку. |
SCHEDULED | Сообщение было отложено. |
ENROUTE | Сообщение находится в очереди на отправку. |
SENT | Сообщение отправлено в сеть оператора. |
DELIVERED | Сообщение доставлено абоненту. |
EXPIRED | Истек срок жизни сообщения. |
UNDELIVERABLE | Сообщение невозможно доставить. |
SEEN | Сообщение было прочитано. |
CLICKED | Был переход по ссылке из сообщения. |
DELETED | Сообщение было удалено. |
REJECTED | Сообщение было отклонено Viber или Devino.Online. |
UNKNOWN | Произошла неизвестная ошибка. |
SUBSCRIBED | Пользователь подписался на рассылку. |
UNSUBSCRIBED | Пользователь отписался от рассылки. |
Примеры коллбэков¶
[
{
"messageId": "3597958273915257088",
"ts": 1613411223173,
"status": "DELIVERED",
"errorCode": 0
}
]
[
{
"messageId": "3597958273915257088",
"ts": 1613411223173,
"status": "REJECTED",
"errorCode": 2012
}
]