База знаний
Revision 1.2.240312
This document contains information about the JSONv2 protocol, which allows messages to be transmitted to the platform over the HTTP(S) protocol.
This document contains information that is current at the time of its preparation. The manufacturer does not guarantee the absence of errors in this document. The manufacturer reserves the right to make changes to the document without prior notice
No part of this document may be reproduced or transmitted in any form or by any means without written notice to the Manufacturer
The manufacturer does not guarantee that the software specified in this document is error-free, will work in arbitrarily selected conditions and meet all the requirements that may be imposed on it.
The manufacturer does not guarantee the operability of illegally obtained software. Illegal use of software and documentation for it is prosecuted by law
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.
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:
| Parameter | Value |
|---|---|
| URLof the API | [JSONv2_URL]/{client_id}/json2/simple |
| Method | POST |
| HTTPAuthentication | Basic |
| Mandatory header | Content-Type: application/json |
Request parameters
General parameters.
| Title | Type | Required | Description |
|---|---|---|---|
| templateid | string | none | Template ID for sending message |
| priority | string | none | Priority: 2 - low, 4 - normal, 6 - high, 8 - highest. If not specified, 4 is used |
| timing | object | no | Timing settings |
| sms | object | no | Parameters for sending via the corresponding channel |
| call | object | no | Parameters for sending via the corresponding channel |
| messages | array | none | Parameters to send via the corresponding channel |
Parameters of the timing object.
| Name | Type | Requirement | Description |
|---|---|---|---|
| templateid | string | none | Template ID for sending the message |
| priority | string | none | Priority: 2 - low, 4 - normal, 6 - high, 8 - highest. If not specified, 4 is used |
| timing | object | no | Timing settings |
| sms | object | no | Parameters for sending via the corresponding channel |
| call | object | no | Parameters for sending via the corresponding channel |
| messages | array | no | Parameters for sending via the corresponding channel |
Parameters of the content object for sms
| Name | Type | Requirement | Description |
|---|---|---|---|
| originator | string | no | Sender address |
Parameters of the content object for call
| Name | Type | Requirement | Description |
|---|---|---|---|
| text | string | no | Message text for TTS synthesis, up to 2000 bytes (1000 characters). One of three parameters is used: text, file, ivrmenu. A request with more than one parameter is considered invalid |
| priority | string | none | Priority: 2 - low, 4 - normal, 6 - high, 8 - highest. If not specified, 4 is used |
| file | string | none | The name of the audio file. One of three parameters is used: text, file, ivrmenu. A request with more than one parameter is considered incorrect. |
| menu | string | no | IVR menu name. One of three parameters is used: text, file, ivrmenu. A request with more than one parameter is considered incorrect. |
| retryattempts | Number | no | Number of retry attempts. Only non-negative numbers are allowed. |
| retry- | Number | no | Interval after which a timeout call will be made, in milliseconds |
Parameters of the messages array element.
| Name | Type | Requirement | Description |
|---|---|---|---|
| recipient | string | no | Recipient address (usually MSISDN), specified strictly in the format 9989xxxxx, without spaces and without the + sign |
| message-id | string | no | A message identifier unique to the sending system must be unique for each message sent or forwarded. Example “abc0000001” abc = organization name. Field size no more than 40 characters |
| template-id | string | no | Template identifier for sending a message |
| priority | string | no | Priority: low - low, normal - usual, high - high, realtime - highest. If not specified, then normal is used. Configured in your personal account. |
| timing | object | no | Temporary settings |
| variables | array | no | An object of parameters and their values for substitution in the message (each element is presented as a PARAMETER: VALUE entry, for example, {“PARAM1”:”VALUE1”,”PARAM2”:”VALUE2”} ). |
| sms | object | none | Parameters to send via the corresponding channel |
| call | object | none | Parameters to send via the corresponding channel |
Parameters for timing objects and channel objects are similar to those for the general part of the request
Response parameters: A successful request has a status of 200/OK and a response body of Request is received
Sending message statuses
URL () of the partner: /status URL () of the partner is used to force receiving the statuses of sent messages from the SMSC "Play Mobile". The status is sent to the partner's URL () as soon as we receive it from the mobile operator.
Sending a single status.json
{
"messages": [
{
"message-id": "",
"channel": "",
"status": "",
"status-date": "",
"description": ""
}
]
}
Bulk sending of status.json
{
"messages": [
{
"message-id": "",
"channel": "",
"status": "",
"status-date": "",
"description": ""
},
{
"message-id": "",
"channel": "",
"status": "",
"status-date": "",
"description": ""
}
]
}
The status request returns the following message statuses:
Delivered - delivered; Transmitted - sent to the operator, your SMS was received and sent to the operator, the operator has not yet processed it, the reason may be that the subscriber is out of the network area or switched off. After 24 hours, the status will change to Delivered.; NotDelivered - not delivered, usually the reason may be that the subscriber is blocked by the operator (insufficient funds or debt); Rejected - one of the main reasons is that the number is on the blacklist; Failed - an error occurred while sending a request (for example, when the sender's address is incorrect); Expired - the SMS has expired (when the subscriber has not contacted for 24 hours. For Beeline, it is within an hour).
Examples
Sending a single message
{
"messages": [
{
"recipient": "998900000000",
"message-id": "abc000000001",
"sms": {
"originator": "3700",
"content": {
"text": "Test message"
}
}
}
]
}
Sending a single messages
{
"messages": [
{
"recipient": "9989xxxxxxxxxx",
"message-id": "abc00000001",
"sms": {
"originator": "3700",
"content": {
"text": "Test text"
}
}
},
{
"recipient": "9989xxxxxxxx",
"message-id": "abc00000002",
"sms": {
"originator": "3700",
"content": {
"text": "Test text 1"
}
}
},
{
"recipient": "998970000000",
"message-id": "abc00000003",
"sms": {
"originator": 3700,
"content": {
"text": "Test text2"
}
}
}
]
}