Перейти к основному содержимому

Отправка исходящих сообщений

Для передачи пакета исходящих сообщений клиент отправляет запрос consumeOutMessageRequest. В ответ провайдер отправляет клиенту пакет consumeOutMessageResponse.

Пакет consumeOutMessageRequest​

Раздел payload пакета consumeOutMessageRequest содержит одну или несколько подсекций outMessage, каждая из которых определяет параметры одного исходящего сообщения.

Также раздел payload содержит подраздел outMessageCommon, в котором указываются общие параметры всех сообщений пакета.

warning

Если параметр сообщения не указан в outMessage, то его значение берется из outMessageCommon. Если параметр не указан ни в outMessage, ни в outMessageCommon, то берется значение по умолчанию из конфигурации платформы провайдера. Исключением является только параметр content, который обязательно должен быть указан либо в outMessage, либо в outMessageCommon.

Структура пакета​

<consumeOutMessageRequest>
<header><!--параметры аутентификации клиента--></header>
<payload>
<outMessageCommon><!--общие параметры сообщений рассылки--></outMessageCommon>
<outMessageList>
<outMessage><!--адрес получателя и индивидуальные параметры сообщения--></outMessage>
<!--повторение блока outMessage-->
</outMessageList>
</payload>
</consumeOutMessageRequest>
Полная XML-схема пакета consumeOutMessageRequest
<xsd:schema>
<xsd:element name="consumeOutMessageRequest">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="header">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="auth">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="login" type="xsd:string"/>
<xsd:element name="password" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="payload">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="outMessageCommon" minOccurs="0">
<xsd:complexType>
<xsd:all>
<xsd:element name="subject" type="xsd:string" minOccurs="0"/>
<xsd:element name="priority" type="priorityType" minOccurs="0"/>
<xsd:element name="startTime" type="dateTimeType" minOccurs="0"/>
<xsd:element name="validityPeriodMinutes" type="xsd:positiveInteger" minOccurs="0"/>
<xsd:element name="contentType" type="contentTypeType" minOccurs="0"/>
<xsd:element name="content" type="xsd:string" minOccurs="0"/>
<xsd:element name="comment" type="xsd:string" minOccurs="0"/>
</xsd:all>
</xsd:complexType>
</xsd:element>
<xsd:element name="outMessageList" minOccurs="0">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="outMessage" minOccurs="0" maxOccurs="unbounded">
<xsd:complexType>
<xsd:all>
<xsd:element name="subject" type="xsd:string" minOccurs="0"/>
<xsd:element name="address">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:pattern value="\d{9,15}"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
<xsd:element name="priority" type="priorityType" minOccurs="0"/>
<xsd:element name="startTime" type="dateTimeType" minOccurs="0"/>
<xsd:element name="validityPeriodMinutes" type="xsd:positiveInteger" minOccurs="0"/>
<xsd:element name="contentType" type="contentTypeType" minOccurs="0"/>
<xsd:element name="content" type="xsd:string" minOccurs="0"/>
<xsd:element name="comment" type="xsd:string" minOccurs="0"/>
</xsd:all>
<xsd:attribute name="clientId" type="xsd:positiveInteger" use="required"/>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
<xsd:unique name="clientId">
<xsd:selector xpath="outMessage"/>
<xsd:field xpath="@clientId"/>
</xsd:unique>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:simpleType name="priorityType">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="low"/>
<xsd:enumeration value="normal"/>
<xsd:enumeration value="high"/>
<xsd:enumeration value="realtime"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="contentTypeType">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="text"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="dateTimeType">
<xsd:restriction base="xsd:string">
<xsd:pattern value="\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:schema>

Параметры пакета​

к сведению

Все параметры в таблице входят в объект payload.

