1 Description of the JSONv2 protocol for sending messages to the platform

The JSONv2 protocol allows you to send messages to the platform over the HTTP(S) protocol.

• Differences from the SMPP protocol:
• You can use several communication channels with your audience at the same time: Push, messenger applications and SMS (only SMS is supported in this installation). If the message is successfully delivered via any channel, further sending of the message via other channels is stopped.
• Bulk messaging is supported.

The platform acts as a server. Clients sending messages for delivery act as HTTP clients.

Start URL for working with the JSONv2 protocol in this installation: https://mn-smsrlbsvc.vimpelcom.ru:4433/msghub/api

1.1 Basic scenarios for using the protocol

The protocol provides the ability to transmit a single message to the platform for delivery to the subscriber, as well as the ability to launch mass mailings of two types of messages.

Single message delivery scenario:

Script for launching a regular type of mass mailing (batch or broadcast):

Script for launching a sync type of mass mailing (batch or broadcast):

1.2 Sending a separate messages:

Request parameters are divided into two types: mandatory and optional. If at least one mandatory parameter is missing, the request is not accepted by the platform. Each message transmission channel has its own unique parameters. Description of all request parameters see below

Request

{
"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 status 200 OK means that your request was successfully processed by the server.

Response

If the request is correct, you will receive the following response:

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

If the request contains an error or does not match the connection settings, you will receive the following response:

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

For a description of the response parameters, see below.

1.3 Bulk messaging

The JSONv2 protocol provides the ability to launch a mass messaging service with a single request. The maximum number of recipients in a single request is 50,000.

A batch messaging requestcontains a perspersonalized message text across all communication channels for each user.

Broadcast requestcontains general text and variables that contain personalized values ​​and can be used for all request parameters

The platform returns a response to the request (see Response to a request to send bulk messages).

1.3.1 Sending a request for batch SMS messaging

Example of a request for batch SMS messaging:

{
"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 status 200 OK means that your request was successfully processed by the server.

1.3.2 Sending a request for broadcast SMS messages

Example of a request for broadcast SMS messages:

{
"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
}
}
}

You can use variables in the text. The variable name can be arbitrary and is indicated between the “%” symbols. Variables with their values ​​for substitution must be specified in the “recipients” section. The number of variables in the text is unlimited. But there is a limit on the length of the message, and it must meet the following parameters:

{
"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 status 200 OK means that your request was successfully processed by the server.

1.3.3 Response to a request for mass messaging

If the request is sent to URL[JSONv2_URL]/{client_id}/json2/broadcastor [JSONv2_URL] /{client_id}/json in response you will receive the campaign identifier (ID) in the following format:

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

Using this job_id you can request a report on the status of the campaign (mailing list).

If the request is sent to the URL [JSONv2_URL]/{client_id}/json2/broadcast/sync or [JSONv2_URL] /{client_id} you will receive details for each message, with their “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
}
]
}

See below for a description of the response parameters.

1.3.4 Request for a campaign status report

A campaign status request allows you to get information about the status of your campaign (mailing list)

Campaign status example:

{
 "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 status 200 OK means that your request was successfully processed by the server

See below for a description of the report parameters

1.4 Message delivery report

1.4.1 Receiving a delivery report for a single message

As soon as the status is updated in the system, the report is sent to your URL in the format JSON. The report contains the final status of the message.

Example report:

{
"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"
}

See below for description of report parameters

1.4.2 Receiving a batch mailing report

As soon as the status is updated in the system, the message delivery reports are saved in a batch. The package is sent to your URL in JSON format (HTTP, HTTPS). The number of reports in the package and the frequency of their sending are configured on the platform side

Example report:

[
{
"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"
}
]

See below for a description of the report parameters

1.5 Request a delivery report for a single message

The delivery report includes the final status of the message.

1.5.1 Requesting a simple delivery report

A simple message delivery report can be requested by message ID (the platform-generated “message_id” parameter) or by an additional ID (the client-defined “extra_id” parameter).

To get a report by message ID, use the following URL:

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

To get a report using an additional ID, use the followingfollowing URL:

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

Simple delivery report example:

{
"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 status 200 OK means that your request was successfully processed by the server.

See below for a description of the report parameters

1.5.2 Requesting a detailed delivery report

A detailed message delivery report can be requested by message ID (the “message_id” parameter generated by the platform) or by an additional identifier (the “extra_id” parameter specified by the client application).

To get a report by message ID, use the following URL:

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

To get a report using an additional identifier, use the following URL:

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

Example of a detailed delivery report:

{
"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
}
]
}

If the message has not been sent to any of the communication channels or does not yet have the final delivery status, the message status is -1.

HTTP status 200 OK means that your request was successfully processed by the server

See below for a description of the report parameters

1.6 SMS encoding

* message segment lengths are specified based on the use of symbols from the default 7-bit GSM alphabet table. In this case, it should be noted that when using the symbols of the extended table of the default GSM 7-bit alphabet, the length of the message segments will decrease, since each symbol of the extended table is transmitted as two octets and is counted as two symbols

Extended table of the default GSM 7-bit alphabet symbols:

1.7 Description of request and response parameters

Descriptionrequest parameters:

Description of response parameters:

Description of message delivery report parameters:

1.8 Message statuses

This section provides a basic list of statuses that can be changed by the system owner.

Simplified meaning of “status” - status:

Extended meaning of “substatus” - substatuses: