Получение истории сообщений

Для запроса на получение истории сообщений получателя используется метод 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
}

Параметры запроса

ПараметрТип данныхХарактерОписание
subscriberFilterobject НеобязательныйФильтр получателя.
subscriberFilter.
address
string НеобязательныйАдрес получателя. Например, номер телефона.
subscriberFilter.
type
stringНеобязательныйТип адреса получателя.

Возможные значения:
PHONE
EMAIL
UTM
COOKIE_ID
INSTAGRAM_ID
FACEBOOK_ID
TELEGRAM_ID
GOOGLE_ID
APPLE_ID
YANDEX_ID
EXT_USER_ID
offsetintegerНеобязательныйКоличество сообщений, которые нужно пропустить после сортировки.

Значение по умолчанию — 0.
limitintegerНеобязательныйКоличество сообщений в ответе.

Значение по умолчанию — 15. Максимальное значение — 1000.
channelTypesarray of stringsНеобязательныйТип канала.

Возможные значения:
WHATSAPP — канал WhatsApp;
SMS — канал SMS;
VIBER — канал Viber;
PUSH — канал Push;
VK_NOTIFY — канал VK Notify;
OK_NOTIFY — канал OK Notify.

Например, если передано значение PUSH, возвращается контент сообщения только для канала Push. Можно передать несколько значений.
directionstringНеобязательныйНаправление сообщения.

Возможные значения:
IN — от получателя;
OUT — к получателю.
dateFromstringНеобязательныйВремя в формате ISO 8601 (например, «2024-07-01T00:00:00Z»), с которого запрашиваются сообщения. По умолчанию запрашиваются сообщения за последние 30 дней.

В параметре limit укажите количество сообщений, которое вы хотите получить.
dateTostringНеобязательныйВремя в формате ISO 8601 (например, «2024-07-01T00:00:00Z»), по которое запрашиваются сообщения. По умолчанию запрашиваются сообщения за последние 30 дней.

Максимальный период запроса — один год.

В параметре limit укажите количество сообщений, которое вы хотите получить.
sortobjectНеобязательныйПараметры сортировки.
sort.propertystringНеобязательныйЗначение параметра для сортировки. Можно использовать значение любого параметра из примера ответа.
sort.directionstringНеобязательныйНаправление сортировки.

Возможные значения:
ASC — сортировка по возрастанию;
DESC — сортировка по убыванию.

Значение по умолчанию — DESC. Используется только с параметром sort.property.
trafficTypesarray of stringsНеобязательныйТип трафика при значении параметра "direction":"OUT".

Возможные значения:
AD — рекламные сообщения;
SERVICE — сервисные сообщения;
HSM — шаблонные сообщения WhatsApp;
CHAT — сообщения WhatsApp в свободной форме.
subjectIDintegerНеобязательныйИдентификатор подписи.

Формат ответа

В ответ на запрос возвращается 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
}

Параметры ответа

ПараметрТип данныхОписание
contentarray of objectsМассив передаваемых сообщений.
content.messageIdintegerВнутренний идентификатор сообщения.
content.tenantIdintegerИдентификатор личного кабинета пользователя.
content.channelTypestringТип канала.

Возможные значения:
WHATSAPP — канал WhatsApp;
SMS — канал SMS;
VIBER — канал Viber;
PUSH — канал Push;
VK_NOTIFY — канал VK Notify;
OK_NOTIFY — канал OK Notify.
content.directionstringНаправление сообщения.

Возможные значения:
IN — входящее сообщение;
OUT — исходящее сообщение.

По умолчанию возвращаются все сообщения.
content.addressstringАдрес отправителя для входящих и получателя для исходящих сообщений.
content.contentstringТекст сообщения.
content.deliveryStatusstringСтатус доставки сообщения.

Возможные значения:
ACCEPTED — сообщение принято в edna Pulse;
INVALID — исходящее сообщение не прошло этапы валидации на стороне edna Pulse;
ENQUEUED — исходящее сообщение успешно отправлено на стороне edna Pulse;
SENT — исходящее сообщение успешно отправлено получателю;
UNDELIVERED — исходящее сообщение не доставлено получателю или отправлено неуспешно;
DELIVERED — исходящее сообщение доставлено получателю;
READ — исходящее сообщение прочитано получателем.
content.deliveryStatusAtstringДата и время статуса доставки в формате ISO 8601 (например, «2024-01-11T01:01:11.000+0000»).
content.deliveryStatusMessagestringСообщение статуса доставки.
content.sentOrReceivedAtstringДата и время отправки исходящих сообщений и доставки входящих сообщений в формате ISO 8601 (например, «2024-01-11T02:02:22.223+0000»).
content.subjectIdintegerИдентификатор подписи.
content.subjectNamestringИмя подписи.
content.cascadeIdintegerИдентификатор каскада.
content.cascadeNamestringИмя каскада.
content.cascadeStageUuidstringНомер шага каскада.
content.broadcastIdintegerИдентификатор рассылки.
content.broadcastNamestringИмя рассылки.
content.trafficTypestringТип трафика при значении параметра "direction":"OUT".

Возможные значения:
AD — рекламные сообщения;
SERVICE — сервисные сообщения;
HSM — шаблонные сообщения WhatsApp;
CHAT — сообщения WhatsApp в свободной форме.
content.segmentsintegerКоличество сегментов сообщения.
content.subscriberIdintegerИдентификатор получателя в edna Pulse.
content.matcherIdintegerИдентификатор шаблона, по которому отправлялись сообщения при значении параметра "direction":"OUT".
content.matcherNamestringНазвание шаблона, по которому отправлялись сообщения при значении параметра "direction":"OUT".
content.commentstringКомментарий к сообщению.

Параметр comment можно передавать при отправке сообщений и использовать для уникальной идентификации сообщений или рассылок.
hasNextbooleanФлаг наличия следующей страницы.
content.replyInMessageIdintegerВнутренний идентификатор цитируемого сообщения пользователя. Пользователь цитирует свое сообщение, отправленное компании.
content.replyOutMessageIdintegerВнутренний идентификатор цитируемого сообщения компании. Пользователь цитирует сообщение, полученное от компании.
content.replyOutMessage
ExternalRequestId
integerВнешний идентификатор цитируемого сообщения компании, который она указывает при отправке исходящего сообщения по API. В том случае, если пользователь процитировал сообщение, полученное от компании.

Ошибки

Возможные ошибки после вызова метод api/messages/history:

КодОшибкаОписание
401Api-key not foundУказан неверный API-ключ.
400not-valid-requestУказано пустое значение параметра address.
400limit-not-validУказано значение больше 1000 в параметре limit.
400date-from-not-validУказана дата более чем за один год до текущей даты в значении параметра dateFrom.
400message-matcher-subject-not-foundУказан неверный идентификатор в значении параметра subjectId.