ПараметрТипХарактерОписание
outMessageCommon/subjectStringОбязательныйПодпись сообщения, выданная клиенту на этапе регистрации канала на платформе.
outMessageCommon/priorityStringОбязательныйПриоритет сообщения:
- low — низкий;
- normal — нормальный;
- high — высокий;
- realtime — высочайший.
outMessageCommon/startTimeDatetimeОбязательныйВремя отложенной отправки исходящих сообщений.
outMessageCommon/validityPeriodSecondsIntegerОбязательныйВремя, в течение которого платформа пытается доставить сообщение. Задается в секундах.
outMessageCommon/contentTypeStringОбязательныйТип содержимого сообщения. Допустимое значение: text — текстовое сообщение.
outMessageCommon/contentStringОбязательныйИнформационное содержание сообщения. Если параметр contentType в outMessage имеет значение text, то допустима любая непустая строка произвольной длины. Если строка длиннее, чем допустимый размер одного SMS-сообщения, то она автоматически разобьется на нужное количество сообщений.
outMessageCommon/commentStringНеобязательныйТекстовый комментарий к сообщениям.
.../outMessage/clientIdIntegerОбязательныйИдентификатор исходящего сообщения на стороне клиента. Глобально уникален на протяжении всего времени взаимодействия между клиентом и провайдером. Значение генерируется для каждого исходящего сообщения и служит для дальнейшей привязки providerId к исходящему сообщению, а также запроса статусов доставки последнего.
.../outMessage/subjectStringОбязательныйПодпись сообщения, выданная клиенту на этапе регистрации канала на платформе.
.../outMessage/addressAddressОбязательныйНомер мобильного телефона получателя в формате E.164.
.../outMessage/priorityStringОбязательныйПриоритет сообщения:
- low — низкий;
- normal — нормальный;
- high — высокий;
- realtime — высочайший.
.../outMessage/startTimeDatetimeОбязательныйВремя отложенной отправки исходящих сообщений.
.../outMessage/validityPeriodSecondsIntegerОбязательныйВремя, в течение которого платформа пытается доставить сообщение. Задается в секундах.
.../outMessage/contentTypeStringОбязательныйТип содержимого сообщения.
Допустимое значение: text — текстовое сообщение.
.../outMessage/contentStringОбязательныйИнформационное содержание сообщения. Если параметр contentType имеет значение text, то допустима любая непустая строка произвольной длины. Если строка длиннее, чем допустимый размер одного SMS-сообщения, то она автоматически разобьется на нужное количество сообщений.
.../outMessage/commentStringНеобязательныйТекстовый комментарий к сообщениям.

Пример пакета​

<consumeOutMessageRequest>
<header>
<auth>
<login>test</login>
<password>test</password>
</auth>
</header>
<payload>
<outMessageCommon>
<subject>mfms</subject>
<priority>high</priority>
<validityPeriodSeconds>600</validityPeriodSeconds>
<contentType>text</contentType>
<content>С Новым Годом!</content>
<comment>массовая рассылка</comment>
</outMessageCommon>
<outMessageList>
<outMessage clientId="9935977">
<address>79036666666</address>
</outMessage>
<outMessage clientId="9935978">
<address>79037777777</address>
</outMessage>
</outMessageList>
</payload>
</consumeOutMessageRequest>

Пакет consumeOutMessageResponse​

Раздел payload пакета consumeOutMessageResponse содержит код ответа платформы:

  • если код ответа свидетельствует об отсутствии ошибки, то раздел payload включает подраздел outMessageList с секциями outMessage из пакета consumeOutMessageRequest;

  • если код ответа свидетельствует об ошибке, значит ни одно исходящее сообщение пакета consumeOutMessageRequest не принято на отправку.

В каждой секции outMessage указан код ответа для соответствующего исходящего сообщения:

  • если код ответа свидетельствует об отсутствии ошибки, то секция outMessage содержит идентификаторы исходящего сообщения clientId и providerId;

  • если код ответа свидетельствует об ошибке, значит исходящее сообщение не принято на отправку.

Структура пакета​

