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

Обновлено: 8 апреля 2025

Для запроса на получение истории сообщений получателя используется метод api/messages/history.

Вызов метода `api/messages/history`

Чтобы вызвать метод api/messages/history, отправьте POST-запрос на URL-адрес https://app.edna.ru/api/messages/history

Если запрос выполнен успешно, метод возвращает ответ с кодом 200 и JSON-объект с текстом и информацией о сообщении. Если запрос выполнен неуспешно, метод возвращает код ошибки.

Формат тела запроса

{
    "subscriberFilter": {
        "address": "79000000000",
        "type": "PHONE"
    },
    "offset": 0,
    "limit": 0,
    "channelTypes": [
        "SMS"
    ],
    "messageId": 567890,
    "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.ru/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"
    ],
    "messageId": 567891,
    "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.address`	string	Необязательный	Адрес получателя. Например, номер телефона.
`subscriberFilter.type`	string	Необязательный	Тип адреса получателя: - `PHONE`. - `EMAIL` - `UTM` - `COOKIE_ID` - `INSTAGRAM_ID` - `TELEGRAM_ID` - `GOOGLE_ID` - `APPLE_ID` - `YANDEX_ID` - `EXT_USER_ID` - `FACEBOOK_ID` - `EXT_USER_ID`
`offset`	integer	Необязательный	Количество сообщений, которые нужно пропустить после сортировки. Значение по умолчанию — 0.
`limit`	integer	Необязательный	Количество сообщений в ответе. Значение по умолчанию — 0, максимальное — 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	Обязательный, если используется параметр `messageId`	Направление сообщения. - `IN` — от получателя; - `OUT` — к получателю.
`dateFrom`	string	Необязательный	Дата в формате ISO 8601 (например, `2024-07-01T00:00:00Z`), с которой запрашиваются сообщения. По умолчанию запрашиваются сообщения за последние 30 дней. Чтобы получить все сообщения от определенной даты в прошлом до настоящего момента, укажите необходимую дату только в параметре `dateFrom` и оставьте пустым параметр `dateTo`. При необходимости в параметре `limit` укажите количество сообщений, которое вы хотите получить. ISO 8601 - Convention
`dateTo`	string	Необязательный	Дата в формате ISO 8601 (например, `2024-07-01T00:00:00Z`), с которую запрашиваются сообщения. По умолчанию запрашиваются сообщения за последние 30 дней. Максимальный диапазон значений между параметрами `dateFrom` и `dateTo` — 366 дней. Чтобы получить все сообщения за последние 30 дней, укажите в параметре `dateTo` дату в промежутке последних 30 дней и оставьте пустым параметр `dateFrom`. Если в параметре `dateTo` указать дату позднее, чем 30 дней назад, и оставить пустым параметр `dateFrom` — в ответе будет пустой список. При необходимости в параметре `limit` укажите количество сообщений, которое вы хотите получить. ISO 8601 - Convention
`sort`	object	Необязательный	Параметры сортировки.
`sort.property`	string	Необязательный	Значение параметра для сортировки. Можно использовать значение любого параметра из примера ответа.
`sort.direction`	string	Необязательный	Направление сортировки: - `ASC` — сортировка по возрастанию; - `DESC` — сортировка по убыванию (по умолчанию) Используется только с параметром `sort.property`.
`trafficTypes`	array of strings	Необязательный	Тип трафика при значении параметра `direction:OUT`: - `AD` — рекламные сообщения; - `SERVICE` — сервисные сообщения; - `HSM` — шаблонные сообщения WhatsApp; - `CHAT` — сообщения WhatsApp в свободной форме.
`subjectID`	integer	Необязательный	Идентификатор подписи.
`messageID`	integer (long)	Необязательный	Внутренний идентификатор сообщения.

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

В ответ на запрос возвращается 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	Тип канала
`content.direction`	string	Направление сообщения. - `IN` — от получателя; - `OUT` — к получателю. По умолчанию возвращаются все сообщения.
`content.address`	string	Адрес отправителя для входящих и получателя для исходящих сообщений.
`content.content`	string	Текст сообщения. При использовании WhatsApp Flows в этом параметре будет приходить информация о Flow: - для исходящих сообщений — информация о Flow; - для входящих сообщений — информация об ответах получателя во Flow.
`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`) ISO 8601 - Convention
`content.deliveryStatusMessage`	string	Сообщение статуса доставки.
`content.sentOrReceivedAt`	string	Дата и время отправки исходящих сообщений и доставки входящих сообщений в формате ISO 8601 (например, `2024-01-11T02:02:22.223+0000`). ISO 8601 - Convention
`content.subjectId`	integer	Идентификатор подписи.
`content.subjectName`	string	Имя подписи.
`content.cascadeId`	integer	Идентификатор каскада.
`content.cascadeName`	string	Имя каскада.
`content.cascadeStageUuid`	string	Номер шага каскада.
`content.broadcastId`	integer	Идентификатор рассылки.
`content.broadcastName`	string	Имя рассылки.
`content.trafficType`	array of strings	Тип трафика при значении параметра `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	Внутренний идентификатор цитируемого сообщения компании. Пользователь цитирует сообщение, полученное от компании.
`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-range-not-valid	Диапазон значений между параметрами `dateFrom` и `dateTo` превышает 366 дней.
`400`	message-matcher-subject-not-found	Указан неверный идентификатор в значении параметра `subjectId`.

Вызов метода api/messages/history​

Формат тела запроса​

Пример запроса​

Тело запроса с параметром subscriberFilter​

Тело запроса без параметром subscriberFilter​

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

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

Пример ответа​

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

Ошибки​