Comex HTTP API

Введение

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

• SMS;
• Viber;
• электронная почта;
• личные сообщения Вконтакте;
• Push-сообщения;
• WhatsApp;
• FlashCall;
• VoiceCall;

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

• статусы отправленных сообщений;
• входящие сообщения от абонентов.

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

• ID ноды - уникальный идентификатор клиентского подключения в системе. У каждого клиента может быть несколько нод (и соответственно идентификаторов) с индивидуальными параметрами каналов отправки

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

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

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

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

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

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

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

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

• URI - https://external-api.i-dgtl.ru/ <вызываeмое действие>;
• тип запроса - POST;
• Content-Type - application/json;
• авторизация - HTTP Basic;
• кодировка символов - UTF-8.

Авторизация

В 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мое действие>

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

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

ВАЖНО: все временные метки в протоколе 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 текста не должен превышать 1000 символов.

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

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

• content_type - image;
• image_URL -ссылка на изображение.

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

ВАЖНО:

• так как параметр content_type является строкой, двойные кавычки необходимо экранировать при помощи обратной косой черты;
• поддерживаемые форматы изображений - JPEG и PNG;
• оптимальный размер изображения - 400x400 пикселей;
• Viber может не отображать некоторые изображения в зависимости от платформы получателя (iOS, Android) и/или наличия HTTPS. Для генерации гарантированно корректной ссылки на изображение обратитесь в техническую поддержку i-Digital.

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

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

Параметры Viber-сообщения с изображением и кнопкой-ссылкой или кнопкой с номером телефона:

• content_type - button;
• text - текст сообщения;
• caption - имя кнопки;
• action - в качестве действия можно указать:
  • ссылку, на которую будет выполнен переход после нажатия на кнопку;
  • номер телефона в формате tel:+СХХХХХХХХХХ, где С – код страны, Х – номер телефона. После нажатия на кнопку пользователю будет предложено позвонить по номеру телефона.
• imageURL - ссылка на изображение, которое будет передано в сообщении.

ВАЖНО:

• длина имени кнопки не должна превышать 30 символов.

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-сообщения:

• html - формат почтового сообщения (HTML - true, plain text - false);
• content - полный текст сообщения (для сообщений в формате HTML передаётся со всеми необходимыми тэгами);
• senderName - отображаемое имя отправителя;
• subject - тема сообщения.

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 с дополнительными параметрами

• shortMessage - текст короткого сообщения, которое будет отображено на экране мобильного телефона сразу после получения;
• fullMessage - текст полного сообщения, которое будет отображено в приложении после нажатия на короткое сообщение.

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": "<код, введенный абонентом>"
            }

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

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

200 OK

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

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

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

WhatsApp

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

• поддерживается отправка сообщений в режиме чата:
  • если чат инициируется клиентом, первое сообщение должно соответствовать зарегистрированному шаблону. После каждого ответа абонента открывается 24 часовое окно для отправки сообщений с произвольным содержанием. Если абонент не ответил, клиент может отправлять сообщения пользователю вне рамок 24 часового окна с использованием заранее зарегистрированных шаблонов сообщений;
  • если чат инициируется абонентом, в течение 24 часового окна клиент может отправлять сообщения с произвольным содержанием.
• шаблонные сообщения могут содержать следующие типы контента:
  • текст;
  • кнопки с ссылками (URL и/или номер телефона);
  • кнопки с текстом (до 3 кнопок);
  • заголовок с текстом;
  • заголовок с изображением;
  • заголовок с документом;
  • подпись сообщения.
• сообщения, отправленные в период 24 часового окна, могут содержать любой тип контента;
• сообщения, содержащие заголовок, подпись, кнопки с ссылками или кнопки с текстом обязательно должны соответствовать зарегистрированному шаблону, независимо от момента отправки;
• весь медиаконтент, передаваемый в WhatsApp-сообщениях, является строкой: двойные кавычки необходимо экранировать при помощи обратной косой черты.

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

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

ВАЖНО:

• максимальная длина сообщения составляет 1000 символов;

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

