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

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

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

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

DELIVERED

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

REJECTED

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

Детализация

Для получения детальных сведений об отправленных сообщениях необходимо вызвать GET /viber-stat/statistics/detail, передавая параметры фильтров и данные авторизации в заголовке.

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

Параметр	Тип данных	Описание
limit	integer	Количество сообщений в результатах поиска.
offset	integer	Смещение результатов поиска. То есть, к примеру, если в параметре будет указано число 5, полученный массив сообщений будет отображаться, начиная с 5 позиции.
taskId (optional)	integer	ID рассылки, по которой нужно получить детализацию. Можно узнать при создании сценария рассылки. Используется в обязательной комбинации параметров.
triggerId (optional)	integer	ID триггера рассылки. Можно узнать при получении сценария рассылки. Используется в обязательной комбинации параметров.
dateTimeFrom (optional)	datetime	Дата начала поиска сообщений. Используется в обязательной комбинации параметров. Формат YYYY-MM-DD+hh:mm:ss.
dateTimeTo (optional)	datetime	Дата окончания поиска сообщений. Используется в обязательной комбинации параметров. Формат YYYY-MM-DD+hh:mm:ss.
messageIds (optional)	array[integer]	ID сообщений, по которым нужно получить детализацию. Используется в обязательной комбинации параметров.
countryId (optional)	integer	ID страны.
mogId (optional)	integer	ID группы мобильных операторов.
order (optional)	string	В каком порядке выводить результаты запроса. Возможные значения: ○ ASC - в возрастающем порядке. ○ DESC - в убывающем порядке.
orderField (optional)	string	Поле, по которому будут отсортированы результаты запроса.
outFields (optional)	array[string]	Поля в результатах поиска. Неуказанные в этом параметре поля будут исключены.
recipient (optional)	string	Номер телефона получателя.
searchText (optional)	string	Поиск ключевого слова в текстах сообщений. Доступен поиск одного слова на английском языке.
sourceAddress (optional)	string	Согласованное имя отправителя.
status (optional)	string	Статус сообщений в результатах поиска. Возможные значения: ○ DELIVERED - сообщение доставлено получателю. ○ IN_PROGRESS - сообщение находится в процессе отправки. ○ READ - сообщение было прочитано получателем. ○ REDIRECT - получатель перешел по ссылке в сообщении. ○ REJECTED - сообщение было отклонено оператором или Devino.Online. ○ UNDELIVERED - сообщение не доставлено.
timeOffset (optional)	integer	Часовой пояс получателя. Формат - смещение в минутах, например, 180 для Москвы (GMT+3).
userId (optional)	integer	ID пользователя, проводившего рассылку.

Комбинации параметров

Для корректной работы метода в запросе необходимо использовать одну из этих комбинаций параметров в соответствии со списком:

• ID рассылки: taskId
• ID рассылки и триггера: taskId, triggerId
• Даты начала и окончания поиска сообщений: dateTimeFrom, dateTimeTo
• ID рассылки, триггера; даты начала и окончания поиска сообщений: taskId, triggerId, dateTimeFrom, dateTimeTo
• ID сообщений: messageIds

Поля для параметров orderField и outFields

Используются в параметрах orderField для сортировки результатов поиска и outFields для фильтрации полей.

