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

Протокол JSONv2 позволяет передавать на платформу сообщения поверх протокола HTTP(S).

• Отличия от протокола SMPP:
• Одновременно можно использовать несколько каналов связи с вашей аудиторией: Push, приложения-мессенджеры и SMS (в данной инсталляции поддерживается только SMS). Если сообщение успешно доставлено по какому-либо каналу, дальнейшая отправка сообщения по другим каналам прекращается.
• Поддерживается массовая рассылка сообщений.

Платформа выступает в роли сервера. Клиенты, присылающие сообщения на доставку, выступают в роли HTTP-клиентов.

Стартовый URL для работы по протоколу JSONv2 в данной инсталляции: https://mn-smsrlbsvc.vimpelcom.ru:4433/msghub/api

1.1 Базовые сценарии использования протокола

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

Сценарий доставки одиночного сообщения:

Сценарий запуска массовой рассылки обычного типа (batch или broadcast):

Сценарий запуска массовой рассылки типа sync (batch или broadcast):

1.2 Отправка отдельного сообщения:

Параметры запроса делятся на два типа: обязательные и необязательные. Если хотя бы один обязательный параметр отсутствует, запрос не принимается платформой. Каждый канал передачи сообщений имеет свои уникальные параметры. Описание всех параметров запроса см. ниже

Запрос

{
    "phone_number": 79651111111,
    "extra_id": "AD-6640-7006",
    "callback_url": "https://send-dr-here.com",
    "start_time": "2020-12-12 10:10:10+03:00",
    "tag": "Campaign name",
    "channels": [
        "sms"
    ],
    "channel_options": {
        "sms": {
            "text": "Text for SMS",
            "alpha_name": "Test",
            "ttl": 300
        }
    }
}

HTTP статус 200 OK означает, что Ваш запрос был успешно обработан сервером.

Ответ

Если запрос правильный, вы получите следующий ответ:

{"message_id":"9f60ac8f-e721-5027-b838-e6fcb95fcd7a"}

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

{"error_code":36024,"error_text":"Phone number incorrect"}

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

1.3 Массовая рассылка сообщений

Протокол JSONv2 предоставляет возможность запуска массовой рассылки сообщений по одному запросу. Максимальное количество получателей в одном запросе- 50 000.

Запрос на batch-рассылкусодержит персонализированный текст сообщения по всем каналам связи для каждого пользователя.

Запрос на broadcast-рассылкусодержит общий текст и переменные, которые содержат персонализированные значения и могут быть использованы для всех параметров запроса

Платформа возвращает ответ на запрос (см. Ответ на запрос на рассылку массовых сообщений).

1.3.1 Отправка запроса на batch-рассылку SMS-сообщений

Пример запроса на batch-рассылку SMS-сообщений:

{
    "messages": [
        {
            "phone_number": 79651111111,
            "extra_id": "AD-6640-7006",
            "text": "Text for all channels, recipient #79651111111"
        },
        {
            "phone_number": 79652222222,
            "extra_id": "AD-6640-7007",
            "text": "Text for all channels, recipient #79652222222"
        }
    ],
    "start_time": "2020-12-12 10:10:10+03:00",
    "tag": "Campaign name",
    "channels": [
        "sms"
    ],
    "channel_options": {
        "sms": {
            "alpha_name": "Test",
            "ttl": 300
        }
    }
}

HTTP статус 200 OK означает, что Ваш запрос был успешно обработан сервером.

1.3.2 Отправка запроса на broadcast-рассылку SMS сообщений

Пример запроса на broadcast-рассылку SMS сообщений:

{
    "recipients": [
        {
            "phone_number": 79651111111,
            "extra_id": "AD-6640-7006",
            "name": "Michael",
            "greeting": "Mr. "
        },
        {
            "phone_number": 79652222222,
            "extra_id": "AD-6640-7007",
            "name": "Zoya",
            "greeting": "Ms. "
        }
    ],
    "start_time": "2020-12-12 10:10:10+03:00",
    "tag": "Campaign name",
    "channels": [
        "sms"
    ],
    "channel_options": {
        "sms": {
            "text": "Dear %greeting% %name%! Here is an SMS",
            "alpha_name": "Test",
            "ttl": 300
        }
    }
}

