Viber#

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

  • текстовое сообщение;

  • изображение;

  • текст + кнопка — текстовое сообщение, под которым расположена кнопка, при нажатии на которую происходит переход по заданной ссылке;

  • текст + кнопка + изображение — текстовое сообщение, под которым расположены изображение и кнопка, при нажатии на которую происходит переход по заданной ссылке.

Вид Viber-сообщения определяется автоматически, исходя из набора переданных параметров. Если передан текст кнопки, то должна быть передана и ссылка для кнопки (и наоборот).

Запрос на отправку#

Для отправки сообщения Партнёру следует установить соединение с сервером и передать Сервис-провайдеру пакет submit_sm, в котором содержатся все необходимые параметры сообщения (опционально, также и TLV-параметры).

Примечание

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

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

Параметр

Тип

Описание

source_addr

string

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

Подробнее

В случае отсутствия параметра отправка производится с номера, заданного по умолчанию на платформе Сервис-провайдера (настройка по желанию Партнёра).

Кодировка значения параметра source_addr (согласно протоколу SMPP): ASCII.

Для Viber в номере отправителя (наименовании чата) возможно использование Unicode-символов, в том числе кириллицы.

В случае использования не-ASCII подписи, Партнёру для работы по SMPP выделяется сервисное имя, состоящее из ASCII-символов, а подмена на Unicode-вариант реализуется на интерфейсе между платформами Сервис-провайдера и Viber.

destination_addr

string

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

Подробнее

Длина символов: не более 25.

Примеры: 79036550550, +79036550550, 8-903-655-05-50, 89036550550.

short_message

string

Текст сообщения для отправки абоненту.

Подробнее

Длина сообщения для Viber: не более 1000 символов.

Длина пользовательских данных для поля short_message: не более 254 октета.

Текстовые сообщения длиной более 254 октетов рекомендуется передавать одной PDU в TLV-параметре message_payload, id = 0x0424.

Важно

Одновременное использование обоих полей недопустимо. При использовании поля message_payload поле short_message должно оставаться пустым.

data_coding

integer

Схема/тип кодирования текста сообщения.

Подробнее

Задается в соответствии со стандартом GSM 03.38.

Допустимые значения:

  • 0 — DEFAULT, кодировка по умолчанию;
  • 1 — ASCII;
  • 3 — LATIN1;
  • 6 — LATIN_CYR;
  • 8 — UCS2.

Если кодировка текста отличается от заявленных выше, сообщение воспринимается платформой как бинарное.

Для передачи текста сообщения рекомендуется использовать кодировку UCS2 (data_coding = 8).

Для передачи сообщений в латинице возможно использование data_coding = 0, что соответствует кодировке GSM DEFAULT ALPHABET или ASCII — по желанию Партнёра (единая настройка на прием и передачу сообщений).

esm_class

integer

Множество значений этого параметра задается протоколом SMPP версии 3.4, раздел 5.2.12.

registered_delivery

integer

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

Подробнее

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

  • 0 — Партнёру не требуется уведомление о статусе доставки;
  • 1 — Партнёру требуется уведомление о статусе доставки;
  • 2 — Партнёру требуется уведомление о статусе только в случае если сообщение не доставлено абоненту.

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

schedule_delivery_time

string

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

Подробнее

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

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

Поле schedule_delivery_time можно задавать как в относительном, так и в абсолютном формате.

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

Формат значения для параметра YYMMDDhhmmsstnnp, где:

  • YYMMDDhhmmss — год, месяц, день, часы, минуты, секунды;
  • t — десятые доли секунд;
  • nn — четверти часа (по 15 минут), например, для 8 часов значение будет 32;
  • p — сдвиг. Возможные значения:
    • + и – задают сдвиг времени на четверть часа относительно GMT, например, 08+ соответствует GMT+2, а 04– соответствует GMT–1;
    • R — значения t и nn игнорируется, всё остальное прибавляется к текущему локальному времени;
    • А — дата и время считаются указанными по локальному времени абонента и задают начало интервала возможной отправки, а четверти задают длину этого интервала. Отправка происходит внутри указанного времени, даже если дата в прошлом, т.е., если «сейчас» 10:00, а интервал задан как «вчера» с 15:00 до 18:00, то сообщение не будет отправлено раньше 15:00. Если в текущих сутках интервал уже закончился, его начало перемещается на следующий день.

validity_period

string

Время жизни сообщения.

Подробнее

Диапазон времени жизни для Viber: от 30 до 86400 секунд (до 1 суток).

Формат значения для параметра YYMMDDhhmmsstnnp, где:

  • YYMMDDhhmmss — год, месяц, день, часы, минуты, секунды;
  • t — десятые доли секунд;
  • nn — четверти часа (по 15 минут), например, для 8 часов значение будет 32;
  • p — сдвиг. Возможные значения:
    • + и – задают сдвиг времени на четверть часа относительно GMT, например, 08+ соответствует GMT+2, а 04– соответствует GMT–1;
    • R — значения t и nn игнорируется, всё остальное прибавляется к текущему локальному времени.

