HTTP API message¶
- Table of contents
- HTTP API message
Sends a message with a text body with a source_number to a recipient with a destination_number.
Arguments¶
| argument | mandatory | description |
| _login | yes | coincides with a user / company login to a personal account |
| _password | yes | matches a user / company password to a personal account |
| destination_number | yes | a number of a recipient |
| body | no | a body of a message |
| source_name | no | a name of a sender |
| source_number | no | a number of a sender |
| require_dlr | no | require the Delivery Receipt |
| stealth_ping | no | aka Silent SMS (0 - no, 1 - yes). An invisible message is sent to a recipient. The recipient doesn't see the message on his device. The sender gets a Delivery receipt, basing on which he can know about availability of the recipient. |
| request_id | no | A value, assigned by a client. It will be returned to the client in a response |
Returned data¶
The server returns a response in JSON API format.
The response will contain one of:
- errors.
Array of errors, occured when processing the request. - data.
JSON object, which contains request results, in case if request from client contains 1 number.
Array of JSON objects, in case if request from client contains several numbers.
errors and data will not be present in 1 response simultaneously.
Each response contains either errors, or data.
| attribute | mandatory | description |
| id | yes | a response ID assigned by a server |
| type | yes | "message" |
| destination_number | yes | a number of a recipient |
| segments | yes | a number of segments, the original message has been split into (see Message billing) |
| status | yes | ок - a message has been successfully sent, the balance has been charged for the message, error - a message hasn't been sent, the balance hasn't been charged for the message |
| request_id | yes, if a client has passed the request_id inside a request | an argument that has been passed by the client |
| attribute | mandatory | description |
| code | yes | A short error code. It might be used by a client for the conditional error handling. It doesn't depend on a client's locale. |
| detail | yes | The error details. They might be used by a client to display a message inside the contents of an error dialog. They may be returned by the server in a locale of a client. |
| title | yes | An error title. It might be used by a client to display a message in a header of the error dialog. It may be returned by the server in a locale of a client. |
Example¶
Send message to 1 recipient¶
| request | POST "https://your.server.name/api/message?_login=LOGIN&_password=PASSWORD&destination_number=12123388100&body=test&require_dlr=1" |
| response |
{
"data" : {
"attributes" : {
"destination_number" : "12123388100",
"segments" : 1,
"status" : "ok"
},
"id" : "1561370632513",
"meta" : {
"request_id" : "1"
},
"type" : "message"
}
}
|
Send message to 2 recipients¶
| request | POST "https://your.server.name/api/message?_login=LOGIN&_password=PASSWORD&destination_number=12123388100&body=test&require_dlr=1&destination_number=12123388101&body=test1&require_dlr=1" |
| response |
{
"data" : [
{
"attributes" : {
"destination_number" : "12123388100",
"segments" : 1,
"status" : "ok"
},
"id" : "1561371433517",
"meta" : {
"request_id" : "1"
},
"type" : "message"
},
{
"attributes" : {
"destination_number" : "12123388101",
"segments" : 1,
"status" : "ok"
},
"id" : "1561371433518",
"meta" : {
"request_id" : "2"
},
"type" : "message"
}
]
}
|
Error¶
| request | POST "https://your.server.name/api/message?_login=LOGIN&_password=PASSWORD&destination_number=12123388100&body=test&require_dlr=1" |
| response |
{
"errors" : [
{
"code" : "authentication",
"detail" : "Please check your login and password",
"title" : "Authentication error"
}
]
}
|