h1. HTTP интерфейс message

{{>toc}}

Отправляет сообщение с текстом *body* с номером отправителя *source_number* получателю с номером *destination_number*.

h2. Аргументы

|*аргумент*|*обязательный*|*описание*|
|_login|да|совпадает с логином пользователя/компании к личному кабинету|
|_password|да|совпадает с паролем пользователя/компании к личному кабинету|
|destination_number|да|номер абонента-получателя|
|body|нет|тело сообщения в кодировке UTF-8|
|source_name|нет|имя абонента-отправителя|
|source_number|нет|номер абонента-отправителя|
|require_dlr|нет|требовать отчет о доставке, (0 - не требовать, 1 - требовать)|
|stealth_ping|нет|Невидимый пинг абонента-получается (0 - нет, 1 - да).
Абоненту-получателю отправляется сообщение, которое не отображается на его устройстве.
Абоненту-отправителю приходит отчет о доставке, по которому можно судить о доступности абонента-получателя.|
|request_id|нет|назначаемый клиентом ID запроса, будет возвращен клиенту в ответе|

h2. Возвращаемые данные

Сервер возвращает ответ в формате "JSON API":https://jsonapi.org/format/.
В ответе может присутствовать одно из:

* *errors*.
  Массив ошибок, возникших при обработке запроса.
* *data*.
  JSON объект, содержащий результаты запроса, если запрос от клиента содержит 1 номер.
  Массив JSON объектов, если запрос от клиента содержит несколько номеров.

*errors* и *data* не присутствуют в 1 ответе одновременно.
Каждый ответ содержит либо *errors*, либо *data*.
  
*data* может содержать следующие атрибуты:
|*атрибут*|*обязательный*|*описание*|
|id|да|назначенный сервером ID сообщения|
|type|да|"message"|
|destination_number|да|номер получателя|
|segments|да|кол-во сегментов, на которое было разбито исходное сообщение (см. [[Биллинг сообщений]])|
|status|да|ок - успешно отправили сообщение, с баланса списались деньги
error - не получилось отправить сообщение, с баланса не списались деньги|
|request_id|да, если клиент передал request_id в запросе|переданный клиентом аргумент|

*errors* может содержать следующие атрибуты:
|*атрибут*|*обязательный*|*описание*|
|code|да|Короткий код ошибки.
Может использоваться клиентом для условной обработки ошибки.
Не зависит от локали клиента.|
|detail|да|Детали ошибки.
Может использоваться клиентом для отображения в содержимом диалогового окна ошибки.
Может быть выдано сервером в локали клиента.|
|title|да|Заголовок ошибки.
Может использоваться клиентом для отображения в заголовке диалогового окна ошибки.
Может быть выдано сервером в локали клиента.|

h2. Примеры

h3. Сообщение на 1 номер

|*запрос*|POST "https://имя.вашего.сервера/api/message?destination_number=79183035536&body=test&request_id=1&_login=LOGIN&_password=PASSWORD"|
|*ответ*|<pre>
{
	"data" : {
		"attributes" : {
			"destination_number" : "79183035536",
			"segments" : 1,
			"status" : "ok"
		},
		"id" : "1561370632513",
		"meta" : {
			"request_id" : "1"
		},
		"type" : "message"
	}
}
</pre>|

h3. Запрос 2 номеров

|*запрос*|POST "https://имя.вашего.сервера/api/message?destination_number=79183035536&body=test&request_id=1&destination_number=79183035537&body=test2&request_id=2&_login=LOGIN&_password=PASSWORD"|
|*ответ*|<pre>
{
	"data" : [
		{
			"attributes" : {
				"destination_number" : "79183035536",
				"segments" : 1,
				"status" : "ok"
			},
			"id" : "1561371433517",
			"meta" : {
				"request_id" : "1"
			},
			"type" : "message"
		},
		{
			"attributes" : {
				"destination_number" : "79183035537",
				"segments" : 1,
				"status" : "ok"
			},
			"id" : "1561371433518",
			"meta" : {
				"request_id" : "2"
			},
			"type" : "message"
		}
	]
}
</pre>|

h3. Ошибка

|*запрос*|POST "https://имя.вашего.сервера/api/message?destination_number=79183035536&body=test&request_id=1&_login=LOGIN&_password=PASSWORD"|
|*ответ*|<pre>
{
	"errors" : [
		{
			"code" : "authentication",
			"detail" : "Please check your login and password",
			"title" : "Authentication error"
		}
	]
}
</pre>|

[[HTTP API message|English translation]]