Viber#
Поддерживается отправка следующих типов Viber-сообщений:
только текст;
только изображение;
текст + кнопка для перехода по ссылке;
текст + изображение + кнопка для перехода по ссылке.
Запрос на отправку сообщений#
В HTTP API допустимы POST и GET запросы.
Примеры запросов#
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-запрос с текстом сообщения на кириллице “тест“ в URL-формате.
POST /login HTTP/1.1
Host: 10.241.0.194:9080
Content-Type: application/x-www-form-urlencoded;charset=utf-8
Content-Length: 78
serviceId=login&pass=123&clientId=79161234567&message=%D1%82%D0%B5%D1%81%D1%82
GET-запрос для передачи изображения.
http://partner.ru/login?clientId=79161234567&pass=123&serviceId=login&imageUrl=http://image001.jpg
GET-запрос с сообщением на латинице “test“ в простом текстовом формате и кнопкой с надписью “click“.
http://partner.ru/login?clientId=79161234567&message=test&pass=123&serviceId=login&buttonText=click&buttonLink=http://click
Параметры запросов#
Параметры применимы для 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 |
|
buttonText |
string |
Текст кнопки. Если передан buttonText, то обязательно должен быть передан
и buttonLink.
Максимальная длина: 30 символов.
|
buttonLink |
string |
|
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. Если Партнёр передает в этом параметре часовой пояс, то сообщение будет отправлено абоненту по местному времени этого часового пояса, иначе часовой пояс абонента определяется по номеру телефона абонента. Примечание Абонент с хабаровским номером находится в Москве. Возможны следующие варианты отправки:
Для нулевой зоны обязательно указание знака, неважно «+» или «-«.
Знак «+» при кодировании 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.
Ответ на запрос#
Примечание
Сервис-провайдер отправляет сообщения абонентам только при успешной обработке запроса.
Ответ при успешной отправке запроса#
На успешный запрос Сервис-провайдер возвращает Партнёру:
HTTP-код «200 OK»;
идентификатор сообщения в системе Сервис-провайдера.
OK
4095284974
Ответный код |
Описание |
Возможные действия Партнера |
---|---|---|
200 |
Успешная обработка запроса.
В теле ответа передаётся идентификатор, присвоенный
сообщению Сервис-провайдером.
Идентификатор представляет собой 64-битное целое
положительное число.
|
Штатная работа с сервисом. |
Ошибки при отправке запроса#
При передаче ошибочного запроса в теле ответа может возвращаться короткое текстовое сообщение об ошибке.
Пример ответа в случае возникновения ошибки неверного сочетания serviceId/pass:
Invalid password
Ответный код |
Описание |
Возможные действия Партнера |
---|---|---|
400 |
Отсутствуют обязательные параметры или они заданы некорректно. Например, не передан параметр message (там, где он необходим). |
Повторить запрос с правильным сочетанием параметров и их корректными значениями. |
401 |
Передано неверное сочетание параметров serviceId и pass. |
Повторить запрос с верными значениями параметров serviceId и pass. |
402 |
Исчерпан остаток оплаченных сообщений (для Партнёров, работающих по предоплате). |
Для возобновления отправки сообщений необходимо внести предоплату и обратиться к вашему курирующему менеджеру. Партнёр не должен повторять запрос. |
403 |
Сервис с переданным serviceId отсутствует или не активен. |
Следует обратиться к своему курирующему менеджеру. Партнёр не должен повторять запрос. |
406 |
Невозможно послать сообщение абоненту с переданным clientId. |
Партнёр не должен повторять запрос. |
408 |
Превышение допустимой скорости отправки сообщений. Примечание Для сервиса Партнёра установлена допустимая скорость 10 запросов в секунду. Партнёр отправил 12 запросов в секунду. Первые 10 запросов будут успешно обработаны: в ответ на эти запросы Сервис-провайдер вернет Партнёру статус 200 и отправит сообщения абонентам. В ответ на последние 2 запроса Сервис-провайдер вернет Партнёру статус 408 и не будет отправлять сообщения абонентам. |
Партнёр может повторить запрос, не превышая допустимой скорости. |
409 |
Запрещена отправка дубликатов. Примечание Для сервиса Партнёра включен функционал блокировки дубликатов. Партнёр отправил в течении суток три запроса для отправки сообщения на один номер с одинаковым текстом. Первый запрос будет успешно обработан и сообщение будет отправлено абоненту. В ответ на последние два запроса Сервис-провайдер вернет Партнёру статус 409 и не будет отправлять эти два сообщения абоненту. Функционал блокировки дубликатов по умолчанию отключен для Партнёра. Функционал может быть включен по просьбе Партнёра. Также Сервис-провайдер может включить функционал блокировки дубликатов для Партнёра при необходимости: например, в ответ на жалобы абонентов. |
Партнёр не должен повторять запрос. При необходимости отправки дубликата сообщения, Партнёр может обратиться в службу техподдержки Сервис-провайдера, предоставив наиболее полную информацию об условиях возникновения данной ситуации. |
414 |
Превышение допустимой длины текста сообщения, переданного в параметре message. |
Партнёр может повторить запрос, сократив текст сообщения до допустимой длины. |
500 |
Внутренняя ошибка сервера. Технические проблемы на стороне Сервис-провайдера. |
При получении статуса 500 или при истечении тайм-аута ожидания ответа, Партнёр должен выдержать паузу минимум 1 минуту. По истечении паузы Партнёр может повторить запрос. При получении статуса 500 более 10 раз необходимо прекратить передачу запроса. После чего передать в службу техподдержки Сервис-провайдера наиболее полную информацию б условиях возникновения данной ошибки для дальнейшего анализа. |
503 |
Запрос в обработке. Ошибка может возникнуть, если Партнёр практически одновременно передает несколько запросов с одним и тем же значением параметра partnerMsgId. Пока не обработан первый запрос на следующие запросы с тем же partnerMsgId Сервис-провайдер вернет Партнёру статус 503. |
Партнёр должен выдержать паузу и подождать ответ на первый запрос с переданным значением параметра partnerMsgId. Партнёр может повторить запрос, если не получит ответ на первый запрос. |
Ответ в формате XML#
200 – запрос успешно обработан;
500 – внутренняя ошибка сервера, технические проблемы на стороне Сервис-провайдера.
Примеры ответов#
<?xml version="1.0" encoding="utf-8"?>
<response>
<code>200</code>
<text>OK</text>
<payload>
<id>4095284976</id>
</payload>
</response>
Пример ответа в формате XML при ошибочной отправке запроса: неверное сочетание serviceId / pass.
<?xml version="1.0" encoding="utf-8"?>
<response>
<code>401</code>
<text>Invalid password</text>
</response>
При получении статуса 500 или при истечении тайм-аута ожидания ответа, Партнёр должен выдержать паузу минимум 1 минуту. По истечении паузы Партнёр может повторить запрос.
Примечание
При получении статуса 500 более 10 раз необходимо прекратить передачу запроса. После чего передать в службу техподдержки Сервис-провайдера наиболее полную информацию об условиях возникновения данной ошибки для дальнейшего анализа.
В таблице обязательные параметры выделены жирным шрифтом.
Наименование |
Описание |
Примечание |
---|---|---|
xml version |
Номер версии XML. |
Содержится в прологе XML-документа. |
encoding |
Кодировка. |
Содержится в прологе XML-документа. |
response |
Корневой элемент, содержит элементы code, text, payload. |
|
code |
Код ответа (значения соответствуют HTTP-кодам для ответов с типом text/plain). |
Подробное описание этих кодов приведено выше. |
text |
Дополнительная краткая текстовая информация об ответе. |
Может содержать информацию об ошибке. |
payload |
Информация о сообщении, содержит элемент id. |
Передаются только в случае успешного выполнения запроса (при значении code=200). |
id |
Идентификатор, присвоенный сообщению Сервис-провайдером. Идентификатор представляет собой 64-разрядное целое положительное число. |
Viber-сессия#
Примечание
Функционал Viber-сессий недоступен по умолчанию. Для его подключения следует обратиться к своему курирующему менеджеру.
Подключение функционала сессий#
Важно
Для бизнес-аккаунтов, поддерживающих функционал Viber-сессий, доступны сообщения с типом “только текст“ или “только изображение“ (значение параметра InstantContent.type должно быть либо “TEXT“, либо “IMAGE_URL“).
Особенности работы сессий#
Начало сессии:
сессия может быть инициирована только подписчиком;
сессия начинается, когда подписчик отправляет первое сообщение Партнеру;
сессия не может быть инициирована изображением;
если в рамках переписки присутствует только один отправитель (неважно – подписчик или Партнер), то это не считается сессией, сообщения будут тарифицированы обычным образом.
Лимиты сессии:
продолжительность сессии по умолчанию 24 часа;
Партнер может отправить до 60 сообщений (после превышения данного лимита автоматически стартует новая сессия);
Партнер может отправлять до 10 сообщений без ответа подписчика (после превышения данного лимита сессия автоматически закрывается);
Партнер может отправлять только сообщения с типом “текст“ или “изображение“.
Завершение сессии:
по прошествии 24 часов;
по достижении лимита в 60 сообщений (автоматически стартует новая сессия);
по достижении лимита в 10 безответных сообщений от Партнера.