TLV-параметры запроса#

TLV-параметры для отправки сообщений от Партнёра к Сервис-провайдеру.

TLV-параметр

Поле

Размер (октетов)

Тип

Описание

message_payload

Tag

2

Integer

id = 0x0424

Length

2

Integer

Длина параметра в октетах.

Value

до 2048
Octet
String

Текст сообщения длиной более 254 октетов (многосегментное сообщение с точки зрения SMPP).

Подробнее

Примечание

Текстовые сообщения длиной менее 254 октетов рекомендуется передавать в параметре short_message. Одновременное использование параметров message_payload и short_message недопустимо.

ptag

Tag

2

Integer

id = 0x1411

Length

2

Integer

Длина параметра в октетах.

Value

до 1000
Octet
String

Идентификатор сообщения в системе Партнёра.

Подробнее

Может содержать от 1 до 50 символов.

Допустимые символы: 0...9a...zA...Z-.

Это может быть любой идентификатор в системе Партнёра.

Например, уникальный идентификатор сообщения или идентификатор подразделения, инициирующего запрос на отправку.

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

imageURL

Tag

2

Integer

id = 0x1436

Length

2

Integer

Длина параметра в октетах.

Value

до 2048
Octet
String

Ссылка на изображения для отправки в Viber-сообщении.

Подробнее

Длина символов: не более 2048.

URL должен начинаться с «http://» или «https://».

Символы, недопустимые в URL согласно стандарту HTTP-протокола (спецсимволы, кириллица, юникод), должны быть закодированы (URLEncoded) по кодировке UTF-8.

action

Tag

2

Integer

id = 0x1433

Length

2

Integer

Длина параметра в октетах.

Value

до 2048
Octet
String

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

Подробнее

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

Длина, символов, не более: 2048.

URL должен начинаться с «http://» или «https://».

Символы, недопустимые в URL согласно стандарту HTTP-протокола (спецсимволы, кириллица, юникод), должны быть закодированы (URLEncoded) по кодировке UTF-8.

Пример: 0x68,0x74,0x74,0x70,0x3A,0x2F,0x2F, 0x77,0x77,0x77, 0x2E,0x62,0x75,0x74,0x74,0x6F,0x6E, 0x2E,0x72,0x75,0x00.

caption

Tag

2

Integer

id = 0x1434

Length

2

Integer

Длина параметра в октетах.

Value

до 20
Octet
String

Текст, отображаемый на кнопке в Viber-сообщении.

Подробнее

Длина, символов, не более: 20.

Если текст содержит символы кириллицы, следует использовать кодировку UTF-8.

Пример: 0xD0,0xBA,0xD0,0xBD,0xD0,0xBE,0xD0, 0xBF,0xD0,0xBA,0xD0,0xB0 — соответствует строке кнопка.

viberTTL

Tag

2

Integer

id = 0x1435

Length

2

Integer

Длина параметра в октетах.

Value

до 5
Octet
String

Время жизни Viber-сообщения, заданное в секундах.

Подробнее

Минимальное значение: 30.

Рекомендуемое минимальное значение: 60.

Максимальное значение: 86400.

Значения, выходящие за рамки минимального и максимального, будут к ним округлены.

Если параметр не передан, будет использовано значение по умолчанию (согласованное при запуске сервиса).

Примечание

В течение времени жизни сообщения Viber будет пытаться доставить сообщение абоненту. Если это время истекло, сообщению присваивается статус «не доставлено».

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

На пакет submit_sm сервер Сервис-провайдера отвечает пакетом submit_sm_resp с полем command_status.

Если пакет принят и обработан успешно, тело пакета submit_sm_resp будет содержать message_id — уникальный идентификатор (целое положительное число), присвоенный на сервере Сервис-провайдера данному PDU.

В дальнейшем значение message_id используется Партнёром для получения и анализа статусов доставки сообщения.

Возможные значения поля command_status приведены в таблицах ниже.

Ответ при успешной отправке#

В случае успешной отправки возвращается код ответа (HEX) 0x00.

Код (HEX)

Описание

Действие Партнёра

0x00

Пакет принят успешно.

Ошибок нет, штатная работа сервиса.

Ошибки при отправке#

Для ошибочных результатов код ответа (HEX) будет отличный от 0x00.

Код (HEX)

Описание

Действие Партнёра

0x01

Превышена допустимая длина текста сообщения.
Что делать

Партнёр может сократить текст до допустимых значений и повторить попытку отправки сообщения.

0x03

