Отправка сообщ ений
Метод consumeOutMessage отправляет сообщения в edna Prisma для дальнейшей доставки адресату.
Параметры запроса
Помимо стандартных параметров login и password в запросе передается структура consumeOutMessageArg с параметрами отправляемого сообщения. При этом один запрос можно использовать для отправки нескольких сообщений, указав соответствующее число таких структур.
| Параметр | Тип данных | Характер | Описание |
|---|---|---|---|
messageId | String | Обязательный | Идентификатор сообщения |
outMessageTypeId | String | Обязательный | Тип сообщения, зарегистрированный в edna Prisma |
subject | String | Необязательный | Телефонный номер или имя отправителя сообщения. При получении сообщения подпись отобразится в поле «От кого» |
address | String | Необязательный | Адрес получателя сообщения. Телефонный номер абонента (клиента) в международном формате ITU-T E.164 без знака «+» перед цифрами |
clientID | String | Необязательный | Идентификатор клиента в информационной системе отправителя |
priority | String | Необязательный | Приоритет исходящего сообщения: - low — низкий; - normal — обычный; - high — высокий; - realtime — отправить в режиме реального времени. Если указано неверное значение, то приоритет определяется типом сообщения |
startTime | DateTime | Необязательный | Момент времени, после которого можно начинать отправку сообщения |
stopTime | DateTime | Необязательный | Момент времени, до которого отправка сообщения должна быть выполнена |
dlvInterval | Необязательный | Промежуток времени в течение дня, когда получателю можно доставлять сообщение | |
dlvStart | String | Необязательный | Время дня, начиная с которого можно доставлять сообщение получателю. Указывается в двузначном формате (только часы), например, dlvStart = 13 означает, что период доставки начинается в 13 часов |
dlvStop | String | Необязательный | Время дня, до которого можно доставлять сообщение получателю. Указывается в двузначном формате (только часы) |
timezone | String | Необязательный | Код временной зоны получателя, в соответствии с которым будет установлен интервал доставки сообщения. Используется для переопределения временной зоны абонента, определенной по номеру телефона |
comment | String | Необязательный | Комментарий к сообщению |
options | Необязательный | Список дополнительных атрибутов push-сообщений | |
option | Необязательный | Дополнительный атрибут сообщения. Содержит одну пару вида «ключ-значение». Можно добавлять несколько атрибутов, для каждого из которых следует определить свой параметр option. Позволяет передавать разные значения в зависимости от того, на какое устройство (iOS или Android) будет отправлено сообщение | |
key | String | Ключ | |
value | String | Значение | |
outMessageTemplate | Шаблон сообщения. Содержит параметры для формирования текста сообщения | ||
text | String | Обязательный | Текст сообщения или шаблон с параметрами подстановки |
startTime и stopTime
Параметры startTime и stopTime используются для указания интервала отправки сообщения. startTime — момент времени, после которого можно начинать отправку, stopTime — момент времени, до которого отправка сообщения должна быть завершена.
Если сообщение по какой-либо причине не было отправлено за указанный интервал (большая очередь или технические проблемы), то оно не будет отправлено никогда.
Допустимо указание только одного параметра. Параметр startTime может использоваться для отложенной отправки сообщений в будущем.
Если startTime не указан, сообщение отправляется по факту получения от системы с учетом текущей очереди.
Если stopTime не указан, то его значение определяется равным «startTime + 10 суток». Кроме того, учитывается время, когда получателю можно доставлять сообщение — параметр dlvInterval.
Например, если в сообщении, поступившем от системы пользователя, указано
startTime =2022-02-10T20:00:00,dlvStart = 10,dlvStop = 18, то оно будет отправлено 2022-02-11 в 10:00, т.к.это ближайшее время послеstartTime, попадающее в интервал доставки с 10 до 18 часов.
Значения dlvStart и dlvStop учитываются во временной зоне получателя. Временная зона определяется либо по номеру телефона, либо с помощью параметра timezone.
Например, если сообщение с указанными выше временными параметрами предназначено абоненту 7924ххххххх,то SMS-шлюз по номеру определит временную зону абонента — Дальний Восток (GMT+11:00), и дата и время отправки составят 2022-02-11, 3:00 по московскому времени. Но если известно, что абонент в данный момент находится в Москве, ИС может переопределить временную зону, указав в параметрах сообщения
timezone = GMT+4:00. Тогда сообщение будет отправлено 2022-02-11в 10:00 по Москве.
Дополнительные атрибуты сообщений
С помощью параметров options можно передавать дополнительные атрибуты сообщений в виде пары «ключ-значение». При этом, указывая значение ключа, можно использовать префиксы gcm/ или aps/. Тогда данные будут отправлены только в облако Google для доставки на Android-устройства или только в облако Apple для доставки на устройства iOS. Если префикс не указан, то данные отправляются в оба облака.
<options>
<option>
<!--Параметр будет отправлен только на Android-->
<key>gcm/data</key>
<value>{ "type": "pushActivity", "activity_name": "URL", "id": objectID
}</value>
</option>
<option>
<!--Параметр будет отправлен только на iOS-->
<key>aps/data</key>
<value>{ "type": "pushActivity", "activity_name": "URL", "id": objectID
}</value>
</option>
<option>
<!--Параметр будет отправлен в оба облака-->
<key>data</key>
<value>{ "type": "pushActivity", "activity_name": "URL", "id": objectID
}</value>
</option>
</options>
Логика обработки таких дополнительных параметров определяется приложением на мобильном устройстве. Таким образом, разработчик приложения сам определяет, какие дополнительные атрибуты он хочет получать вместе с push-сообщением, и как их обрабатывать. Эти дополнительные атрибуты указываются в формате JSON внутри значения value.
В iOS нельзя использовать в качестве имени ключа key значение alert, так как оно
используется для передачи текста в push-сообщениях.
Пример на Android
messageId=1563525921879359509-0123-37556707
activity_name=URL
gateMessageId=410220370112094560
serverMessageId=1563525921879359509
id=http://mail.ru
type=pushActivity
alert=желает Вам хорошего дня!
newMessagesAvailable=2
sessionKey=066c1402-7eb1-417b-b1fb-309d99a480cf
chlSentAt=2022-06-05T12:12:46.045
Пример на iOS
[AnyHashable("messageId"): 1558425691053883396, AnyHashable("serverMessageId"):
1558425691053883396, AnyHashable("data"): { "type": "pushActivity", "activity_name":
"URL", "id": objectID }, AnyHashable("chlSentAt"): 2018-05-22T18:21:15.573,
AnyHashable("gateMessageId"): 409901605690274128, AnyHashable("aps"):
{ alert = "\U0412\U0430\U0448 \U043f\U0430\U0440\U043e\U043b\U044c"; badge = 2;
"content-available" = 1; data = "
{ \"type\": \"pushActivity\", \"activity_name\": \"URL\", \"id\": objectID }
";
"mutable-content" = 1;
}, AnyHashable("sessionKey"): 3a4de1de-a792-46d8-8322-0d84318b3919,
AnyHashable("newMessagesAvailable"): 2]
[DEMO] AppDelegate[foreground]: willPresent notification (>= iOS 10)
+ onlyPush = false
+ messageId = 1558425691053883396
+ serverMessageId = 1558425691053883396
+ operationId = nil
+ chlSentAt = 2022-05-22T18:21:15.573
[AnyHashable("messageId"): 1558425691053883396, AnyHashable("serverMessageId"):
1558425691053883396, AnyHashable("data"): { "type": "pushActivity", "activity_name":
"URL", "id": objectID }, AnyHashable("chlSentAt"): 2018-05-22T18:21:15.573,
AnyHashable("gateMessageId"): 409901605690274128, AnyHashable("aps"):
{ alert = "\U0412\U0430\U0448 \U043f\U0430\U0440\U043e\U043b\U044c"; badge = 2;
"content-available" = 1; data = "
{ \"type\": \"pushActivity\", \"activity_name\": \"URL\", \"id\": objectID }
";
"mutable-content" = 1;
}, AnyHashable("sessionKey"): 3a4de1de-a792-46d8-8322-0d84318b3919,
AnyHashable("newMessagesAvailable"): 2]
Параметры ответа
| Параметр | Тип данных | Характер | Описание |
|---|---|---|---|
responseCode | String | Обязательный | Код выполнения запроса: - ok — запрос выполнен; - error-system-blocked — внешняя система недоступна - error-message-id-duplicate — сообщение с таким идентификатором уже было отправлено |
consumeOutMessageResult | Обязательный | Комплексный параметр, содержащий данные о результате обработки запроса | |
consumeOutMessageCode | String | Обязательный | Код обработки запроса: - ok — сообщение принято; - error-system — внутренняя ошибка при обработке сообщения; - error-message-id-duplicate — сообщение с таким идентификатором уже существует |
messageId | String | Обязательный | Идентификатор сообщения |
Статусы обработки сообщения шлюзом (ответ в consumeOutMessageCode)
ok— сообщение отправлено на платформу провайдера;error-system— системная ошибка;error-message-id-format— неверный формат идентификатора сообщения;error-message-id-duplicate— сообщение с таким идентификатором уже было обработано ранее;error-subject-unknown— подпись сообщения не определена;error-address-format— неверный формат адреса получателя;error-instant-message-data— неверное значение данных в параметрах IM-сообщения;error-out-message-template-text-not-specified— не указан текст шаблона сообщения;error-out-message-template-param-key-format— ключ для параметра подстановки в шаблоне сообщения указан неверно;error-out-message-template-param-unknown— неизвестный параметр подстановки в шаблоне сообщения;error-out-message-template-param-value-format— неверный формат значения ключа в параметре подстановки
Пример запроса
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:out="http://www.edna.ru/ednagate/out-message-service">
<soapenv:Header/>
<soapenv:Body>
<out:consumeOutMessageRequest>
<out:auth>
<out:login>username</out:login>
<out:password>password</out:password>
</out:auth>
<out:consumeOutMessageArg>
<out:messageId>msg-12345</out:messageId>
<out:outMessageTypeId>type1</out:outMessageTypeId>
<out:subject>BANK</out:subject>
<out:address>79161112222</out:address>
<out:clientID>client-001</out:clientID>
<out:priority>high</out:priority>
<out:startTime>2022-04-25T18:30:00</out:startTime>
<out:stopTime>2022-04-25T20:30:00</out:stopTime>
<out:dlvInterval>
<out:dlvStart>09</out:dlvStart>
<out:dlvStop>18</out:dlvStop>
</out:dlvInterval>
<out:timezone>Europe/Moscow</out:timezone>
<out:comment>Test message</out:comment>
<out:options>
<out:option>
<out:key>pushTitle</out:key>
<out:value>Notification</out:value>
</out:option>
</out:options>
<out:outMessageTemplate>
<out:text>Your code is {code}</out:text>
</out:outMessageTemplate>
</out:consumeOutMessageArg>
</out:consumeOutMessageRequest>
</soapenv:Body>
</soapenv:Envelope>
Пример ответа
Пример успешного ответа
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:out="http://www.edna.ru/ednagate/out-message-service">
<soapenv:Header/>
<soapenv:Body>
<out:consumeOutMessageResponse>
<out:responseCode>ok</out:responseCode>
<out:consumeOutMessageResult>
<out:consumeOutMessageCode>ok</out:consumeOutMessageCode>
<out:messageId>msg-12345</out:messageId>
</out:consumeOutMessageResult>
</out:consumeOutMessageResponse>
</soapenv:Body>
</soapenv:Envelope>
Пример ответа с ошибкой
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:out="http://www.edna.ru/ednagate/out-message-service">
<soapenv:Header/>
<soapenv:Body>
<out:OutMessageServiceFaultCode>
<out:faultCode>error-syntax</out:faultCode>
</out:OutMessageServiceFaultCode>
</soapenv:Body>
</soapenv:Envelope>