WHATSAPP API

Общие сведения

API предоставляет интерфейс для автоматизации процесса отправки мгновенных сообщений WHATSAPP мессенджера через платформу Devino Telecom. С помощью API можно производить пакетные рассылки, отправлять транзакционные сообщения, а также осуществлять переотправку SMS в случае недоставки WHATSAPP сообщений одной командой.

Предупреждение

Внимание! Для использования данного вида интеграции необходимо обратиться к своему менеджеру для настройки доступа.

Работа с API осуществляется с использованием метода HTTP POST. Формат тела запроса клиента и ответа сервера представлены в формате JSON. Данные должны быть в кодировке UTF-8.

Данным методом можно отправлять не более 100 сообщений за один вызов.

API поддерживает basic-авторизацию через заголовок Authorization (https://en.wikipedia.org/wiki/Basic_access_authentication). В заголовке запроса необходимо передать логин и пароль из Личного Кабинета в формате login:password в base64 кодировке.

Например:

Authorization: Basic dGVzdGVyOjExMTExMQ==

Точка подключения:

https://im.devinotele.com

Используемые типы данных:

Тип данных Описание
Integer Положительные числа больше нуля
DateTime Значение, обозначающее дату и время, представляются в пакетах в формате «yyyy-MMdd hh:mm:ss», например, 1999-05-31 13:20:00
Address Адрес абонента. Номер мобильного телефона абонента в международном формате (в формате E.164). Например, 79031112233, для России или 491791112233 для Германии
String Строка символов в формате UTF-8

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

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

https://im.devinotele.com/send/whatsapp

Метод служит для отправки сообщения на указанные номера абонента. Параметры сообщения и адреса абонентов передаются в теле запроса в формате JSON.

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

Запрос на отправку текстового сообщения собирается с указанием contentType: «text». Возможна переотправка по СМС.

Пример запроса:

https://im.devinotele.com/send/whatsapp

{
    "resendSms": "true",
    "messages": [
        {
            "subject" : "Subject",
            "priority" : "high",
            "validityPeriodSec" : 3600,
            "comment" : "comment",
            "type" : "whatsapp",
            "contentType" : "text",
            "content" :
            {
                 "text" : "Message text"
            },
            "address" : "79250000000",
            "smsText":"1sms Message text",
            "smsSrcAddress":"1TEST",
            "smsValidityPeriodSec":5000
        }
    ]
}

Описание полей тела запроса отправки сообщения:

Параметр Тип данных Описание Обязательное поле
resendSms boolean

Признак переотправки сообщения, по умолчанию - false.

Допустимые значения:
  • true – переотправка включена,
  • false – переотправка выключена.
Нет
subject String

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

Все подписи предварительно должны регистрироваться на платформе Devino.

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

Да
priority String

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

  • low – низкий приоритет,
  • normal – нормальный приоритет,
  • high – высокий приоритет,
  • realtime – высочайший приоритет.
Да
validityPeriodSec Integer

Время ожидания доставки WHATSAPP сообщения в секундах.

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

Да
comment String Произвольный текстовый комментарий. Нет
type String

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

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

Да
contentType String
Тип содержимого сообщения:
  • text,
  • audio,
  • video,
  • image,
  • document.
Да
content Content

Содержимое сообщения.

Если contentType не text, то указывается URL на медиа-контент.

Да
address Address Номер телефона абонента, на который отправляется сообщение, в формате E.164 Да
smsText String Текст СМС сообщения Нет
smsSrcAddress String

Адрес отправителя СМС сообщения. Он должен быть согласован на SMS в Личном кабинете.

Длина имени не более 11 латинский символов

Нет
smsValidity PeriodSec Integer

Время ожидания доставки СМС сообщения.

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

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

Нет
Объект «Content»
Параметр Тип данных Описание contentType
text String Текст сообщения text
imageUrl String URL изображения image
videoUrl String URL видео video
videoName String Название видео video
documentUrl String URL документа document
documentName String Название документа document

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

{
    "status": "ok",
    "messages": [
        {
            "providerId" : 3158611117333282816,
            "code" : "ok"
        }
    ]
}

Описание полей ответа на запрос отправки сообщения:

Параметр Тип данных Описание Обязательное поле
status String

Статус ответа на запрос /send/whatsapp

Список возможных кодов и их значений указан в таблице кодов возврата

Да
providerId Integer

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

На стороне клиента providerId должно сохраняться для последующего запроса статуса сообщения.

Нет
code String

Код ответа провайдера для конкретного

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

Да

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

https://im.devinotele.com/status/whatsapp

Данный метод предназначен для проверки статусов по ранее полученным providerId на запросы «/send/whatsapp». В одном запросе можно передавать не более 100 ID сообщений.

Пример запроса:

https://im.devinotele.com/status/whatsapp

{
   "messages": [
       3158611117333282816,
       3158611117333282817,
       3158611117333282818
   ]
}

Пример ответа на запрос статуса доставки:

{
   "status": "ok",
   "messages": [
       {
           "providerId": 3158611117333282816,
           "code": "ok",
           "smsStates": [
               {
                   "id": 583465579822710784,
                   "state": "delivered"
               },
               {
                   "id": 583465579822710785,
                   "state": "delivered"
               }
           ]
       },
       {
           "providerId": 3158611117333282817,
           "code": "ok",
           "status": "delivered",
           "statusAt": "2016-08-10 15:28:50"
       },
       {
           "providerId": 3158611117333282818,
           "code": "ok",
           "smsStates": [
               {
                   "id": 583465579822710798,
                   "state": "delivered"
               }
           ]
       }
   ]
}

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

Параметр Тип данных Описание Обязательное поле
status String

Результат обработки запроса

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

Да
code String

Результат обработки запроса для конкретного сообщения с провайдеским идентификатором

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

Да
smsStates

Массив

(Составное поле)

Текущий статус доставки СМС сообщения.

Указывается, только если была переотправка сообщения.

Нет
smsStates.state String
Код статуса доставки СМС сообщения:
  • enqueued – сообщение находится в очереди на отправку;
  • sent – сообщение отправлено абоненту;
  • delivered – сообщение доставлено абоненту;
  • undelivered – сообщение отправлено, но не доставлено абоненту.
Нет
smsStates.id Long ID СМС сообщения с СМС-Центра провайдера. Если сообщение многосегментное, то будет возвращен ID для каждого сегмента сообщения и его статус. Да
Status String
Код статуса доставки WHATSAPP сообщения:
  • enqueued – сообщение находится в очереди на отправку;
  • sent – сообщение отправлено абоненту;
  • delivered – сообщение доставлено абоненту;
  • read – сообщение просмотрено абонентом.
  • undelivered – сообщение отправлено, но не доставлено абоненту;
  • failed – сообщение не было отправлено в результате ошибки;
  • cancelled –отправка сообщения отменена;
  • vp_expired – сообщение просрочено, финальный статус не получен в рамках заданного validity period
Да
statusAt DateTime Дата и время получения статуса по UTC Да
errorCode String
Причина, недоставки сообщения:
  • USER_BLOCKED – пользователь заблокирован
  • NOT_TEMPLATE_MATCH - шаблон не найден
Нет

Прием статусов с помощью callback-запросов

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

При получении статуса сообщения от WHATSAPP платформа Devino отправляет HTTP-POST запрос (JSON, UTF-8) на URL сервера. В случае, если сервер возвращает ошибку или не предоставляет ответ, то платформа будет совершать повторные запросы в течение 24 часов.

Ответ сообщающий о приеме должен быть 200 OK с пустым телом запроса.

Предупреждение

Внимание! Для подключения URL для приема статусов WHATSAPP-сообщений обратитесь к вашему менеджеру или напишите письмо в техническую поддержку support@devinotele.com

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

[
    {
        "id": 3158611117333282816,
        "receivedAt": "1527861323068",
        "status": "undelived",
        "errorCode": "error"
    }
]

Описание полей запроса со статусами доставки

Параметр Тип данных Описание Обязательное поле
id Long Уникальный идентификатор сообщения на платформе Да
receivedAt timestamp Дата и время получения статуса Да
Status String
Код статуса доставки WHATSAPP сообщения.
  • enqueued – сообщение находится в очереди на отправку.
  • sent – сообщение отправлено абоненту
  • delivered – сообщение доставлено абоненту.
  • read – сообщение просмотрено абонентом.
  • visited абонент перешел по ссылке в сообщении.
  • undelivered – сообщение отправлено, но не доставлено абоненту.
  • failed – сообщение не было отправлено в результат сбоя.
  • cancelled – отправка сообщения отменена.
  • vp_expired – сообщение просрочено, финальный статус не получен в рамках заданного validity period
Да
errorCode String
Причина, недоставки сообщения
  • USER_BLOCKED – пользователь заблокирован
  • NOT_TEMPLATE_MATCH - шаблон не найден
Нет

Прием входящих сообщений

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

Платформа Devino передает HTTP-POST запрос с данными в формате JSON по URL сервера, содержащий пачку новых входящих WHATSAPP-сообщений по факту обработки платформой.

Предупреждение

Внимание! Для подключения URL для приема входящих WHATSAPP-сообщений обратитесь к вашему менеджеру или напишите письмо в техническую поддержку support@devinotele.com

В случае, если сервер возвращает ошибку или не предоставляет ответ, то платформа будет совершать повторные запросы в течение 1 часа.

Ответ сообщающий о приеме должен быть 200 OK с пустым телом запроса.

Пример запроса отправляемого на URL:

 [
     {
         "id": 2,
         "parentId": 1,
         "receivedAt": "2007-11-29 00:00:00",
         "subject": "test",
         "address": "7916123456789",
         "contentType": "text",
         "content": "balance"
     }
]

Описание полей запроса с входящими сообщениями

Параметр Тип данных Описание Обязательное поле
id Long Уникальный идентификатор входящего сообщения на платформе Да
parentId Long

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

Если равен нулю, то исходящее сообщение в за последние сутки не найдено.

Да
receivedAt DateTime Время получения входящего сообщения поставщиком Да
subject String Адрес отправителя, с которого было отправлено исходящее сообщение Да
address String Номер телефона, с которого отправлено входящее сообщение Да
contentType String
Возможные значения:
  • text
  • image
  • audio
  • video
  • document
Да
contentName String Название переданного пользователем файла Да
content String URL на контент или текст сообщения Да

Таблица кодов возврата

Коды возврата обработки запроса (status)

Код Описание
ok Запрос был успешно обработан
error-syntax ошибка синтаксиса
error-auth ошибка аутентификации
error-system системная ошибка
error-account-locked аккаунт клиента заблокирован
error-instant-message-typeformat неправильный формат типа исходящего сообщения
error-instant-message-content-type-format неправильный формат типа содержимого сообщения
error-instant-message-content-image-id-format неправильный формат идентификатора изображения для содержимого сообщения

Коды возврата обработки сообщения в рамках запроса (code)

Код Описание
ok исходящее сообщение успешно принято на отправку
error-system системная ошибка
error-instant-message-client-id-not-unique клиентский идентификатор сообщения не уникален в рамках всего взаимодействия между клиентом и провайдером.
error-subject-format неправильный формат подписи
error-subject-unknown указанная подпись не разрешена клиенту в конфигурации платформы провайдера
error-subject-not-specified подпись не указана
error-address-format неправильный формат номера абонента
error-address-unknown отправка на номерную емкость, к которой относится номер абонента не разрешена клиенту в конфигурации платформы провайдера
error-address-not-specified номер абонента не указан
error-priority-format неправильный формат значения приоритета
error-comment-format неправильный формат значения комментария
error-instant-message-type-format неправильный формат типа сообщения
error-instant-message-type-not-specified неправильный формат типа содержимого сообщения
error-content-type-format неправильный формат содержимого сообщения
error-content-not-specified содержимое сообщения не указано
error-validity-period-seconds-format неправильно указано значение времени ожидания доставки
error-instant-message-provider-id-format неправильный формат провайдерского идентификатора
error-instant-message-provider-id-duplicate провайдерский идентификатор исходящего сообщения неуникален в рамках запроса проверки статуса
error-instant-message-provider-id-unknown исходящее сообщение с данным провайдерским идентификатором не найдено на платформе провайдера
error-resend-sms-error указаны поля для переотправки смс но переотправка не включена
error-resend-sms-validity-period-error неверное время жизни для смс