Viber

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

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

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

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

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

Время жизни Viber-сообщений: от 30 до 86400 секунд (24 часа).

Время жизни Viber-сообщений передаётся в запросе, в параметре viberTtl.

Запрос на отправку сообщений

В HTTP API допустимы POST и GET запросы.

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

POST-запросыGET-запросы

Текстовый форматURL-формат

POST-запрос с сообщением на латинице “test“ в простом текстовом формате.

{
    POST /login HTTP/1.1
    Host: 10.10.10.10:9080
    Content-Type: application/x-www-form-urlencoded;charset=utf-8
    Content-Length: 58
    serviceId=login&pass=123&clientId=79161234567&message=test
}

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

Параметры применимы для POST и GET запросов.

В таблице обязательные параметры выделены жирным шрифтом.

Параметр	Тип	Описание
clientId	string	Номер телефона абонента, до 25 символов. Примеры: 79036550550, +79036550550, 8-903-655-05-50, 89036550550.
message	string	Текст сообщения в кодировке UTF-8. Максимальная длина: 1000 символов.
serviceId	string	Идентификатор сервиса (логин), от имени которого происходит отправка сообщения. Логин serviceId заводится Сервис-провайдером при подключении сервиса и сообщается Партнёру.
pass	string	Пароль для авторизации в сервисе. Пароль заводится Сервис-провайдером при подключении сервиса и сообщается Партнёру.
ptag	string	Идентификатор сообщения в системе Партнёра. Может содержать от одного до 50 символов. Допустимые символы: 0…9a…zA…Z- Это может быть любой идентификатор в системе Партнёра. Примечание Например, уникальный идентификатор сообщения или идентификатор подразделения, инициирующего запрос на отправку. В отличие от параметра partnerMsgId, который нужен для контроля повторных отправок и дублирования, Сервис-провайдер не контролирует значения, переданные в параметре ptag (проверяется только соответствие формату). Сервис-провайдер опционально возвращает Партнёру данный идентификатор в рамках запроса на получение статуса доставки сообщения (этот функционал подробно описан в разделе «Сервис получения статусов доставки сообщений»).
imageUrl	string	Ссылка на изображение, пересылаемое абоненту. Ссылка должна начинатьсяс «http://» или «https://».
buttonText	string	Текст кнопки. Если передан buttonText, то обязательно должен быть передан и buttonLink. Максимальная длина: 30 символов.
buttonLink	string	Ссылка для перехода после нажатия на кнопку. Ссылка должна начинаться с «http://», «https://», «viber://», «tel:», «mailto:». Максимальная длина ссылки: 2048 символов. Если передан buttonLink, то обязательно должен быть передан и buttonText.
viberTtl	integer	Время жизни сообщения. Допустимый диапазон, сек: от 30 до 86400. Рекомендуемое минимальное значение: 60. В течение указанного времени Viber будет пытаться доставить сообщение абоненту. Значения, выходящие за пределы минимального или максимального, будут к ним округлены. Если параметр не передан, будет использовано значение по умолчанию (согласованное при запуске сервиса). Если время жизни сообщения истекло, ему присваивается статус не доставлено.
sending_time	string	Локальное время отправки сообщения абоненту. Задается в формате hh_hh, где два значения часа задают временной промежуток, в который должно быть отправлено сообщение. Предупреждение Если параметр указан, то его значение не может быть пустым. Примечание Например, при значении параметра sending_time=10_20, сообщение будет отправлено в период с 10:00 до 20:00 по местному времени в часовом поясе абонента. Часовой пояс абонента определяется не по фактическому местоположению абонента. Если Партнёр не передает параметр time_zone, то часовой пояс абонента определяется по номеру телефона. Если Партнёр передает в параметре time_zone часовой пояс, то сообщение будет отправлено абоненту по местному времени этого часового пояса.
time_zone	string	Часовой пояс абонента. Задается в формате ±hh:mm. Подробнее о формате см. ISO 8601. Если Партнёр передает в этом параметре часовой пояс, то сообщение будет отправлено абоненту по местному времени этого часового пояса, иначе часовой пояс абонента определяется по номеру телефона абонента. Примечание Абонент с хабаровским номером находится в Москве. Возможны следующие варианты отправки: Получены значения: sending_time=10_20, time_zone=+04:00 (московское время). Сообщение будет отправлено в период с 10:00 до 20:00 по московскому времени. Получено значение sending_time=10_20 и не передан параметр time_zone. Сообщение будет отправлено в период с 10:00 до 20:00 по хабаровскому времени. Для нулевой зоны обязательно указание знака, неважно «+» или «-«. Знак «+» при кодировании URL преобразуется в «%2B». Например, часовой пояс +04:00 передается так time_zone= %2B04:00.
source	string	Имя отправителя. Сообщение абоненту будет отправлено с сервисного имени, указанного в данном параметре. Данный параметр не является обязательным. Если параметр отсутствует в запросе, то сообщение будет отправлено абоненту с имени по умолчанию (настройка на стороне Сервис-провайдера). Важно Использование данного параметра недоступно для Партнёра по умолчанию. Функционал может быть включен после согласования с Сервис-провайдером. В этом случае для Партнёра настраивается список разрешенных имен отправителей, либо включается функционал динамической подписи.
output	string	Формат ответа на запрос. Если output=xml, то ответ на запрос будет сформирован в виде XML (см. Ответ в формате XML). Если параметр не задан или имеет другое значение, будет применён формат по умолчанию: text/plain (см. Ответ на запрос).
partnerMsgId	string	Уникальный идентификатор сообщения в системе Партнёра. Допустимая длина: от одного до 50 символов. Данный параметр используется для контроля повторных отправок и дублирования. Партнёр может отправить запрос на отправку сообщения с одним и тем же partnerMsgId несколько раз. При этом: отправка сообщения абоненту будет выполнена только один раз (по первому запросу); в ответах на данные запросы Сервис-провайдер вернет Партнёру один и тот же идентификатор сообщения в системе Сервис-провайдера (тот же, что на первый запрос). Сервис-провайдер опционально возвращает Партнёру данный идентификатор в рамках запроса на получение статуса доставки сообщения (См. Сервис получения статусов доставки). Использование данного параметра недоступно по умолчанию. Подключение данного функционала нужно согласовать со своим курирующим менеджером.
shortenLinks	boolean	Параметр указывает, требуется ли сокращать ссылки в тексте сообщения. Важно Используется только для одиночных сообщений. В случае каскадной доотправки необходимо использовать параметр shorten_list (см. Каскадные сообщения). Важно Использование данного параметра недоступно по умолчанию. Подключение данного функционала необходимо согласовать со своим курирующим менеджером. Подробнее: Сервис сокращения ссылок.