Партнёр передал PDU неподдерживаемого типа (query_sm, submit_multi, data_sm и т.п.).
Что делать

Партнёр устраняет ошибки на своей стороне.

0x08

Общая системная ошибка на сервере.
Что делать

Партнёр может повторить попытку отправить сообщение.

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

0x0A

Неверное имя отправителя.

Подробнее

Партнёр передал в параметре source_addr значение, с которого не разрешена отправка сообщений абонентам.

Что делать

Партнёр устраняет ошибки на своей стороне, после этого может повторить отправку сообщения с корректным source_addr.

0x0B

Неверный номер получателя.

Подробнее

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

Что делать

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

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

0x0C

Передано некорректное значение TLV-параметра ptag (id=0x1411).
Что делать

Партнёр исправляет значение параметра и может повторить попытку отправки сообщения.

0x14

Очередь на отправку сообщений от Партнёра достигла максимально допустимого значения.

Подробнее

Пример. Для сервиса Партнёра установлено максимальное количество сообщений в очереди для отправки абонентам — 100 сообщений.

Если в очереди отправки Партнёра скопилось более 100 сообщений, то Сервис-провайдер отвечает этим кодом ошибки пока очередь не уменьшится.

Что делать

Партнёр приостанавливает процесс отправки SMS (submit_sm) на 5 сек, потом возобновляет рассылку. Партнёр может повторить отправку сообщений, на которых возникла ошибка.

Если ошибка повторится более пяти раз подряд, следует прекратить процесс отправки сообщений и обратиться в Службу технической поддержки, предоставив наиболее полную информацию об условиях возникновения данной ошибки.

0x45

Попытка отправить сообщения после завершения триал-периода или при превышении количества разрешенных для триал-периода сообщений.
Что делать

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

0x55

Превышен порог максимального количества ответных сообщений для режима «запрос-ответ» или «смешанный».
Что делать

Партнёр должен дождаться следующего входящего сообщения от абонента.

0x58

Превышена пропускная способность, установленная для Партнёра.

Подробнее

Пример. Для сервиса Партнёра установлена допустимая скорость 10 сообщений в секунду. Партнёр отправил 12 сообщений в секунду. Первые 10 сообщений будут успешно обработаны — Сервис-провайдер отправит сообщения абонентам.

В ответ на последние два сообщения Сервис-провайдер вернет Партнёру код ошибки 0x58 и не будет отправлять эти два сообщения абонентам.

Что делать

Партнёр останавливает процесс отправки (submit_sm) на 5 сек, потом возобновляет рассылку, не превышая допустимой скорости.

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

0x61

Указано некорректное значение параметра schedule_delivery_time.
Что делать

Партнёр устраняет ошибки на своей стороне, после чего может повторить отправку с корректным schedule_delivery_time.

0x62

Превышен лимит продолжительности транзакции.

Подробнее

Ошибка возникает, если значение, переданное в schedule_delivery_time, выходит за допустимые пределы.

Что делать

Партнёр может повторить отправку с правильным значением параметра schedule_delivery_time.

0xAB

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

Подробнее

Пример. Для сервиса Партнёра включен функционал блокировки дубликатов. Партнёр отправил в течение суток три запроса на отправку сообщения на один и тот же номер абонента с одинаковым текстом. Первый запрос будет успешно обработан и сообщение будет отправлено абоненту.

В ответ на последние два запроса Сервис-провайдер вернет Партнёру код ошибки 0xAB и не будет отправлять эти два сообщения абоненту.

Функционал блокировки дубликатов по умолчанию отключен для Партнёра. Функционал может быть включен по просьбе Партнёра.

Что делать

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

0xC4

Партнёр передал некорректное значение в одном из TLV-параметров.
Что делать

Партнёр устраняет ошибки на своей стороне, после чего может повторить отправку сообщения с корректным набором параметров.

0x500

Ошибка будет возникать при условии, если в настройках интеграционного SMPP-клиента в параметрах протокола «Параметры протокола» задан определённый метод склейки («Склеивать через UDH» или «Склеивать через TLV»), а от SMPP-клиента придет пакет, не соответствующий данному типу обработки.

Подробнее

Ошибка не будет проявляться, если выбран параметр «Определять автоматически» (значение по умолчанию). В данном случае при получении от SMPP-клиента автоматически определяется тип пакета и выполняется склейка сообщения по определенному методу.

Что делать

При возникновении данной ошибки Партнёр останавливает процесс отправки сообщений, изменяет метод отправки данных сообщений на своей стороне (TLV или UDH), повторяет отправку данных сообщений.

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

Примечание

Если сервис Партнёра не отвечает на запросы Сервис-провайдера, выполняется Повторная обработка сообщений.

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

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

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

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

Viber-сессия#

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

Примечание

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

Подключение#

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

Важно

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

Тарификация#

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