Название поля	Описание
ACTION_URL	URL или deep link, на который перешел пользователь после нажатия на кнопку в сообщении. Также параметр используется для указания URL прикрепленного видео или файла.
BUTTON_CAPTION	Текст кнопки.
CALLBACK_DATA	Данные, которые указаны в коллбэке со статусом сообщения.
CALLBACK_URL	URL, на который система отправляет уведомления об изменениях статуса сообщения.
CLIENT_ACTION_URL	URL или deep link, переданный в ответном сообщении от получателя.
COMPANY_ID	ID компании.
COMPANY_NAME	Название компании.
CONTACT_ID	ID получателя из списка контактов.
COUNTRY_ID	ID страны.
COUNTRY_NAME	Название страны.
ERROR_CODE	Код ошибки.
EVENT_DATE_TIME	Дата и время последнего обновления статуса сообщения.
IMAGE_URL	Ссылка на изображение, прикрепленное к сообщению.
MESSAGE_ID	ID сообщения.
MOG_ID	ID группы мобильных операторов.
MOG_NAME	Название группы мобильных операторов.
MO_ID	ID мобильного оператора.
MO_NAME	Название мобильного оператора.
PRICE	Стоимость сообщения.
PROVIDER_MESSAGE_ID	ID сообщения у оператора.
RECIPIENT	Номер телефона получателя.
RECIPIENT_TIME_ZONE_OFFSET	Часовой пояс получателя.
ROUTE_ID	ID маршрута, по которому было отправлено сообщение.
SENT_DATE_TIME	Дата и время отправки.
SOURCE_ADDRESS	Имя отправителя.
STATUS	Статус сообщения.
TASK_ID	ID рассылки.
TASK_NAME	Название рассылки.
TASK_TYPE	Тип рассылки.
TEXT	Текст сообщения.
TRAFFIC	Тип трафика. Возможные значения: ○ ADVERTISING - рекламный трафик. ○ AUTHORIZATION - авторизационный трафик. ○ INCOMING - входящий трафик. ○ SERVICE - сервисный трафик. ○ TRANSACTIONAL - транзакционный трафик.
TRIGGER_CONTACT_GROUP	Название списка контактов, по которому проходила рассылка.
TRIGGER_SEGMENT	Название сегмента списка контактов, по которому проходила рассылка.
IS_CONTACT_GROUP_DELETED	Удален ли список контактов, контакту которого было отправлено сообщение.
IS_TRIGGER_SEGMENT_DELETED	Удален ли сегмент списка контактов, контакту которого было отправлено сообщение.
TRIGGER_ID	ID триггера рассылки.
USER_ID	ID пользователя, отправившего сообщения.
USER_LOGIN	Логин пользователя, отправившего сообщения.

Примеры запросов

С датами

curl -X GET https://api.devino.online/viber-stat/statistics/detail?dateTimeFrom=2022-10-06+13:45:30&dateTimeTo=2023-02-06+13:45:30&limit=20&offset=1
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \

С ID рассылки и триггера

curl -X GET https://api.devino.online/viber-stat/statistics/detail?taskId=8742&triggerId=2312&limit=20&offset=1
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \

Параметры ответа

Параметр	Тип данных	Описание
data	array[object]	Массив объектов с детальной информацией по каждому сообщению. Параметры определяются полями, которые были заданы в изначальном запросе.
size	integer	Количество элементов на странице и сообщений в результатах поиска. Задается параметром limit.
offset	integer	Смещение результатов поиска. То есть, к примеру, если в параметре будет указано число 5, полученный массив сообщений будет отображаться, начиная с 5 позиции.
number	integer	Номер полученной страницы. Определяется параметром offset. ○ Если значение параметра offset будет 0 при любом значении параметра limit, то номер полученной страницы будет 1. ○ Если offset будет больше 0, но меньше, чем значение параметра limit, номер страницы будет 2. Например, при "offset": 5 и "limit": 10, значение параметра number будет 2. ○ Если offset будет больше чем limit, то номер страницы будет определяться целочисленным делением offset на limit плюс 1 (offset / limit + 1). Например, при "offset": 1000 и "limit": 50, значение параметра number будет 21 (1000 / 50 + 1 = 21).
pageExists	boolean	Существует ли отображаемая страница.
total	integer	Общее количество сообщений, по которым можно получить детализацию.
pages	integer	Общее количество страниц, по которым можно получить детализацию. Определяется целочисленным делением параметра total на limit (total / limit).
more	boolean	Индикатор: существуют ли страницы после текущей, указанной в параметре number.

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

