Viber#

Поддерживается отправка следующих типов Viber-сообщений:

  • только текст;

  • только изображение;

  • текст + кнопка для перехода по ссылке;

  • текст + изображение + кнопка для перехода по ссылке.

Примеры запросов на отправку Viber-сообщений#

Для формирования тестового запроса с вашими параметрами Внешняя ссылка Открыть генератор запросов 

 1{
 2   "login":"ВАШ_ЛОГИН",
 3   "password":"ВАШ_ПАРОЛЬ",
 4   "useTimeDiff":false,
 5   "id":"8770100",
 6   "scheduleInfo":
 7   {
 8      "timeBegin":"10:00",
 9      "timeEnd":"20:00",
10      "weekdaysSchedule":"12345"
11   },
12   "destAddr":"Номер_Абонента",
13   "message":
14   {
15      "type":"VIBER",
16      "data":
17      {
18         "instantContent":
19         {
20            "type":"TEXT",
21            "data":
22            {
23               "text":"VIBERMESS"
24            }
25         },
26         "serviceNumber":"НОМЕР_ОТПРАВИТЕЛЯ",
27         "ttl":1
28      }
29   }
30}

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

Параметр

Обязат.

Тип

Описание

login

да

string

Имя Партнера.

password

да

string

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

useTimeDiff

нет

boolean

Учитывание часового пояса при запуске рассылки.

Подробнее

Если true, то отправка сообщения осуществляется абоненту согласно расписанию рассылки и его часовому поясу.

Если false, то сообщение отправляется согласно расписанию инициатора рассылки UTC+3, не обращая внимание на часовой пояс получателя сообщения.

Значение по умолчанию: false.

id

нет

string

Уникальный идентификатор на стороне Партнёра.

Подробнее

Данный параметр используется для контроля повторных отправок и дублирования (сервис контроля включается отдельно). Партнёр может вызывать Сервис-провайдера (запрос на отправку сообщения) с одним и тем же id несколько раз.

При этом:

  • отправка сообщения абоненту будет выполнена только один раз (по первому запросу);
  • в ответах на данные запросы Сервис-провайдер вернет Партнёру один и тот же идентификатор сообщения в системе Сервис-провайдера (тот же, что на первый запрос).

Сервис-провайдер опционально возвращает Партнёру данный идентификатор при его наличии в отчёте о доставке сообщения.

shortenLinks

нет

boolean

Параметр управляет включением автоматического сокращения длинных ссылок в сообщении.

Подробнее

Возможные значения:

  • true — для сокращения ссылок (значение по умолчанию);
  • false — сокращение ссылки не требуется.

Если параметр в запросе не приходит, но при этом сервис Партнёру доступен, то ссылки будут сокращаться по умолчанию.

Возможность пользоваться данным сервисом предварительно оговаривается и настраивается Сервис-Провайдером.

Подробнее: см. Сервис сокращения ссылок.

scheduleInfo

нет

object

Расписание рассылки.

Подробнее

Если не указано, отправляется сразу же, в момент получения запроса.

scheduleInfo/
timeBegin

нет

string

Время начала.

Подробнее

Например, 10:00.

scheduleInfo/
timeEnd

нет

string

Время окончания.

Подробнее

Например, 21:00.

scheduleInfo/
weekdaysSchedule

нет

string

Дни рассылки.

Подробнее

Задаются цифрами от 1 (понедельник) до 7 (воскресение), например, 12345.

Если ограничений по дням недели нет, то данный параметр может быть пустой или не передан в запросе.

scheduleInfo/
deadline

нет

string

Дата окончания рассылки.

Подробнее

Например, 2019-05-10T16:29:30+0300.

destAddr

да

string

Номер телефона абонента.

Подробнее

Содержит код страны, код оператора и номер телефона.

Для РФ код может быть 8, 7 или +7.

Примеры: 72101234567, +72101234567, 8-210-123-45-67, 82101234567.

message

да

object

Параметры отправляемого сообщения.

message/type

да

enum

Тип сообщения.

Подробнее

Передается значение VIBER.

message/data

да

object

Параметры отправляемых данных
message/data/
instantContent

да

object

Параметры отправляемого Viber-сообщения (изображения, кнопки).
instantContent/
type

да

enum

Тип параметра сообщения.

Подробнее

Допустимые значения: TEXT (для передачи только текста), IMAGE_URL (для передачи только изображения), BUTTON (для передачи текста сообщения, адреса изображения, наименования кнопки и URL для перехода по кнопке, см. instantContent/data).

Важно

Для бизнес-аккаунтов, поддерживающих функционал Viber-сессий, доступны сообщения либо TEXT, либо IMAGE_URL. Сообщения с другим типом возвращают ошибку 400 «Invalid request».
instantContent/
data

да

object

Параметры отправляемых данных при выборе значения BUTTON в instantContent/type.

Подробнее

Допустимые значения: text (текст сообщения), imageURL (адрес изображения), caption (наименованием кнопки), action (URL для перехода по кнопке).

instantContent/
data/text

да

string

Текст сообщения.

Подробнее

Максимальная длина: 1000 символов.

instantContent/
data/imageURL

да

string

URL изображения для передачи.

Подробнее

Рекомендовано использовать изображение размером 400x400px с расширением JPG или PNG.

instantContent/
data/caption

да

string

Текст кнопки в Viber-сообщении.

Подробнее

Максимум 30 символов.

instantContent/
data/action

да

string

Ссылка кнопки в Viber-сообщении.

Подробнее

Максимум 2048 символов.

URL для ссылки должен начинаться с http:// , https:// , viber:// , mailto: , tel: .

message/data/
serviceNumber

нет

