Перейти к содержанию

VIBER

Отправка

Для отправки сообщений в Viber необходимо:

Параметры запроса

Параметр Тип данных Описание
shortenUrl
(optional)
boolean

При true сокращает длину ссылок в тексте сообщения. Если пользователь перешел по ссылке, система отправляет коллбэк со статусом CLICKED.

К примеру, если параметр активен, ссылка https://www.example-url.com/my-example-param... будет преобразована в ссылку вида https://clickdo.integrationapi.net/link-hash.

По умолчанию false.

Тело запроса

Параметр Тип данных Описание
messages array[Message] Массив сообщений.

Message

Параметр Тип данных Описание
from string

Имя отправителя, которое используется при отправке сообщения.

Можно использовать только те имена, которые доступны пользователю.

to string Номер телефона в международном формате, согласно стандарту E.164.
text
(optional)
string

Текст сообщения в кодировке UTF-8.

Стандартное число символов - не более 1000.
Максимальное число символов - 2000.

Если стандартное число символов в Viber-сообщении превышает 1000 символов, сообщение будет поделено на сегменты и доставлено последовательно, с сохранением смыслового содержания.

image
(optional)
string URL изображения в форматах JPG, JPEG или PNG.
fileType
(optional)
string

Тип отправляемого файла.

Максимальный размер файла - 200 MB. В параметре указывается тип файла без точки - например, docx, pdf и так далее.

Можно отправлять следующие типы файлов:

○ Документы: .doc, .docx, .rtf, .dot, .dotx, .odt ,odf, .fodt, .txt, .info
○ PDF: .pdf, .xps, .pdax, .eps
○ Таблицы: .xls, .xlsx, .ods, .fods, .csv, .xlsm, .xltx

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
Максимальное значение: 1209600, 14 дней
По умолчанию: 86400, 1 сутки

priority
(optional)
string

Приоритет отправки сообщения.

LOW и MEDIUM - низкий и средний приоритеты, по умолчанию LOW. Обычно используются для отправки рекламы.
HIGH - рекомендуем использовать такой приоритет для сообщений, использующих шаблоны.
REALTIME - максимально возможный приоритет. Используйте его, когда отвечаете на входящее сообщение от пользователя.
При использовании любого другого значения сообщение будет отклонено.

scheduledTime
(optional)
integer

Запланированное UTC время отправки сообщения.

Формат: YYYY-MM-DD hh:mm:ss

callbackUrl
(optional)
string

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

Любой валидный URL со схемой HTTP или HTTPS.

options
(optional)
object

Данные, которые будут указаны в коллбэке со статусом сообщения.

Любой массив вида "key":
{ "key1": "value1", "key2": "value2" }

Чтобы начать сессию с пользователем, в данном объекте должен быть указан параметр allowUseSessions (bool). Если параметр allowUseSessions будет равен true, система сможет инициировать сессию при выполнении остальных условий.

Внимание

Для корректного отображения контента в чате, во всех ссылках на файлы и изображения должен использоваться протокол 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. OK - успешно обработано.
2. REJECTED - произошла ошибка во время обработки запроса.

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 позволяют общаться с пользователями по фиксированной цене за определенное время и количество сообщений.

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

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

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

  1. С момента начала сессии прошло 24 часа.
  2. Пользователю было отправлено больше 10 сообщений подряд.
  3. Пользователю было отправлено больше 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
  }
]