{
  "result": {
    "offset": 1000,
    "number": 21,
    "size": 50,
    "pageExists": true,
    "data": [
      {
        "messageId": "234567865432456787634",
        "sentDateTime": "2022-12-14 05:55:32",
        "sourceAddress": "sendersName",
        "recipient": "79001112233",
        "status": "DELIVERED",
        "eventDateTime": "2022-12-14 05:54:52",
        "companyId": 234,
        "companyName": "MyCompany",
        "userId": 88,
        "userLogin": "79991112233",
        "countryId": 12,
        "countryName": "Russia",
        "mogId": 0,
        "mogName": "MOG",
        "moName": "MO",
        "moId": 234,
        "price": "1.0000",
        "text": "Hello",
        "errorCode": 0,
        "traffic": "ADVERTISING",
        "isContactGroupDeleted": "No",
        "recipientTimeZoneOffset": "180"
      },
      ...
    ],
    "more": true,
    "pages": 100,
    "total": 1000
  }
}

Статистика сообщений

Для получения общей статистики по статусам сообщений необходимо вызвать GET /viber-stat/statistics/of-group, передавая параметры фильтров и данные авторизации в заголовке.

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

Параметр	Тип данных	Описание
groupBy	string	Группировка результатов: ○ NONE - без группировки ○ YEAR - по годам ○ MONTH - по месяцам ○ WEEK - по неделям ○ DAY - по дням ○ HOUR - по часам
startDate	datetime	Дата начала периода сбора статистики. Формат - YYYY-MM-DDThh%3Amm%3Ass.
endDate	datetime	Дата окончания периода сбора статистики. Формат - YYYY-MM-DDThh%3Amm%3Ass.
taskId (optional)	integer	ID рассылки, по которой нужно получить статистику.
triggerId (optional)	integer	ID триггера рассылки, по которому нужно получить статистику.
timeOffset (optional)	integer	Часовой пояс получателя. Формат - смещение в минутах, например, 180 для Москвы (GMT +3).

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

curl -X GET https://api.devino.online/viber-stat/statistics/of-group?startDate=2022-10-06T13%3A45%3A30&endDate=2023-02-06T13%3A45%3A30&groupBy=MONTH
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \

Параметры ответа

Параметр	Тип данных	Описание
messages	array[MessageStatusObject]	Количество сообщений по выбранному периоду, сгруппированных по статусам.
segments	array[MessageStatusObject]	Количество сегментов сообщений по выбранному периоду, сгруппированных по статусам.

MessageStatusObject

Объект содержит информацию о количестве сообщений со статусами:

Код	Описание
accepted	Сообщение было принято.
scheduled	Сообщение запланировано к отправке.
enrouted	Сообщение находится в процессе отправки оператору.
sent	Сообщение было отправлено в сеть оператора.
deleted	Сообщение было удалено.
delivered	Сообщение доставлено абоненту.
expired	Истек срок жизни сообщения.
seen	Сообщение было прочитано получателем.
clicked	Получатель перешел по ссылке в сообщении.
rejected	Сообщение было отклонено оператором или Devino.Online.
undeliverable	Сообщение невозможно доставить.
unknown	Произошла неизвестная ошибка.

Каждый статус включает в себя параметры:

Параметр	Тип данных	Описание
date	string	Дата сбора статистики в зависимости от значения параметра groupBy.
amount	integer	Количество сообщений.

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

{
  "result": {
    "messages": {
      "accepted": [
        {
          "date": "2023-01-01 00:00:00",
          "amount": 100
        }
      ],
      "sent": [
        {
          "date": "2022-12-01 00:00:00",
          "amount": 2
        }
      ],
      "deleted": [],
      "delivered": [
        {
          "date": "2023-01-01 00:00:00",
          "amount": 67
        },
        {
          "date": "2022-10-01 00:00:00",
          "amount": 1
        },
        {
          "date": "2022-12-01 00:00:00",
          "amount": 72
        },
        {
          "date": "2023-02-01 00:00:00",
          "amount": 3
        }
      ],
      "enrouted": [],
      "expired": [],
      "seen": [],
      "clicked": [],
      "rejected": [],
      "scheduled": [],
      "undeliverable": [],
      "unknown": []
    },
    "segments": {
      "accepted": [
        {
          "date": "2023-01-01 00:00:00",
          "amount": 2
        },
        {
          "date": "2023-02-01 00:00:00",
          "amount": 4
        }
      ]
      ...
    }
  }
}