string

Сервисное имя, от которого осуществляется отправка сообщения.

message/data/ttl

нет

integer

Срок жизни сообщения.

Подробнее

Допустимый диапазон, сек: от 30 до 86400.

Примечание

При ttl = 0 или отсутствии параметра в запросе берётся значение из настроек по умолчанию, которые задаются при настройке интеграции отдельно для каждого клиента.
message/data/
ttlUnit

нет

enum

Единица измерения периода доставки сообщения.

Подробнее

Передается только вместе с ttl.

Допустимые значения: SECONDS; MINUTES (значение по-умолчанию); HOURS.

extraParam

нет

string

Дополнительные параметры, передаваемые в виде param1=value1,param2=value2, где param1 и param2 — названия параметров, value1 и value2 — значения.

Подробнее

Символ запятой в названии параметра использоваться не может, но может входить в его значение — в этом случае он должен удваиваться. Пример: строка место=абзаково,название=гостевой дом-2,координаты= 53.8085896,,58.6362112, c=23.02.09,по=05.03.09.

registeredDelivery

нет

integer

Необходимость отчётов о доставке.

Подробнее

Возможные значения:

  • 0 — статусы не нужны;
  • 1 — нужны статусы (по умолчанию);
  • 2 — нужны только статусы НЕ ДОСТАВЛЕНО.

notifyUrl

нет

string

Имя хоста входящего API для получения отчета о доставке.

Подробнее

Этот параметр в запросе необязательный, но при его отправке нужно учесть следующее: если парметр указан, он не может быть пустым.

Длина строки notifyUrl не должна превышать 2048 символов.

При невыполнении любого из указанных условий будет сгенерирована ошибка, запрос не будет выполнен.

cascadeChainLink

нет

object

Параметры каскадных сообщений.

Подробнее

См. Каскадная рассылка

Ответ на запрос#

После отправки сообщения Сервис-провайдер синхронно возвращает ответ. В случае успешной отправки возвращается HTTP-код 200 OK.

Ответ при успешной отправке Viber-сообщения#

1 {
2     "mtNum": "7390612217"
3     "id": "8770599"
4 }

Ошибки при отправке Viber-сообщения#

Для ошибочных результатов HTTP-код ответа будет отличный от 200 OK (см. Коды ошибок отправки).

1  {
2      "error": {
3         "code": 4,
4         "description": "Invalid request"
5      },
6      "extendedDescription": "Capture is absent or length longer 30 characters"
7   }

В данном примере в Viber-сообщении типа BUTTON отсутствует параметр capture, или его длина превышает 30 символов.

Коды ошибок отправки#

Код

Описание

HTTP-код

1

Service is unavailable

503

2

Invalid IP-address

403

3

Too many connections

429

4

Invalid request

400

5

Invalid login

401

6

Invalid password

401

7

serviceNumber is not defined

400

8

destAddr is not correct

406

9

Message type is not correct

406

10

Prohibited sending duplicates

409

11

Invalid TTL

406

100

100

500

Статусы доставки Viber-сообщений#

Для получения статусов Viber-сообщений необходимо настроить Сервис получения статусов доставки сообщений.

Коды ошибок доставки#

Коды ошибок доставки, в зависимости от типа сообщения, приведены в соответствующей вкладке в разделе Описание кодов ошибок.

Viber-сессия#

Viber-сессия — функционал, позволяющий Партнеру общаться с подписчиками в определенных временных рамках по фиксированной цене за одну сессию.
Причина обращения может быть любая: вопрос, сообщение о проблеме, проверка бронирования или статуса доставки — пользователь получит ответ в режиме реального времени.

Примечание

Функционал Viber-сессий недоступен по умолчанию. Для его подключения следует обратиться к своему курирующему менеджеру.

Подключение функционала сессий#

Использование сессий подразумевает наличие специального бизнес-аккаунта Viber.
Вы можете создать новый бизнес-аккаунт Viber с подключенным функционалом сессий.
Если у Вас уже есть действующий бизнес-аккаунт, и Вы хотели бы подключить сессии к нему, следует обратиться к курирующему менеджеру.

Важно

Для бизнес-аккаунтов, поддерживающих функционал Viber-сессий, доступны сообщения с типом «только текст» или «только изображение» (значение параметра InstantContent.type должно быть либо TEXT, либо IMAGE_URL).

Особенности работы сессий#

Начало сессии:

  • сессия может быть инициирована только подписчиком;

  • сессия начинается, когда подписчик отправляет первое сообщение Партнеру;

  • сессия не может быть инициирована изображением;

  • если в рамках переписки присутствует только один отправитель (неважно — подписчик или Партнер), то это не считается сессией, сообщения будут тарифицированы обычным образом.

Лимиты сессии:

  • продолжительность сессии по умолчанию 24 часа;

  • Партнер может отправить до 60 сообщений (после превышения данного лимита автоматически стартует новая сессия);

  • Партнер может отправлять до 10 сообщений без ответа подписчика (после превышения данного лимита сессия автоматически закрывается);

  • Партнер может отправлять только сообщения с типом “текст“ или “изображение“.

Завершение сессии:

  • по прошествии 24 часов;

  • по достижении лимита в 60 сообщений (автоматически стартует новая сессия);

  • по достижении лимита в 10 безответных сообщений от Партнера.

Тарификация Viber-сессий#

За пользование функционалом сессий взимается абонентская плата. Ее размер нужно уточнять у курирующего менеджера при создании бизнес-аккаунта.
Все сессии оплачиваются по фиксированной (одинаковой) цене. Сообщения внутри сессий не тарифицируются.
Сообщения вне сессии тарифицируются обычным образом.