h1. HTTP API message

{{>toc}}

Sends a message with a text *body* with a *source_number* to a recipient with a *destination_number*.

h2. 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|

h2. Returned data

The server returns a response in "JSON API":https://jsonapi.org/format/ 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*.
  
*data* can contain the following attributes:
|*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|

*errors* can contain the following attributes:
|*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.|

h2. Example

h3. 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*|<pre>
{
	"data" : {
		"attributes" : {
			"destination_number" : "12123388100",
			"segments" : 1,
			"status" : "ok"
		},
		"id" : "1561370632513",
		"meta" : {
			"request_id" : "1"
		},
		"type" : "message"
	}
}
</pre>|

h3. 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*|<pre>
{
	"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"
		}
	]
}
</pre>|

h3. Error

|*request*|POST "https://your.server.name/api/message?_login=LOGIN&_password=PASSWORD&destination_number=12123388100&body=test&require_dlr=1"|
|*response*|<pre>
{
	"errors" : [
		{
			"code" : "authentication",
			"detail" : "Please check your login and password",
			"title" : "Authentication error"
		}
	]
}
</pre>|

[[HTTP интерфейс message|Русский перевод]]