Примечание

Возможные комбинации параметров в запросе:

• message;

• imageUrl;

• message + buttonText + buttonLink;

• message + imageUrl + buttonText + buttonLink.

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

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

По умолчанию ответ от Сервис-провайдера приходит в формате text/plain.

По согласованию с Партнёром ответ может быть сформирован в формате XML.

Примечание

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

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

На успешный запрос Сервис-провайдер возвращает Партнёру:

• HTTP-код «200 OK»;

• идентификатор сообщения в системе Сервис-провайдера.

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

{
   OK
   4095284974
}

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

При передаче ошибочного запроса в теле ответа может возвращаться короткое текстовое сообщение об ошибке.

Пример ответаКоды ошибок при отправке запроса

Пример ответа в случае возникновения ошибки неверного сочетания serviceId/pass:

{
    Invalid password
}

Ответ в формате XML

Для получения ответа в формате XML Партнеру в теле запроса необходимо передать параметр output=xml.

В таком случае Сервис-провайдер синхронно отвечает на запрос одним из следующих HTTP-кодов:

• 200 – запрос успешно обработан;

• 500 – внутренняя ошибка сервера, технические проблемы на стороне Сервис-провайдера.

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

Успешная отправкаОтправка с ошибкойОписание элементов XML

Пример ответа в формате XML при успешной отправке запроса (HTTP-код 200) .

Описание содержания ответа приведено во вкладке «Элементы XML».

{
    <?xml version="1.0" encoding="utf-8"?>
    <response>
        <code>200</code>
        <text>OK</text>
        <payload>
            <id>4095284976</id>
        </payload>
    </response>
}

Viber-сессия

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

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

Примечание

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

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

Использование сессий подразумевает наличие специального бизнес-аккаунта Viber.

Вы можете создать новый бизнес-аккаунт Viber с подключенным функционалом сессий.

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

Важно

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Все сессии оплачиваются по фиксированной (одинаковой) цене. Сообщения внутри сессий не тарифицируются.

Сообщения вне сессии тарифицируются обычным образом.