В тексте можно использовать переменные. Имя переменной может быть произвольными указывается между символами “%”. Переменные с их значениями для подстановки должны бытьуказаны в разделе “recipients”. Количество переменных в тексте неограниченно. Но существует ограничение на длину сообщения, и оно должно соответствовать следующим параметрам:

{
    "recipients": [
        {
            "phone_number": 79651111111,
            "extra_id": "AD-6640-7006",
            "name": "Michael",
            "greeting": "Mr. "
        },
        {
            "phone_number": 79652222222,
            "extra_id": "AD-6640-7007",
            "name": "Zoya",
            "greeting": "Ms. "
        }
    ],
    "start_time": "2020-12-12 10:10:10+03:00",
    "tag": "Campaign name",
    "channels": [
        "sms"
    ],
    "channel_options": {
        "sms": {
            "text": "Dear %greeting% %name%! Here is an SMS",
            "alpha_name": "Test",
            "ttl": 300
        }
    },
    "sms_cyrillic": {
        "min": 0,
        "max": 1340
    },
    "sms_latin": {
        "min": 0,
        "max": 3060
    }
}

HTTP статус 200 OK означает, что Ваш запрос был успешно обработан сервером.

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

Если запрос отправлен на URL[JSONv2_URL]/{client_id}/json2/broadcastили [JSONv2_URL] /{client_id}/json в ответ Вы получите идентификатор (ID) кампании в виде:

{"job_id": "66591729-cb47-5ef9-964b-949dc6aff84f"}

Используя этот job_id можно запрашивать отчёт о статусе кампании(рассылки).

Если запрос отправленна URL [JSONv2_URL]/{client_id}/json2/broadcast/sync или [JSONv2_URL] /{client_id} Вы получите детали, по каждому сообщению, с их “message_id”:

{
    "messages": [
        {
            "processed": true,
            "phone_number": "79651111111",
            "message_id": "9f60ac8f-e721-5027-b838-e6fcb95fcd7a",
            "extra_id": "AD-6640-7006",
            "accepted": true
        },
        {
            "processed": true,
            "phone_number": "79652222222",
            "message_id": "e5ea7286-6849-52d7-9e1b-8719b736283e",
            "extra_id": "AD-6640-7007",
            "accepted": true
        }
    ]
}

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

1.3.4 Запрос отчета о статусе кампании

Запрос статуса кампании позволяет получить информациюо состоянии вашей кампании (рассылки)

Пример статуса кампании:

{
  "messages": [
    {
      "time": 1477417299000,
      "phone_number": "79652222222",
      "message_id": "e5ea7286-6849-52d7-9e1b-8719b736283e",
      "extra_id": "AD-6640-7007",
      "processed": false,
      "accepted": true,
      "total_sms_parts": 1,
      "error_text": "SMS expired",
      "error_code": 35015
    },
    {
      "time": 1477417294667,
      "phone_number": "79651111111",
      "message_id": "9f60ac8f-e721-5027-b838-e6fcb95fcd7a",
      "extra_id": "AD-6640-7006",
      "processed": false,
      "accepted": true,
      "total_sms_parts": 1,
      "delivered_sms_parts": 1,
      "status_text": "SMS delivered",
      "status": 2,
      "substatus": 23,
      "msghub_status": 23011
    }
  ]
}

HTTP-статус 200 OK означает,что ваш запрос был успешно обработан сервером

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

1.4 Отчет о доставке сообщения

1.4.1 Получение отчета о доставке отдельного сообщения

Как только статус обновляется в системе, отчет отправляется на Ваш URL в формате JSON. Отчет содержит окончательный статус сообщения.

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

{
  "number": 79651111111,
  "time": 1477417294667,
  "status": 2, 
  "substatus": 23, 
  "msghub_status": 23011,
  "message_id": "9f60ac8f-e721-5027-b838-e6fcb95fcd7a",
  "extra_id": "AD-6640-7006",
  "sent_via": "sms"
}
 

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

1.4.2 Получение отчета о batch-рассылке

Как только статус обновляется в системе, отчеты о доставке сообщений сохраняются в пакет. Пакет отправляется на Ваш URL в формате JSON(HTTP,HTTPS).Количество отчетов в пакете и периодичность их отправки настраиваются на стороне платформы

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

