Отправка сообщений Viber

Пример GET-запроса для отправки

https://auth.terasms.ru/outbox/send_viber?login=login&password=password&target=79XXXXXXXXX&sender=sender&message=Hello+from+terasms.ru

Отправить изображение и кнопку можно только таким способом. Соответствующие параметры запроса (image_id, button_text, button_link) описаны ниже.

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

Описание параметров

Параметр Описание Тип Обязательный
login Ваш логин на платформе TeraSMS string да
password Ваш пароль на платформе TeraSMS string да
target Телефон получателя string да
sender Имя отправителя, которое увидит клиент * string да
message Текст сообщения ** string нет
button_text Текст кнопки, приложенной к сообшению ** string нет
button_link Ссылка приложенной к сообщению кнопки ** string нет
image_id ID приложенного к сообщению изображения. Изображения необходимо предварительно загружать в систему (см. ниже) ** int32 нет
ttl Время, в течении которого должно быть доставлено сообщение (в секундах). Сообщения с истекшим TTL считаются недоставленными int32, мин. значение — 60 (минута), максимальное — 86400 (сутки) нет (значение по-умолчанию — 86400)

* имя отправителя необходимо согласовывать с менеджером

** возможны следующие варианты сообщений: только текст, только изображение, текст + кнопка, текст + кнопка + изображение

В качестве ответа на запрос вернётся ID сообщения (целое число, int 32), которое можно затем использовать для проверки статуса, либо код ошибки.

Коды ошибок отправки сообщения

Код ошибки Значение
-20 В запросе отсутствует содержание сообщения, либо переданное содержание недопустимо
-30 В запросе отсутствует номер абонента
-40 Передан неверный номер абонента
-50 В запросе отсутствует имя отправителя
-60 Передан неверный ID изображения
-80 Услуга не подключена, обратитесь к менеджеру
-100 Неизвестная ошибка
-120 Неверное значение TTL

Массовая отправка сообщений через API

Вы можете отправлять несколько сообщений одним запросом, отправляя POST-запрос по адресу https://auth.terasms.ru/outbox/send_viber_bulk/xml или https://auth.terasms.ru/outbox/send_viber_bulk/json.
При запросе на https://auth.terasms.ru/outbox/send_viber_bulk/xml ваш запрос должен быть представлен в формате XML (ответ платформы также приходит в этом формате), при запросе на https://auth.terasms.ru/outbox/send_viber_bulk/json запрос должен быть в формате json, ответ также будет в json. Параметры сообщений аналогичны параметрам, передаваемым при отправке одиночного сообщения.

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

запрос
<?xml version="1.0" encoding="utf-8"?>
<request>
    <login>login</login>
    <password>password</password>
    <messages>
        <msg>
            <target>780011122233</target> <!-- телефон, на который отправится сообщение -->
            <message>ку-ку</message> <!-- текст сообщения -->
            <sender>terasms.ru</sender> <!-- имя отправителя -->
        </msg><<msg>
            <target>780011122234</target>
            <message>ку-ку</message>
            <sender>terasms.ru</sender>
        </msg>
    </messages>
</request>
Ответ
<?xml version="1.0" encoding="utf-9"?>
    <response>
    <messages>
        <message>
            <status>0</status>
            <message_id>1771</message_id>
        </message>
        <message>
            <status>0</status>
            <message_id>1773</message_id>
        </message>
    </messages>
</response>

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

Запрос
{
    "login": "login",
    "password": "password",
    "messages": [
        {
            "message": "хелло",
            "target": "78999999999",
            "sender": "terasms.ru"
        }
    ]
}
Ответ
{
  "messages": [
    {
      "status": 0,
      "message_id": 15304
    },
    {
      "message_id": null,
      "status": -50,
      "error": "No sender name"
    }
  ]
}

Загрузка изображений

Загрузка изображений в систему осуществляется POST-запросом (multipart/form-data) по адресу https://auth.terasms.ru/outbox/upload_image

В запросе должны присутствовать следующие поля:

Параметр Описание обязательный
login Ваш логин на платформе TeraSMS да
password Ваш пароль на платформе TeraSMS да
image Файл изображения в формате multipart/form-data да

В ответе на запрос придёт ID изображения, которое можно указывать в параметре image_id при отправке сообщений.

Проверка статуса сообщения

Для проверки статуса сообщения рекомендуется использовать общий метод получения статусов сообщений любых типов.
Также можно произвести GET/POST-запрос по адресу: https://auth.terasms.ru/outbox/viber_status?login=login&password=password&id=message_id

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

Параметр Описание обязательный
login Ваш логин на платформе TeraSMS да
password Ваш пароль на платформе TeraSMS да
id ID сообщения в системе да

Получение статусов нескольких сообщений одним запросом

Вы можете получать статусы нескольких сообщений, выполняя POST-запрос по адресу https://auth.terasms.ru/outbox/viber_status_bulk/xml или https://auth.terasms.ru/outbox/viber_status_bulk/json.

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

https://auth.terasms.ru/outbox/viber_status_bulk/xml

Запрос
<?xml version="1.0" encoding="UTF-8" ?>
<request>
    <login>login</login>
    <password>password</password>
    <ids>
        <id>111</id>
        <id>222</id>
        <id>333</id>
    </ids>
</request>
Ответ
<?xml version="1.0" encoding="UTF-8" ?>
<response>
    <messages>
        <message>
            <status>1</status>
            <status_name>отправлено</status_name>
        </message>
        <message>
            <status>1</status>
            <status_name>отправлено</status_name>
        </message>
        <message>
            <status>12</status>
            <status_name>доставлено</status_name>
        </message>
    </messages>
</response>

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

https://auth.terasms.ru/outbox/viber_status_bulk/json

Запрос
{
	"login": "login",
	"password": "password",
	"ids": [
		111, 222, 333
	]
}
Ответ
{
  "messages": [
    {
      "status": 1,
      "status_name": "отправлено"
    },
    {
      "status": 1,
      "status_name": "отправлено"
    },
    {
      "status": 12,
      "status_name": "доставлено"
    }
  ]
}

Описание статусов

Статус Описание
0 Сообщение принятно и находится в очереди на доставку
1 Сообщение отправлено в сеть Viber
2 Абонент не в сети, сообщение находится в очереди на отправку
4 Неизвестный статус, статус отправки от сети Viber не получен
5 Сообщение не доставлено (например, абонент не зарегистрирован в Viber)
12 Сообщение доставлено абоненту
13 Сообщение не было доставлено (истёк срок ожидания абонента в сети)
15 Получен отказ в передаче от сети Viber
255 Ошибка
256 В запросе не получение статуса передан неверный ID сообщения

«Каскадная» отправка сообщений

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