<consumeOutMessageResponse>
<header/>
<payload>
<code>string</code>
<outMessageList>
<outMessage clientId="integer" providerId="string">
<code>string</code>
</outMessage>
</outMessageList>
</payload>
</consumeOutMessageResponse>
Полная XML-схема пакета consumeOutMessageResponse
<xsd:schema>
<xsd:element name="consumeOutMessageResponse">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="header" type="xsd:string"/>
<xsd:element name="payload">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="code">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="ok"/>
<xsd:enumeration value="error-syntax"/>
<xsd:enumeration value="error-auth"/>
<xsd:enumeration value="error-permission"/>
<xsd:enumeration value="error-system"/>
<xsd:enumeration value="error-account-locked"/>
<xsd:enumeration value="error-out-message-client-id-format"/>
<xsd:enumeration value="error-out-message-client-id-duplicate"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
<xsd:element name="outMessageList" minOccurs="0">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="outMessage" minOccurs="0" maxOccurs="unbounded">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="code">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="ok"/>
<xsd:enumeration value="error-system"/>
<xsd:enumeration value="error-out-message-client-id-unknown"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
</xsd:sequence>
<xsd:attribute name="clientId" type="xsd:positiveInteger" use="required"/>
<xsd:attribute name="providerId" type="xsd:positiveInteger" use="optional"/>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
<xsd:unique name="clientId">
<xsd:selector xpath="outMessage"/>
<xsd:field xpath="@clientId"/>
</xsd:unique>
<xsd:unique name="providerId">
<xsd:selector xpath="outMessage"/>
<xsd:field xpath="@providerId"/>
</xsd:unique>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>

Параметры пакета​

к сведению

Все параметры в таблице входят в объект payload.

ПараметрТипХарактерОписание
codeStringОбязательныйКод результата обработки пакета consumeOutMessageRequest. File IconОтвет на ошибочный пакет
.../outMessage/codeStringОбязательныйКод ответа платформы для исходящего сообщения. File IconКоды ответов платформы при отправке сообщений
.../outMessage/@clientIdIntegerОбязательныйИдентификатор исходящего сообщения на стороне клиента. Глобально уникален на протяжении всего времени взаимодействия между клиентом и провайдером. Значение генерируется для каждого исходящего сообщения и служит для дальнейшей привязки providerId к исходящему сообщению, а также запроса статусов доставки последнего.
.../outMessage/@providerIdStringОбязательныйИдентификатор сообщения на стороне платформы. Значение уникально на протяжении всего времени взаимодействия между провайдером и клиентом. Параметр возвращается, если сообщение с указанным clietnId успешно принято на отправку.

Пример пакета​

<consumeOutMessageResponse>
<header/>
<payload>
<code>ok</code>
<outMessageList>
<outMessage clientId="1" providerId="101">
<code>ok</code>
</outMessage>
<outMessage clientId="2" providerId="102">
<code>error-address-format</code>
</outMessage>
</outMessageList>
</payload>
</consumeOutMessageResponse>

Коды ответов платформы при отправке сообщений​

Код ответа для каждого сообщения указывается в параметре code в объекте outMessage.

КодОписание
okИсходящее сообщение успешно принято на обработку.
error-systemСистемная ошибка.
error-out-message-client-id-not-uniqueПараметр clientId не уникален в рамках взаимодействия между клиентом и платформой.
error-subject-formatНекорректный формат подписи сообщения.
error-subject-unknownУказанная подпись не разрешена клиенту в конфигурации платформы провайдера.
error-address-formatНекорректный формат номера телефона получателя.
error-address-unknownВ конфигурации платформы запрещена отправка сообщений на номерную емкость, к которой относится номер получателя.
error-address-not-specifiedНомер телефона получателя не указан.
error-priority-formatНеправильный формат значения приоритета.
error-start-time-formatНекорректный формат времени отправки.
error-comment-formatНекорректный формат комментария.
error-content-type-formatНекорректный формат содержимого сообщения.
error-content-not-specifiedКонтент сообщения не указан.