{
                "@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-сообщения с изображением

• content_type - image;
• imageUrl - ссылка на изображение;
• imageName - подпись к изображению.

ВАЖНО:

• поддерживаемые форматы изображений - JPEG и PNG;
• оптимальный размер изображения - 400x400 пикселей;
• размер отправляемого изображения не должен превышать 100 МБ.

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

{
                "@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-сообщения с документом

• content_type - document (можно добавлять файл любого формата);
• documentUrl - ссылка на отправляемый в сообщении документ.

ВАЖНО:

• в виде документа может быть отправлен файл любого формата;
• размер отправляемого файла не должен превышать 100 МБ.

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

{
                "@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-сообщения с аудиофайлом

• content_type - audio;
• audioUrl - ссылка на отправляемый в сообщении аудиофайл.

ВАЖНО:

• поддерживаемые аудиоформаты: mp3, ogg, AAC;
• поддерживаемые кодеки: AMR, MPEG, Opu;
• размер отправляемого аудиофайла не должен превышать 100 МБ.

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

{
                "@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-сообщения с видеофайлом

• content_type - video;
• videoUrl - ссылка на отправляемый в сообщении видеофайл.

ВАЖНО:

• поддерживаемые видеоформаты: mp4;
• поддерживаемые кодеки: H.264 и AAC;
• размер отправляемого видеофайла не должен превышать 100 МБ.

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

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

Параметры WhatsApp-сообщения с кнопкой-ссылкой и номером телефона

• content_type – text;
• buttons – массив параметров, передаваемых с кнопками;
• text – имя, отображаемое на кнопке;
• url – ссылка, на которую будет выполнен переход после нажатия;
• phone – номер телефона в формате +СХХХ ХХХ-ХХ-ХХ, где С – код страны, Х – номер телефона.

ВАЖНО:

• максимальное количество кнопок - 2;
• может быть только одна кнопка со ссылкой на сайт;
• может быть только одна кнопка с номером телефона: при нажатии на неё пользователю будет предложено позвонить по номеру телефона;
• текст кнопки задаётся на этапе регистрации шаблона, максимальная длина текста кнопки составляет 20 символов;
  
• номер телефона задаётся на этапе регистрации шаблона.

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

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

Параметры WhatsApp-сообщения с кнопкой с текстом

• content_type – text;
• buttons – массив параметров, передаваемых с кнопками;
• text - имя кнопки;
• payload – скрытый текст, который будет передан во входящем сообщении, если пользователь нажмет на кнопку.

ВАЖНО:

• комбинировать кнопку с текстом с кнопкой-ссылкой не допускается;
• максимальное количество кнопок в сообщении – 3;
• максимальная длина текста кнопки составляет 20 символов;
  
• параметр «payload» является обязательным;
• максимальное количество символов для параметра «payload» - 128;
• все варианты текстов кнопок необходимо регистрировать заранее.

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

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

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

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

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

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

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

• content_type – text;
• header – заголовок;
• footer – подпись;
• documentUrl – ссылка на отправляемый в сообщении документ;
• documentName – имя документа;
• imageUrl – ссылка на изображение.

ВАЖНО:

• header и footer являются необязательными параметрами;
• максимальная длина заголовка и подписи составляет 60 символов каждый;
• отправлять одновременно в заголовке текст, изображение и документ не допускается;
• рекомендовано использовать изображение размером не меньше 400x400px с расширением JPG или PNG;
• формат документа – pdf.

VoiceCall

VoiceCall - это тип сообщений, в которых выполняется преобразование текста в речь при вызове абонентов.

          [
                {
                    "@type": "outbound",
                    "addresses": {
                        "source": "<имя/номер отправителя>",
                        "destination": "<номер телефона получателя>"
                    },
                    "body": {
                        "bodyType": "whatsapp",  
                    "content": [
                        {
                            "contentType": "<tts>"
                            "text": "<Текст, который будет преобразован в текст>"
                            "sex": "<female|male>"
                            "speed": "<1.2>"
                    },
                    "nodeId": <ID ноды>,
                    "requestDelivery": (true|false)
                }
            ]
        

ВАЖНО:

• для отправки голосового вызова с использованием системы автоматической генерации речи параметр contentType должен быть tts;
• через параметр sex для сообщения можно настроить пол голосового помощника, который будет озвучивать текст: female - женский, male - мужской;
• скорость зачитывания сообщения задается параметром speed. Возможные значения скорости:
• медленно - 0.5, 0.8;
• нормально - 1.0;
• быстро - 1.2, 1.5.

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

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

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

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

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

Коды ошибок

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

С помощью 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 сообщения>"
                  }
               ]
            }

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

Коды ошибок

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

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

Получение статуса по id сообщения

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

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

curl -H 'Content-Type: application/json'\
                 -H 'Accept: application/json' \
                 -H "Authorization: Basic  Mzk5OTk6MTIzNjU0" \
                 -d '{"msids": ["10147aa1-5766-8324-2973-aa0000000010", "10147aa1-5766-8324-2973-aa0000000011"]}'
                 -X POST

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

ВАЖНО:

• срок хранения статусов сообщений составляет 48 часов.

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

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

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

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

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

ВАЖНО:

• время получения статуса зависит от доступности абонента, качества сигнала мобильной сети и некоторых других технических параметров;
• временем ожидания статуса считается промежуток времени от отправки до даты, указанной в параметре expirationDate; по истечении этого промежутка возвращается статус EXPIRED;
• если оператор связи по тем или иным причинам не предоставляет код доставки, сообщение будет финализировано как недоставленное с кодом 127.
• статус EXPIRED_READ по умолчанию не передаётся; если вам нужно получать этот статус, обратитесь в службу технической поддержки или к вашему менеджеру.

HTTP Callback

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

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

• тип запроса - POST;
• URL:<host>:<port>/states;
• Authorization: Basic base64(login:pass)
• Content-Type - application/json

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

По умолчанию эндпоинт для получения статусов /states. Вы можете задать кастомное значение эндпоинта для получения статусов. Для этого необходимо вместе с адресом и портом вашего сервера укажите название эндпоинта.

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

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

Коды ошибок

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

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

SMS

Viber

WhatsApp

VK Notify

Push

FlashCall

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

Процесс получения входящих сообщений аналогичен получению статусов доставки. Максимальное количество единовременно запрашиваемых сообщений - 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).

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

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

Коды ошибок

HTTP Callback

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

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

• тип запроса - POST;
• URL: <host>:<port>/inbounds;
• Authorization: Basic base64(login:pass)
• Content-Type - application/json

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

По умолчанию эндпоинт для получения входящих сообщений /inbounds. Вы можете задать кастомное значение эндпоинта для получения входящих сообщений. Для этого необходимо вместе с адресом и портом вашего сервера укажите название эндпоинта.

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

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