VIBER¶

Отправка¶

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

Согласовать имя отправителя в личном кабинете.
Вызвать POST /viber/messages, передавая параметры сообщения в теле запроса и данные авторизации в заголовке.

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

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

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	Сообщение с описанием ошибки.

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

OK

{
  "result": [
    {
      "code": "OK",
      "messageId": "3702436063699518976"
    }
  ]
}

REJECTED

{
  "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	Пользователь отписался от рассылки.

Примеры коллбэков¶

DELIVERED

[
  {
    "messageId": "3597958273915257088",
    "ts": 1613411223173,
    "status": "DELIVERED",
    "errorCode": 0
  }
]

REJECTED

[
  {
    "messageId": "3597958273915257088",
    "ts": 1613411223173,
    "status": "REJECTED",
    "errorCode": 2012
  }
]