Comex HTTP API

Справочное руководство

Введение

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

Также с помощью сервиса вы можете получать:

Термины и определения

Условные обозначения

Во всех примерах запросов используются обозначения в треугольных скобках, например <имя отправителя>. Вместо такого обозначения при выполнении запроса нужно использовать значение соответствующего параметра.

Обозначения в круглых скобках указывают на возможные варианты содержимого, если их количество ограничено - например, (true|false). В запросе следует указывать только один из вариантов, разделенных вертикальной чертой.

Взаимодействие с сервисом

Взаимодействие с сервисом осуществляется через REST API с помощью стандартных HTTP-запросов.

Структура запроса:

Авторизация

В API используется аутентификация на основе базовой схемы. При регистрации каждый пользователь получает ID ноды (идентификатор подключения) и пароль. Для авторизации нужно перекодировать эти параметры, разделённые двоеточием, в формат base64. Пример для ОС семейства Linux (39999 - ID ноды, 123654 - пароль):

echo -n '39999:123654' | base64

Вывод приведённой команды выглядит так:

Mzk5OTk6MTIzNjU0

Эту строку нужно передавать во всех запросах в заголовке Authorization. Пример запроса к Comex HTTP API с помощью утилиты cURL:

curl -X POST -H "Content-Type: application/json" -H "Authorization: Basic Mzk5OTk6MTIzNjU0" -d '<содержимое запроса>' https://external-api.i-dgtl.ru/<вызываeмое действие>

Принципы формирования содержимого запроса описаны ниже.

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

Параметр Тип Значение
@type string Тип сообщения (входящее или исходящее); имеет постоянное значение оutbound (исходящее)
addresses object Объект, содержащий адреса отправителя и получателя
source string Имя или адрес отправителя
destination string Адрес или номер телефона получателя
body object Объект, в котором передаётся содержимое сообщения
bodyType string Тип сообщения (SMS, e-mail, ВКонтакте, Viber, push, WhatsApp, FlashCall)
content string Содержимое сообщения (подробнее см. в примерах ниже)
nodeId integer Номер ноды
requestDelivery boolean Указывает, cледует ли предоставлять отчёт о доставке после отправки сообщения
expirationDate timestamp Время, до которого будет ожидаться получение статуса от оператора (timestamp в миллисекундах или в формате ISO 8601). По умолчанию составляет 24 часа с момента отправки сообщения. Если статус к этому времени не будет получен, возвращается ошибка 127 (см. описание ниже)

ВАЖНО: все временные метки в протоколе Comex передаются в формате Unixtime с учетом миллисекунд. Это отличается от наиболее распространенной реализации, где в основном используются секунды

Номер телефона указывается в международном формате MSISDN, состоящем из кода страны, DEF-кода оператора и номера абонента. Например, российский номер выглядит так: 79001234567, где 7 - код страны (Россия). Если клиент по той или иной причине использует другой формат номеров (со скобками, с дополнительными символами и т.п.), можно настроить автоматическую конвертацию номеров в MSISDN. Правила конвертации оговариваются с каждым клиентом индивидуально.

Будьте внимательны при использовании в SMS следующих символов:

£,¥,è,é,ù,ì,ò,Ç,Ø,ø,Å,å,Δ,Φ,Γ,Λ,Ω,Π,Ψ,Σ,Θ,Ξ,Æ,æ,ß,É,¤,¡,Ä,Ö,Ñ,Ü,§ ¿,ä,ö,ñ,ü,à,
                                        NUL,SOH,STX,ETX,EOT,ENQ,ACK,BEL,BS,TAB,VT,SO,SI,DLE,DC1,DC2,DC3,DC4,NAK,
                                        SYN,ETB,CAN,EM,SUB,FS,GS,RS,US,`,DEL. 

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

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

URI: https://external-api.i-dgtl.ru/message

SMS

 {
                                            "@type": "outbound",
                                            "addresses": {
                                                "source": "<имя отправителя>",
                                                "destination": "<номер телефона получателя>"
                                            },
                                            "body": {
                                                "bodyType": "text",
                                                "content": "<текст сообщения>"
                                            },
                                            "nodeId": "<ID ноды>",
                                            "requestDelivery": (true|false)
                                        }

Viber

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

 {
                                            "@type": "outbound",
                                            "addresses": {
                                                "source": "<имя отправителя>",
                                                "destination": "<номер телефона получателя>"
                                            },
                                            "body": {
                                                "bodyType": "viber",
                                                "content": "<текст сообщения>"
                                            },
                                            "nodeId": <ID ноды>,
                                            "requestDelivery": (true|false)
                                        }

ВАЖНО:

Отправка сообщения с графическим вложением

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

{
                                           "@type": "outbound",
                                           "addresses": {
                                               "source": "<имя отправителя>",
                                               "destination": "<номер телефона получателя>"
                                           },
                                           "body": {
                                               "bodyType": "viber",
                                               "content": "{\"content_type\":\"image\",\"imageUrl\":\"<ссылка на изображение>\"}"
                                           },
                                           "nodeId": <ID ноды>,
                                           "requestDelivery": (true|false)
                                        }

ВАЖНО:

Отправка сообщения с интерактивными элементами (изображением и кнопкой)

{
                                          "@type": "outbound",
                                          "addresses": {
                                              "source": "<имя отправителя>",
                                              "destination": "<номер телефона получателя>"
                                          },
                                          "body": {
                                              "bodyType": "viber",
                                              "content": "{\"content_type\":\"button\",\"text\":\"<текст сообщения>\",\"caption\":\"<текст кнопки>\",\"action\":\"<ссылка на сайт>\",\"imageUrl\":\"<ссылка на изображение>\"}"
                                          },
                                          "nodeId": <ID ноды>,
                                          "requestDelivery": (true|false)
                                        }

Параметры Viber-сообщения c интерактивными элементами:

ВАЖНО:

E-mail

 {
                                           "@type": "outbound",
                                           "addresses": {
                                               "source": "<email-адрес отправителя>",
                                               "destination": "<email-адрес получателя>"
                                           },
                                           "body": {
                                               "bodyType": "email",
                                               "html": (true|false),
                                               "content": "<содержимое письма>",
                                               "senderName": "<отображаемое имя отправителя>",
                                               "subject": "<тема письма>"
                                           },
                                           "nodeId": <ID ноды>,
                                           "requestDelivery": (true|false)
                                        }

Параметры e-mail-сообщения:

VK Notify

{
                                            "@type": "outbound",
                                            "addresses": {
                                                "source": "<имя отправителя>",
                                                "destination": "<номер телефона получателя>"
                                            },
                                            "body": {
                                                "bodyType": "vk",
                                                "content": "<текст сообщения>"
                                            },
                                            "nodeId": <ID ноды>,
                                            "requestDelivery": (true|false)
                                        }

Push

Пример 1

{
                                            "@type": "outbound",
                                            "addresses": {
                                                "source": "<имя отправителя>",
                                                "destination": "<номер телефона получателя>"
                                            },
                                            "body": {
                                                "bodyType": "push",
                                                "content": "<текст сообщения>"
                                            },
                                            "nodeId": <ID ноды>,
                                            "requestDelivery": (true|false)
                                        }

Пример 2

{
                                            "@type": "outbound",
                                            "addresses": {
                                                "source": "<имя отправителя>",
                                                "destination": "<номер телефона получателя>"
                                            },
                                            "body": {
                                                "bodyType": "push",
                                                "content": "<текст сообщения>"
                                            },
                                            "properties": {
                                                "pushParameters": {
                                                    "shortMessage": "Test",
                                                    "fullMessage": "Текст тестового сообщения"
                                                }
                                            },
                                            "nodeId": <ID ноды>,
                                            "requestDelivery": (true|false)
                                        }

Во втором примере в запросе содержитcя объект properties -> pushParameters с дополнительными параметрами

Вызовы FlashCall

FlashCall - звонок с номера, последние цифры которого являются кодом авторизации/подтверждения.

{
                                            "@type": "outbound",
                                            "addresses": {
                                                "source": "<имя отправителя>",
                                                "destination": "<номер телефона получателя>"
                                            },
                                            "body": {
                                                "bodyType": "flashcall",
                                                "content": "<текст сообщения>"
                                            },
                                            "nodeId": <ID ноды>,
                                            "requestDelivery": (true|false)
                                        }

В запросе на отправку вызова FlashCall в качестве значения параметра content можно указать как последовательность от 4 до 6 цифр, так и произвольный текст. В последнем случае в качестве кода будет по умолчанию выбрана первая последовательность от 4 до 6 цифр без пробелов, встречающаяся в тексте.

Если вам нужно настроить подбор кода по индивидуальным правилам, обратитесь к вашему менеджеру или в службу технической поддержки.

Передача конверсии для FlashCall-вызовов

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

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

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

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

URI: https://external-api.i-dgtl.ru/conversion

{
                                            "msid": "<msid сообщения>",
                                            "result": "(NUMBER_VERIFIED|WRONG_CODE)",
                                            "code": "<код, введенный абонентом>"
                                        }

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

Параметр Тип Значение
msid string Уникальный идентификатор сообщения на платформе i-Digital. Передаётся клиенту при отправке сообщения.
result string Результат проверки введенного пользователем кода.
Возможные значения:
  • NUMBER_VERIFIED - передается в случае, если абонент ввел код, который совпадает с тем, что был отправлен
  • WRONG_CODE - передается в случае, если абонент не ввел код или введенный код не совпадает с тем, что был отправлен
code string Код, который ввел абонент. Необязательный параметр. Рекомендуется передавать для дополнительной аналитики случаев, когда абонент неверно ввел код.

Пример успешного ответа

200 OK

Пример не успешного ответа

{
                                            "timestamp": <время отправки запроса>,
                                            "path": "/conversion",
                                            "status": <код ошибки>,
                                            "error": "<Текст ошибки>",
                                            "message": "<Описание ошибки>",
                                            "requestId": "<id запроса к сервису>"
                                        }

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

Параметр Тип Значение
timestamp timestamp Время отправки сообщения в формате Unix Timestamp
path string Имя метода, на который осуществляется ответ
status intrger Код ошибки
error string Текст ошибки
message string Описание ошибки
requestId string Идентификатор запроса к сервису

WhatsApp

{
                                            "@type": "outbound",
                                            "addresses": {
                                                "source": "<имя отправителя>",
                                                "destination": "<номер телефона получателя>"
                                            },
                                            "body": {
                                                "bodyType": "whatsapp",
                                                "content": "<текст сообщения>"
                                            },
                                            "nodeId": <ID ноды>,
                                            "requestDelivery": (true|false)
                                        }

ВАЖНО:

Отправка сообщения с графическим вложением

{
                                            "@type": "outbound",
                                            "addresses": {
                                                "source": "<имя отправителя>",
                                                "destination": "<номер телефона получателя>"
                                            },
                                            "body": {
                                                "bodyType": "whatsapp",
                                                "content": "{\"content_type\":\"image\",\"imageUrl\":\"http://example.com/my-image.png\",\"imageName":\"<подпись к изображению>\"}"
                                            },
                                            "nodeId": <ID ноды>,
                                            "requestDelivery": (true|false)
                                        }

Параметры WhatsApp-сообщения с графическим вложением

ВАЖНО:

Отправка сообщения с вложенным текстовым документом

{
                                            "@type": "outbound",
                                            "addresses": {
                                                "source": "<имя отправителя>",
                                                "destination": "<номер телефона получателя>"
                                            },
                                            "body": {
                                                "bodyType": "whatsapp",
                                                "content":  "{\"content_type\":\"document\",\"documentUrl\":\"http://bank.ru/docs/tarif123.pdf\",\"documentName\":\"Новые тарифы на 2019 год\"}"
                                            },
                                            "nodeId": <ID ноды>,
                                            "requestDelivery": (true|false)
                                        }

Параметры WhatsApp-сообщения с вложенным документом

ВАЖНО:

Отправка сообщения с вложенным аудиофайлом

{
                                            "@type": "outbound",
                                            "addresses": {
                                                "source": "<имя отправителя>",
                                                "destination": "<номер телефона получателя>"
                                            },
                                            "body": {
                                                "bodyType": "whatsapp",
                                                "content":  "{\"content_type\":\"audio\",\"audioUrl\":\"http://example.com/audios/hello.mp3\"}"
                                            },
                                            "nodeId": <ID ноды>,
                                            "requestDelivery": (true|false)
                                        }

Параметры WhatsApp-сообщения с вложенным аудиофайлом

ВАЖНО:

Отправка сообщения с вложенным видеофайлом

{
                                            "@type": "outbound",
                                            "addresses": {
                                                "source": "<имя отправителя>",
                                                "destination": "<номер телефона получателя>"
                                            },
                                            "body": {
                                                "bodyType": "whatsapp",
                                                "content": "{\"content_type\":\"video\",\"videoUrl\":\"http://example.com/videos/hello.mp4\",\"videoName\":\"Добро пожаловать\"}"
                                            },
                                            "nodeId": <ID ноды>,
                                            "requestDelivery": (true|false)
                                        }

Параметры WhatsApp-сообщения с вложенным видеофайлом

ВАЖНО:

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

В ответ на все приведённые выше примеры запросов API возвращает ответ вида:

{
                                            "id": "<MSID сообщения>",
                                            "timestamp": <время отправки сообщения>,
                                            "code": <код ответа сервиса>
                                        }

Ответ содержит следующие параметры:

Параметр Тип Значение
id string ID сообщения
timestamp timestamp время отправки сообщения в формате Unix Timestamp
code integer код ответа (в случае успешного выполнения запроса - 200 OK)

ВАЖНО: * все временные метки в протоколе Comex передаются в формате Unixtime с учетом миллисекунд. Это отличается от наиболее распространенной реализации, где в основном используются секунды

Коды ошибок

Код ошибки Описание
200 Успешно
400 Неверный синтаксис запроса
401 Ошибка авторизации
403 Доступ запрещён
405 Метод запроса отключён и не может быть использован
415 Некорректное значение заголовка Content-Type
451 В запросе содержатся запрещённые к использованию слова

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

С помощью API можно отправлять не только одиночные сообщения, но и группы (пакеты) сообщений.

URI: https://external-api.i-dgtl.ru/pack

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

[
                                            {
                                                "@type": "outbound",
                                                "addresses": {
                                                    "source": "<имя отправителя>",
                                                    "destination": "<номер телефона получателя #1>"
                                                },
                                                "body": {
                                                    "bodyType": "text",
                                                    "content": "<текст сообщения>"
                                                },
                                                "nodeId": <ID ноды>,
                                                "requestDelivery": (true|false)
                                            },
                                            {
                                                "@type": "outbound",
                                                "addresses": {
                                                    "source": "<имя отправителя>",
                                                    "destination": "<номер телефона получателя #2>"
                                                },
                                                "body": {
                                                    "bodyType": "text",
                                                    "content": "<текст сообщения>"
                                                },
                                                "nodeId": <ID ноды>,
                                                "requestDelivery": (true|false)
                                            }
                                        ]

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

Максимальное количество сообщений в пакете составляет 100.

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

В ответ на запрос API возвращает ID, время отправки и код ответа для каждого сообщения из пакета:

{
                                           "timestamp": "<время отправки пакета сообщений>",
                                           "code": 200,
                                           "responses": [
                                              {
                                                 "timestamp": "<время отправки сообщения>",
                                                 "code": 200,
                                                 "id": "<MSID сообщения>"
                                              },
                                              {
                                                 "timestamp": "<время отправки сообщения>",
                                                 "code": 200,
                                                 "id": "<MSID сообщения>"
                                              }
                                           ]
                                        }

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

Параметр Тип Значение
id string ID сообщения
timestamp timestamp время отправки сообщения в формате Unix Timestamp
code integer код ответа (в случае успешного выполнения запроса - 200 OK)

Коды ошибок

Код ошибки Описание
401 Ошибка авторизации
413 Превышено количество сообщений в пакете
452 Сработала блокировка по стоп-словам

Каскадная отправка

Каскадной отправкой называется технология переотправки сообщения по различным каналам. Последовательность каналов настраивается по согласованию с клиентом. При поступлении сообщение будет направлено в канал с наивысшим приоритетом; в случае недоставки оно будет переотправлено в следующий канал. Переотправка продолжится до тех пор, пока не будет получен статус “Доставлено” или пока не будут использованы все возможные каналы. Например, если push-сообщение по той или иной причине не поступает на мобильное устройство пользователя, его содержание может быть переотправлено в виде SMS.

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

Отправка сообщений с одинаковым содержимым

Если при каскадной отправке не требуется отображение разного содержимого через разные каналы доставки, поле bodyType может содержать значение text и иметь такое же содержимое, как при отправке SMS.

Отправка сообщений с разным содержимым

{
                                            "@type": "outbound",
                                            "addresses": {
                                                "source": "<имя отправителя>",
                                                "destination": "<номер телефона получателя>"
                                            },
                                            "body": {
                                                "bodyType": "generic",
                                                "content": [
                                                    {
                                                        "bodyType": "viber",
                                                        "content": "<текст сообщения>"
                                                    },
                                                    {
                                                        "bodyType": "text",
                                                        "content": "<текст сообщения>"
                                                    }
                                                ]
                                            },
                                            "nodeId": <ID ноды>,
                                            "requestDelivery": (true|false)
                                        }

В запросах на каскадную отправку сообщений с разным содержимым параметр bodyType имеет значение generic. Такой синтаксис используется для отправки массива объекта body разного типа. Таким образом при каскадной отправке вы можете комбинировать любой из доступных способов отправки, описанных выше, указывая необходимое содержимое для каждого типа канала.

Получение статусов доставки

Получение статусов доставки возможно только в случае, если при отправке сообщения указано значение параметра requestDelivery: true. Время получения статуса зависит от доступности абонента и качества сигнала мобильной сети.

Получать статусы можно двумя способами: * с помощью запроса к API: вы выполняете запрос и получаете статусы, доступные на момент выполнения; * с помощью сервиса HTTP Callback: в этом случае запросы будут поступать на ваш сервер, и вы будете получать статусы по мере их поступления.

Запрос к API

URI: https://external-api.i-dgtl.ru/receive

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

curl -H 'Content-Type: application/json'\
                                             -H 'Accept: application/json' \
                                             -H "Authorization: Basic  Mzk5OTk6MTIzNjU0" \
                                             -d '10' \
                                             'https://external-api.i-dgtl.ru/receive'
                                             -X POST

В теле запроса передаётся количество сообщений, статусы которых нужно включить в ответ. В приведённом примере в теле запроса передаётся число 10, и это значит, что в ответ будет включена информация о последних 10 отправленных сообщениях. Максимальное количество запрашиваемых статусов не должно превышать 1000.

ВАЖНО:

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

{
                                           "timestamp": "<время генерации ответа>",
                                           "code": 200,
                                           "states": [
                                              {
                                                 "@type": "state",
                                                 "msid": "<MSID сообщения>",
                                                 "status": "<статус сообщения>",
                                                 "creationDate": "<время генерации статуса>",
                                                 "errorCode": <код ошибки>,
                                                 "final": (true|false)
                                              },
                                              {
                                                 "@type": "state",
                                                 "msid": "<MSID сообщения>",
                                                 "status": "<статус сообщения>",
                                                 "creationDate": "<время генерации статуса>",
                                                 "errorCode": <код ошибки>,
                                                 "final": (true|false)
                                              },
                                              ...
                                           ]
                                        }

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

Параметр Тип Значение
timestamp timestamp Время отправки сообщения в формате Unix Timestamp
code integer Код ответа
responses array Массив со статусами сообщений. Последовательность сообщений в массиве соответствует их последовательности в запросе

Параметры сообщения в массиве

Параметр Тип Значение
@type string Тип ответа (в запросах на получение статусов - state)
msid string UUID сообщения
status string Статус сообщения (cм. ниже)
creationDate timestamp Дата формирования статуса
errorCode integer Код ошибки (см. ниже)
final boolean Указывает, является ли статус сообщения финальным

Cтатусы сообщений

Статус Описание
DELIVERED Сообщение доставлено абоненту
UNDELIVERED Сообщение не доставлено
EXPIRED Время ожидания статуса истекло
READ Сообщение прочитано
EXPIRED_READ Сообщения было доставлено, но статус READ не был получен за необходимое время.

ВАЖНО:

HTTP Callback

Чтобы воспользоваться сервисом HTTP Callback, вам потребуется сообщить нам адрес и порт вашего сервера, на который будут приходить статусы. Сервис HTTP Callback периодически проверяет доступность вашего сервера, отправляя GET-запрос на адрес <host>/ping. Если ваш сервер доступен и возвращает ответ с кодом 200 OK, вам будут отправлены доступные на текущий момент статусы.

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

В качестве значений параметров <host> и <host> вам потребуется указать адрес и порт вашего сервера.

В теле запроса передаётся точно такой же JSON-объект, как в ответе на запрос статусов (см. выше).

В ответ на запрос ваш сервер должен вернуть код 200 OK или 202 (Accepted). Если ваш сервер вернёт другой код, будет предпринята повторная попытка отправки согласно заданным правилам. Правила оговариваются с каждым пользователем индивидуально.

Коды ошибок

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

Общие коды ошибок

Код ошибки Текст сообщения об ошибке Описание ошибки
11 error-address-format Номер получателя указан некорректно или не существует
127 Timeout of getting status Истекло время ожидания статуса сообщения
6969 Error without additional information Неизвестная ошибка

SMS

Код ошибки Текст сообщения об ошибке Описание ошибки
501 Unknown subscriner Номер получателя указан некорректно или не существует
502 SMSC failure Ошибка центра передачи сообщений (SMSC) на стороне конечного оператора.
504 The subscriber is absent or out of coverage Устройство абонента выключено или находится вне зоны действия сети
505 Call bar service activated У абонента включен запрет на прием сообщений или абонента заблокировал оператор (возможно, в связи с отрицательным балансом).
508 Teleservice not provisioned Сервис коротких сообщений не предоставляется
509 Roaming restrictions Абонент находится в роуминге
510 A2P messages blocked SIM-карта абонента заменена менее суток назад
511 Message queue full Очередь сообщений со стороны оператора переполнена
515 Equipment protocol error Аппаратная ошибка телефона абонента
517 Memory capacity exceeded Память телефона абонента переполнена
518 SS7 routing error Ошибка центра передачи сообщений (SMSC) на стороне конечного оператора.
523 Subscriber is busy Устройство абонента занято операцией, препятствующей получению короткого сообщения
525 IMSI error Ошибка на стороне оператора при запросе IMSI
557 Internal system failure Внутренняя ошибка системы на стороне конечного оператора
647 Illegal subscriber Абонент не зарегистрирован или заблокирован оператором

Viber

Код ошибки Текст сообщения об ошибке Описание ошибки
601 not-viber-user Абонент не является пользователем Viber
605 user-blocked Абонент заблокировал рассылку
607 not-suitable-device Устройство абонента не поддерживает сервис Viber
614 error-caption-too-long Превышена длина имени кнопки
618 filtered Сообщение содержит запрещенные к использованию слова

WhatsApp

Код ошибки Текст сообщения об ошибке Описание ошибки
605 user-blocked Абонент заблокировал рассылку
617 not-template-match Не найден подходящий шаблон сообщения
618 filtered Сообщение содержит запрещенные к использованию слова

VK Notify

Код ошибки Текст сообщения об ошибке Описание ошибки
250 NOT ENOUGH DATA Не хватает обязательных параметров
251 INCORRECT_SIGNATURE Некорректная подпись сообщения
252 ERROR Устройство абонента не поддерживает сервис Viber
253 UNSUPPORTED_NUMBER Номер не поддерживается (неподдерживаемая страна или оператор)
254 INCORRECT_NUMBER Некорректный формат номера
255 NUMBER_IN_BLACK_LIST Номер абонента занесен в черный список
256 NUMBER_TYPE_NOT_ALLOWED Номер абонента виртуальный или определен как «спамерский»
258 DAILY_RATELIMIT_FOR_RECEIVER Превышен дневной лимит отправки сообщений от группы ВКонтакте для данного номера.
259 UNSUPPORT Сообщение не может быть доставлено по одной из причин: - данного абонента (пользователя) не существует в системе; - абонент проявлял активность в системе более 7 дней назад.
260 UNSUPPORTED TEMPLATE Параметр text не соответствует ни одному шаблону.
261 UNKNOWN Неизвестный тип ошибки (возможен при получении неизвестного статуса от ВКонтакте)
262 BLOCKED_BY_USER Абонент запретил прием сообщений от данного отправителя (группы)
357 RATELIMIT Превышен лимит отправки сообщений ВКонтакте для данного номера

Push

Код ошибки Текст сообщения об ошибке Описание ошибки
700 recipient-is-locked Абонент заблокирован на платформе вручную
701 recipient-not-found Абонент не найден
702 recipient-has-no-active-device Устройство абонента неактивно
703 device_not_found Устройство абонента не найдено
704 client_application_removed Приложение удалено с устройства абонента
705 subscription-disabled Абонент отписался от push-сообщений
707 application-not-configured Приложение не настроено на платформе или в настройках приложения не указаны обязательные параметры
708 device-unregistered Устройство не зарегистрировано на платформе
709 certificate-expired Истек срок действия сертификата iOS-устройства

FlashCall

Код ошибки Текст сообщения об ошибке Описание ошибки
263 unknown-error Неизвестная ошибка
265 invalid-message Невалидное сообщение
266 destination-denied Направление или оператор не поддерживается
267 number-generation-failed Не удалось подобрать номер для передачи кода
268 duplicate Сообщение является дубликатом (дублированием считается отправка сообщения на один и тот же номер в течение минуты)

Приём сообщений от абонентов

Процесс получения входящих сообщений аналогичен получению статусов доставки. Максимальное количество единовременно запрашиваемых сообщений - 100. Как и статусы, cообщения можно получать как с помощью запросов к API, так и с помощью сервиса HTTP Callback.

Запрос к API

URI: https://external-api.i-dgtl.ru/receiveinbound

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

curl  -H 'Content-Type: application/json'\
                                              -H 'Accept: application/json' \
                                              -H'Authorization: Basic Mzk5OTk6MTIzNjU0' \
                                              -d '10'\
                                              https://external-api.i-dgtl.ru/receiveinbound\
                                              -X POST

В теле запроса передаётся количество сообщений, который будут включены в ответ. Приведённом примере в ответ на запрос API вернёт 10 сообщений (-d ‘10’). Число запрашиваемых сообщений не должно превышать 100.

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

  {
                                          "timestamp": 1570530342388,
                                          "code": <код ответа>,
                                          "messages": [
                                            {
                                              "@type": "inbound",
                                              "properties": {},
                                              "creationDate": 1570439178438,
                                              "requestDelivery": false,
                                              "addresses": {
                                                "source": "<имя или адрес отправителя>",
                                                "destination": "<адрес или номер телефона получателя>"
                                              },
                                              "body": {
                                                "bodyType": "<тип сообщения>",
                                                "content": "<текст сообщения>"
                                              },
                                              "expirationDate": <timestamp>,
                                              "msid": "<MSID сообщения>"
                                            }
                                          ]

Как видно из приведённых примеров, структура ответа ничем не отличается от структуры ответа, возвращаемого при отправке, за исключением параметра @type (для входящих сообщений он имеет значение inbound).

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

Параметр Тип Значение
timestamp timestamp время отправки сообщения в формате Unix Timestamp
code integer код ответа (в случае успешного выполнения запроса - 200 OK)
messages object объект, cодержащий принятые сообщения

Параметры сообщения в массиве

Параметр Тип Значение
@type string Тип сообщения (входящее или исходящее); в данном случае имеет значение inbound
properties string Служебный параметр
сreationDate timestamp время создания сообщения
requestDelivery boolean Указывает, был ли запрошен для сообщения отчёт о доставке
addresses object Объект, содержащий адреса отправителя и получателя
source string Имя или адрес отправителя
destination string Адрес или номер телефона получателя
body object Объект, который содержит параметры bodyType и content
bodyType string Тип сообщения (SMS, e-mail, ВКонтакте, Viber, push, WhatsApp)
content string Содержимое сообщения (подробнее см. в примерах выше)
expirationDate timestamp Срок (дата и время), до которого будут повторяться попытки доставить сообщение. Указывается в формате в формате unixtime или ISO-8601 (например, 2017-01-01T00:00:00Z)
msid string UUID сообщения

Коды ошибок

Код ошибки Описание
401 Ошибка авторизации
413 Превышено количество сообщений в пакете

HTTP Callback

Получение входящих сообщений происходит точно так же, как и получение статусов. Вам потребуется сообщить нам адрес и порт вашего сервера, на который будут поступать входящие сообщения. Так же, как и при получении статусов, сервис HTTP Callback будет периодически проверять доступность вашего сервера, отправляет GET-запрос на <host>:<port>/ping. Если ваш сервер доступен, вы получите все доступные на текущий момент входящие сообщения.

Входящие сообщения будут передаваться на ваш сервер в запросе, который имеет следующую структуру:

В качестве значений параметров <host> и <host> вам потребуется указать адрес и порт вашего сервера.

В теле запроса передаётся точно такой же JSON-объект, как в ответе на запрос статусов (см. выше).

В ответ на запрос ваш сервер должен вернуть код 200 OK или 202 (Accepted). Если ваш сервер вернёт другой код, будет предпринята повторная попытка отправки согласно заданным правилам. Правила оговариваются с каждым пользователем индивидуально.