Отправка исходящих сообщений
Для передачи пакета исходящих сообщений клиент отправляет запрос consumeOutMessageRequest. В ответ провайдер отправляет клиенту пакет consumeOutMessageResponse.
Пакет consumeOutMessageRequest
Раздел payload пакета consumeOutMessageRequest содержит одну или несколько подсекций outMessage, каждая из которых определяет параметры одного исходящего сообщения.
Также раздел payload содержит подраздел outMessageCommon, в котором указываются общие параметры всех сообщений пакета.
Если параметр сообщения не указан в 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/subject | String | Обязательный | Подпись сообщения, выданная клиенту на этапе регис трации канала на платформе. |
outMessageCommon/priority | String | Обязательный | Приоритет сообщения:
- low — низкий;
- normal — нормальный;
- high — высокий;
- realtime — высочайший. |
outMessageCommon/startTime | Datetime | Обязательный | Время отложенной отправки исходящих сообщений. |
outMessageCommon/validityPeriodSeconds | Integer | Обязательный | Время, в течение которого платформа пытается доставить сообщение. Задается в секундах. |
outMessageCommon/contentType | String | Обязательный | Тип содержимого сообщения. Допустимое значение: text — текстовое сообщение. |
outMessageCommon/content | String | Обязательный | Информационное содержание сообщения. Если параметр contentType в outMessage имеет значение text, то допустима любая непустая строка произвольной длины. Если строка длиннее, чем допустимый размер одного SMS-сообщения, то она автоматически разобьется на нужное количество сообщений. |
outMessageCommon/comment | String | Необязательный | Текстовый комментарий к сообщениям. |
.../outMessage/clientId | Integer | Обязательный | Идентификатор исходящего сообщения на стороне клиента. Глобально уникален на протяжении всего времени взаимодействия между клиентом и провайдером. Значение генерируется для каждого исходящего сообщения и служит для дальнейшей привязки providerId к исходящему сообщению, а также запроса статусов доставки последнего. |
.../outMessage/subject | String | Обязательный | Подпись сообщения, выданная клиенту на этапе регистрации канала на платформе. |
.../outMessage/address | Address | Обязательный | Номер мобильного телефона получателя в формате E.164. |
.../outMessage/priority | String | Обязательный | Приоритет сообщения:
- low — низкий;
- normal — нормальный;
- high — высокий;
- realtime — высочайший. |
.../outMessage/startTime | Datetime | Обязательный | Время отложенной отправки исходящих сообщений. |
.../outMessage/validityPeriodSeconds | Integer | Обязательный | Время, в течение которого платформа пытается доставить сообщение. Задается в секундах. |
.../outMessage/contentType | String | Обязательный | Тип содержимого сообщения.
Допустимое значение: text — текстовое сообщение. |
.../outMessage/content | String | Обязательный | Информационное содержание сообщения. Если параметр contentType имеет значение text, то допустима любая непустая строка произвольной длины. Если строка длиннее, чем допустимый размер одного SMS-сообщения, то она автоматически разобьется на нужное количество сообщений. |
.../outMessage/comment | String | Необязательный | Текстовый комментарий к сообщениям. |
Пример пакета
<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.
| Параметр | Тип | Характер | Описание |
|---|---|---|---|
code | String | Обязательный | Код результата обработки пакета consumeOutMessageRequest.
Ответ на ошибочный пакет |
.../outMessage/code | String | Обязательный | Код ответа платформы для исходящего сообщения. Коды ответов платформы при отправке сообщений |
.../outMessage/@clientId | Integer | Обязательный | Идентификатор исходящего сообщения на стороне клиента. Глобально уникален на протяжении всего времени взаимодействия между клиентом и провайдером. Значение генерируется для каждого исходящего сообщения и служит для дальнейшей привязки providerId к исходящему сообщению, а также запроса статусов доставки последнего. |
.../outMessage/@providerId | String | Обязательный | Идентификатор сообщения на стороне платформы. Значение уникально на протяжении всего времени взаимодействия между провайдером и клиентом. Параметр возвращается, если сообщение с указанным 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 | Контент сообщения не указан. |