Requesting Message History

Last updated: 8 April 2025

The api/messages/history method is used to request the recipient’s message history.

Calling api/messages/history Method

To call the api/messages/history method, send a POST request to the URL https://app.edna.io/api/messages/history.

If the request is successful, the method returns a response with a code of 200 and a JSON object with text and information about the message. If the request fails, the method returns an error code. More (#errors).

Request Body Format

{
    "subscriberFilter": {
        "address": "35000000000",
        "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
}

Request Example

POST https://app.edna.io/api/messages/history 
x-api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Content-Type: application/json

Request body with the `subscriberFilter` parameter

{
    "subscriberFilter": {
        "address": "35000000000",
        "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
} 

Request body without the `subscriberFilter` parameter

{
    "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
}

Request Parameters

Parameter	Data type	Character	Description
`subscriberFilter`	object	Optional	Recipient filter.
`subscriberFilter.address`	string	Optional	Recipient's address. For example, a phone number.
`subscriberFilter.type`	string	Optional	Recipient address type: - `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	Optional	The number of messages to skip after sorting. The default value is 0.
`limit`	integer	Optional	The number of messages in the response. The default value is 0, and the maximum value is 1000.
`channelTypes`	array of strings	Optional	Channel type: - `WHATSAPP` — WhatsApp channel; - `VIBER` — Viber channel. You can pass multiple values.
`direction`	string	Required if the `messageId` parameter is used	The direction of the message. - `IN` — from the recipient; - `OUT`— to the recipient.
`DateFrom`	string	Optional	The date in the ISO 8601 format (for example, `2024-07-01T00:00:00Z`) from which the messages are requested. By default, messages for the last 30 days are requested. To receive all messages from a certain date in the past to the present, specify the required date only in the `DateFrom` parameter and leave the `DateTo` parameter empty. If necessary, specify the number of messages you want to receive in the `limit` parameter. ISO 8601 - Convention
`dateTo`	string	Optional	The date in the ISO 8601 format (for example, `2024-07-01T00:00:00Z`) from which the messages are requested. By default, messages for the last 30 days are requested. The maximum range of values between the `DateFrom` and `DateTo` parameters is 366 days. To get all messages for the last 30 days, specify the date in the last 30 days in the `DateTo` parameter and leave the `DateFrom` parameter empty. If you specify a date later than 30 days ago in the `DateTo` parameter and leave the `DateFrom` parameter empty, the response will contain an empty list. If necessary, specify the number of messages you want to receive in the `limit` parameter. ISO 8601 - Convention
`sort`	object	Optional	Sorting options.
`sort.property`	string	Optional	Value of the parameter for sorting. You can use the value of any parameter from the sample response.
`sort.direction`	string	Optional	Sorting direction: - `ASC` — ascending sort; -`DESC` — descending sort (default) Is used only with the `sort.property` parameter.
`trafficTypes`	array of strings	Optional	Traffic type with the value of the `direction:OUT` parameter: - `AD` — advertising messages; - `SERVICE` — service messages; - `HSM` — WhatsApp template messages; - `CHAT` — WhatsApp messages in free form.
`SubjectID`	integer	Optional	Signature identifier.
`messageId`	integer (long)	Optional	Internal message identifier.

Response Format

In response to the request, a JSON object is returned with messages sent to or received from the user according to the specified conditions.

Response Example

{
    "content": [
        {
            "messageId": 8270556,
            "tenantId": 3193,
            "channelType": "SMS",
            "direction": "OUT",
            "address": "35000000000",
            "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": "35000000000",
            "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
}

Response parameters

Parameter	Data type	Description
`content`	array of objects	Array of transmitted messages.
`content.messageId`	integer	Internal ID of the message.
`content.TenantId`	integer	ID of the user's personal account.
`content.channelType`	string	Channel type
`content.direction`	string	Message direction. - `IN` — from the recipient; - `OUT` — to the recipient. By default, all messages are returned.
`content.address`	string	Sender's address for incoming and recipient's address for outgoing messages.
`content.content`	string	Text of the message. When using WhatsApp Flows, information about Flow will be sent in this parameter: - for outgoing messages — information about Flow; - for incoming messages — information about the recipient's responses in Flow.
`content.deliveryStatus`	string	Message delivery status. - `ACCEPTED` — the message was received by edna Pulse; - `INVALID` — the outgoing message did not pass the validation stages on the edna Pulse side; - `ENQUEUED` — the outgoing message was successfully sent on the edna side Pulse; - `SENT` — outgoing message successfully sent to recipient; - `UNDELIVERED` — outgoing message not delivered to recipient or unsuccessfully sent; - `DELIVERED` — outgoing message delivered to recipient; - `READ` — the outgoing message has been read by the recipient.
`content.deliveryStatusAt'	string	Date and time of delivery status in ISO 8601 format (for example, `2024-01-11T01:01:11.000+0000`) https://sentenz .github.io/convention/convention/iso-8601/
`content.deliveryStatusMessage`	string	Delivery status message.
`content.sentOrReceivedAt`	string	Date and time of sending outgoing messages and delivering incoming messages in ISO 8601 format (for example, `2024-01-11T02:02:22.223+0000`). ISO 8601 - Convention
`content.subjectId`	integer	The signature ID.
`content.subjectName`	string	Signature name.
`content.cascadeId`	integer	Cascade ID.
`content.cascadeName`	string	Cascade name.
`content.cascadeStageUuid`	string	Cascade step number.
`content.broadcastId`	integer	The broadcast list ID.
`content.broadcastName`	string	Mailing list name.
`content.trafficType`	array of strings	Traffic type with the value of the `direction:OUT` parameter: - `AD` — advertising messages; - `SERVICE` — service messages; - `HSM` — WhatsApp template messages; - `CHAT` — WhatsApp messages in free form.
`content.segments`	integer	The number of message segments.
`content.subscriberId`	integer	The recipient's ID in edna Pulse.
`content.matcherId`	integer	ID of the template that messages were sent to when the `direction:OUT` parameter was set.
`content.matcherName`	string	The name of the template used to send messages with the value of the `direction:OUT` parameter.
`content.comment`	string	Comment on the message. The `comment` parameter can be passed when sending messages and used to uniquely identify messages or newsletters.
`hasNext`	boolean	The flag for the presence of the next page.
`content.replyInMessageId`	integer	The internal identifier of the user's quoted message. The user quotes his message sent to the company.
`content.replyOutMessageId`	integer	The internal identifier of the quoted message of the company. The user quotes a message received from the company.
`ExternalRequestId`	integer	The external identifier of the company's quoted message, which it specifies when sending an outgoing message via the API. In the event that the user quoted a message received from the company.

Errors

Possible errors after calling the api/messages/history method:

Code	Error	Description
`401`	`Api key not found`	Invalid API key specified.
`400`	`not-valid-request`	An empty value of the `address` parameter is specified.
`400`	`limit-not-valid`	A value greater than 1000 is specified in the `limit` parameter.
`400`	`date-range-not-valid`	The range of values between the `DateFrom` and `DateTo` parameters exceeds 366 days.
`400`	`message-matcher-subject-not-found`	Invalid identifier is specified in the value of the `SubjectID` parameter.

Calling api/messages/history Method​

Request Body Format​

Request Example​

Request body with the subscriberFilter parameter​

Request body without the subscriberFilter parameter​

Request Parameters​

Response Format​

Response Example​

Response parameters​

Errors​