[
  {
    "number": "79651111111",
    "time": 1477417294667,
    "status": 2,
    "substatus": 23,
    "msghub_status": 23011,
    "message_id": "9f60ac8f-e721-5027-b838-e6fcb95fcd7a",
    "extra_id": "AD-6640-7006",
    "sent_via": "sms"
  },
  {
    "number": "79652222222",
    "time": 1477417299000,
    "status": 3,
    "substatus": 35,
    "msghub_status": 35015,
    "message_id": "e5ea7286-6849-52d7-9e1b-8719b736283e",
    "extra_id": "AD-6640-7007",
    "sent_via": "sms"
  },
  {
    "number": "79653333333",
    "time": 1477417299050,
    "status": 2,
    "substatus": 23,
    "msghub_status": 23033,
    "message_id": "8a3ff6c5-a1fb-4849-a54b-3c488753cb8b",
    "extra_id": "AD-6640-7008",
    "sent_via": "sms"
  }
]

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

1.5 Запрос отчета о доставке отдельного сообщения

Отчет о доставке включает окончательный статус сообщения.

1.5.1 Запрос простого отчета о доставке

Простой отчет о доставке сообщения может быть запрошен по идентификатору сообщения (сформированный платформой параметр “message_id”)или по дополнительному идентификатору (заданный клиентским приложением параметр “extra_id”).

Чтобы получить отчет по идентификатору сообщения, используйте следующий URL:

[JSONv2_URL]/{client_id}/dr/{message_id}/simple

Чтобы получить отчет с использованием дополнительного идентификатора, используйте следующий URL:

[JSONv2_URL]/{client_id}/dr/external/{extra_id}/simple

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

{
  "phone_number": "79651111111",
  "last_partner": "sms",
  "message_id": "9f60ac8f-e721-5027-b838-e6fcb95fcd7a",
  "extra_id": "AD-6640-7006",
  "time": 1477417294667,
  "status": 2,
  "substatus": 23,
  "msghub_status": 23011,
  "total_sms_parts": 1,
  "delivered_sms_parts": 1
}

HTTP-статус 200 OK означает, что ваш запрос был успешно обработан сервером.

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

1.5.2 Запрос детального отчета о доставке

Детальный отчет о доставке сообщения может быть запрошен по идентификатору сообщения (сформированный платформой параметр “message_id”) или по дополнительному идентификатору (заданный клиентским приложением параметр “extra_id”).

Чтобы получить отчет по идентификатору сообщения, используйте следующий URL:

[JSONv2_URL]/{client_id}/dr/{message_id}/advanced

Чтобы получить отчет с использованием дополнительного идентификатора, используйте следующий URL:

[JSONv2_URL]/{client_id}/dr/external/{extra_id}/advanced

Пример детального отчета о доставке:

{
  "reports": [
    {
      "phone_number": "79651111111",
      "message_id": "9f60ac8f-e721-5027-b838-e6fcb95fcd7a",
      "extra_id": "AD-6640-7006",
      "time": 1477417294667,
      "last_partner": "sms",
      "status": 3,
      "substatus": 35,
      "msghub_status": 35015
    },
    {
      "phone_number": "79651111111",
      "message_id": "9f60ac8f-e721-5027-b838-e6fcb95fcd7a",
      "extra_id": "AD-6640-7006",
      "time": 1477417294667,
      "last_partner": "sms",
      "status": 2,
      "substatus": 23,
      "msghub_status": 23011,
      "total_sms_parts": 1,
      "delivered_sms_parts": 1
    }
  ],
  "started": true,
  "processing": false,
  "delivered_via": "sms",
  "channels": [
    {
      "channel": "sms",
      "ttl": 300
    }
  ]
}

Если сообщение не отправлено ни на один из каналов связи или еще не имеет статуса окончательной доставки, статус сообщения обозначается -1.

HTTP-статус 200 OK означает,что ваш запрос был успешно обработан сервером

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

1.6 Кодирование SMS

* длина сегментов сообщения указана исходя из использования символов 7-битной таблицы алфавита GSM по умолчанию. В данном случае следует отметить, что при использовании символов расширенной таблицы 7-битного алфавита GSM по умолчанию длина сегментов сообщения уменьшится,так как каждый символ расширенной таблицы передается в виде двух октетов и считается как два символа

Расширенная таблица 7-битных символов алфавита GSM по умолчанию:

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

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

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

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

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

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

Упрощенное значение “status”- статус:

Расширенное значение “substatus”- подстатусы: