Для запроса на получение истории сообщений получателя используется метод api/messages/history
.
Вызов метода api/messages/history
Чтобы вызвать метод api/messages/history
, отправьте POST-запрос на URL-адрес https://app.edna.by/api/messages/history
.
Если запрос выполнен успешно, метод возвращает ответ с кодом 200
и JSON-объект с текстом и информацией о сообщении. Если запрос выполнен неуспешно, метод возвращает код ошибки. Подробнее в разделе.
Формат тела запроса
{ "subscriberFilter": { "address": "79000000000", "type": "EDNA_ID" }, "offset": 0, "limit": 0, "channelTypes": [ "SMS" ], "direction": "OUT", "dateFrom": "2024-07-01T00:00:00Z", "dateTo": "2024-07-22T00:00:00Z", "sort": [ { "property": "messageId", "direction": "DESC" } ], "trafficTypes": [ "AD" ], "subjectId": 0 }
Пример запроса
Заголовок запроса:
POST https://app.edna.by/api/messages/history x-api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Content-Type: application/json
Тело запроса с параметром subscriberFilter
:
{ "subscriberFilter": { "address": "79000000000", "type": "PHONE" }, "offset": 0, "limit": 1000, "channelTypes": [ "SMS" ], "direction": "OUT", "dateFrom": "2024-07-01T00:00:00Z", "dateTo": "2024-07-22T00:00:00Z", "sort": [ { "property": "messageId", "direction": "DESC" } ], "trafficTypes": [ "AD" ], "subjectId": 50192 }
Тело запроса без параметра subscriberFilter
:
{ "offset": 0, "limit": 1000, "channelTypes": [ "SMS" ], "direction": "OUT", "dateFrom": "2024-07-01T00:00:00Z", "dateTo": "2024-07-22T00:00:00Z", "sort": [ { "property": "messageId", "direction": "DESC" } ], "trafficTypes": [ "AD" ], "subjectId": 50192 }
Параметры запроса
Параметр | Тип данных | Характер | Описание |
subscriberFilter | object | Необязательный | Фильтр получателя. |
subscriberFilter. | string | Необязательный | Адрес получателя. Например, номер телефона. |
subscriberFilter. | string | Необязательный | Тип адреса получателя. Возможные значения: • PHONE • EMAIL • UTM • COOKIE_ID • INSTAGRAM_ID • FACEBOOK_ID • TELEGRAM_ID • GOOGLE_ID • APPLE_ID • YANDEX_ID • EXT_USER_ID |
offset | integer | Необязательный | Количество сообщений, которые нужно пропустить после сортировки. Значение по умолчанию — 0. |
limit | integer | Необязательный | Количество сообщений в ответе. Значение по умолчанию — 15. Максимальное значение — 1000. |
channelTypes | array of strings | Необязательный | Тип канала. Возможные значения: • WHATSAPP — канал WhatsApp;• SMS — канал SMS;• VIBER — канал Viber;• PUSH — канал Push;• VK_NOTIFY — канал VK Notify;• OK_NOTIFY — канал OK Notify.Например, если передано значение PUSH , возвращается контент сообщения только для канала Push. Можно передать несколько значений. |
direction | string | Необязательный | Направление сообщения. Возможные значения: • IN — от получателя;• OUT — к получателю. |
dateFrom | string | Необязательный | Время в формате ISO 8601 (например, «2024-07-01T00:00:00Z»), с которого запрашиваются сообщения. По умолчанию запрашиваются сообщения за последние 30 дней. В параметре limit укажите количество сообщений, которое вы хотите получить. |
dateTo | string | Необязательный | Время в формате ISO 8601 (например, «2024-07-01T00:00:00Z»), по которое запрашиваются сообщения. По умолчанию запрашиваются сообщения за последние 30 дней. Максимальный период запроса — один год. В параметре limit укажите количество сообщений, которое вы хотите получить. |
sort | object | Необязательный | Параметры сортировки. |
sort.property | string | Необязательный | Значение параметра для сортировки. Можно использовать значение любого параметра из примера ответа. |
sort.direction | string | Необязательный | Направление сортировки. Возможные значения: • ASC — сортировка по возрастанию;• DESC — сортировка по убыванию.Значение по умолчанию — DESC . Используется только с параметром sort.property . |
trafficTypes | array of strings | Необязательный | Тип трафика при значении параметра "direction":"OUT" . Возможные значения: • AD — рекламные сообщения;• SERVICE — сервисные сообщения;• HSM — шаблонные сообщения WhatsApp;• CHAT — сообщения WhatsApp в свободной форме. |
subjectID | integer | Необязательный | Идентификатор подписи. |
Формат ответа
В ответ на запрос возвращается JSON-объект с сообщениями, отправленными пользователю или полученными от него согласно указанным условиям.
Пример ответа
{ "content": [ { "messageId": 8270556, "tenantId": 3193, "channelType": "SMS", "direction": "OUT", "address": "79000000000", "content": "{\"text\": \"Hello. Glad to see\", \"type\": \"TEXT\"}", "deliveryStatus": "DELIVERED", "deliveryStatusAt": "2024-07-23T08:08:20.000+0000", "sentOrReceivedAt": "2024-07-23T08:08:20.201+0000", "subjectId": 50192, "subjectName": "subject_sms", "cascadeId": 32522, "cascadeName": "cascade_sms", "cascadeStageUuid": "b75c5b32-d185-4784-aac0-ec3adc468a71", "broadcastId": 318463, "broadcastName": "cxzxzcxzcxz", "trafficType": "AD", "segments": 1, "subscriberId": 11354769 }, { "messageId": 8270515, "tenantId": 3193, "channelType": "SMS", "direction": "OUT", "address": "79000000001", "content": "{\"text\": \"Hello. Glad to see\", \"type\": \"TEXT\"}", "deliveryStatus": "DELIVERED", "deliveryStatusAt": "2024-07-23T08:02:11.000+0000", "sentOrReceivedAt": "2024-07-23T08:02:11.223+0000", "subjectId": 50192, "subjectName": "subject_sms", "cascadeId": 32522, "cascadeName": "cascade_sms", "matcherId": 6199, "matcherName": "serv_1", "cascadeStageUuid": "b75c5b32-d185-4784-aac0-ec3adc468a71", "broadcastId": 318462, "broadcastName": "cxvzxc", "trafficType": "SERVICE", "segments": 1, "subscriberId": 11354769 } ], "hasNext": false }
Параметры ответа
Параметр | Тип данных | Описание |
content | array of objects | Массив передаваемых сообщений. |
content.messageId | integer | Внутренний идентификатор сообщения. |
content.tenantId | integer | Идентификатор личного кабинета пользователя. |
content.channelType | string | Тип канала. Возможные значения: • WHATSAPP — канал WhatsApp;• SMS — канал SMS;• VIBER — канал Viber;• PUSH — канал Push;• VK_NOTIFY — канал VK Notify;• OK_NOTIFY — канал OK Notify. |
content.direction | string | Направление сообщения. Возможные значения: • IN — входящее сообщение;• OUT — исходящее сообщение.По умолчанию возвращаются все сообщения. |
content.address | string | Адрес отправителя для входящих и получателя для исходящих сообщений. |
content.content | string | Текст сообщения. |
content.deliveryStatus | string | Статус доставки сообщения. Возможные значения: • ACCEPTED — сообщение принято в edna Pulse;• INVALID — исходящее сообщение не прошло этапы валидации на стороне edna Pulse;• ENQUEUED — исходящее сообщение успешно отправлено на стороне edna Pulse;• SENT — исходящее сообщение успешно отправлено получателю;• UNDELIVERED — исходящее сообщение не доставлено получателю или отправлено неуспешно;• DELIVERED — исходящее сообщение доставлено получателю;• READ — исходящее сообщение прочитано получателем. |
content.deliveryStatusAt | string | Дата и время статуса доставки в формате ISO 8601 (например, «2024-01-11T01:01:11.000+0000»). |
content.deliveryStatusMessage | string | Сообщение статуса доставки. |
content.sentOrReceivedAt | string | Дата и время отправки исходящих сообщений и доставки входящих сообщений в формате ISO 8601 (например, «2024-01-11T02:02:22.223+0000»). |
content.subjectId | integer | Идентификатор подписи. |
content.subjectName | string | Имя подписи. |
content.cascadeId | integer | Идентификатор каскада. |
content.cascadeName | string | Имя каскада. |
content.cascadeStageUuid | string | Номер шага каскада. |
content.broadcastId | integer | Идентификатор рассылки. |
content.broadcastName | string | Имя рассылки. |
content.trafficType | string | Тип трафика при значении параметра "direction":"OUT" . Возможные значения: • AD — рекламные сообщения;• SERVICE — сервисные сообщения;• HSM — шаблонные сообщения WhatsApp;• CHAT — сообщения WhatsApp в свободной форме. |
content.segments | integer | Количество сегментов сообщения. |
content.subscriberId | integer | Идентификатор получателя в edna Pulse. |
content.matcherId | integer | Идентификатор шаблона, по которому отправлялись сообщения при значении параметра "direction":"OUT" . |
content.matcherName | string | Название шаблона, по которому отправлялись сообщения при значении параметра "direction":"OUT" . |
content.comment | string | Комментарий к сообщению. Параметр comment можно передавать при отправке сообщений и использовать для уникальной идентификации сообщений или рассылок. |
hasNext | boolean | Флаг наличия следующей страницы. |
content.replyInMessageId | integer | Внутренний идентификатор цитируемого сообщения пользователя. Пользователь цитирует свое сообщение, отправленное компании. |
content.replyOutMessageId | integer | Внутренний идентификатор цитируемого сообщения компании. Пользователь цитирует сообщение, полученное от компании. |
content.replyOutMessage ExternalRequestId | integer | Внешний идентификатор цитируемого сообщения компании, который она указывает при отправке исходящего сообщения по API. В том случае, если пользователь процитировал сообщение, полученное от компании. |
Ошибки
Возможные ошибки после вызова метод api/messages/history
:
Код | Ошибка | Описание |
401 | Api-key not found | Указан неверный API-ключ. |
400 | not-valid-request | Указано пустое значение параметра address . |
400 | limit-not-valid | Указано значение больше 1000 в параметре limit . |
400 | date-from-not-valid | Указана дата более чем за один год до текущей даты в значении параметра dateFrom . |
400 | message-matcher-subject-not-found | Указан неверный идентификатор в значении параметра subjectId . |