Requesting Message History

KB Home
API
edna Pulse API
Messages
Requesting Message History

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 about errors.

Request Format

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

Request Example

With the subscriberFilter parameter:

POST https://app.edna.io/api/messages/history 
x-api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Content-Type: application/json
{
    "subscriberFilter": {
        "address": "35000000000",
        "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
}

Without the subscriberFilter parameter:

POST https://app.edna.io/api/messages/history
x-api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Content-Type: application/json
{
    "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	The recipient’s filter.
`subscriberFilter. address`	string	Optional	The recipient’s address. For example, a phone number.
`subscriberFilter. type`	string	Optional	The recipient’s address type: `PHONE`, `EMAIL`, `UTM`, `COOKIE_ID`, `INSTAGRAM_ID`, `FACEBOOK_ID`, `TELEGRAM_ID`, `GOOGLE_ID`, `APPLE_ID`, `YANDEX_ID`, `EXT_USER_ID`.
`dateFrom`	string	Optional	The time in ISO 8601 format (for example, “2024-07-01T00:00:00Z”) from which messages are requested. By default, messages from the last 30 days are requested. In the `limit` parameter, specify the number of messages you want to get.
`dateTo`	string	Optional	The time in ISO 8601 format (for example, “2024-07-01T00:00:00Z”) at which messages are requested. By default, messages from the last 30 days are requested. The maximum request period is one year. In the `limit` parameter, specify the number of messages you want to get.
`limit`	integer	Optional	The number of messages in the response. The default value is 15. The maximum value is 1000.
`sort`	object	Optional	The sorting parameters.
`sort.direction`	string	Optional	The sorting direction: • `ASC`: ascending sorting; • `DESC`: descending sorting. The default is `DESC`. It is only used with the `sort.property` parameter.
`channelTypes`	array of strings	Optional	The channel type filter: `WHATSAPP`, `SMS`, `VIBER`, `PUSH`. For example, if a PUSH value is passed, the message content will only be returned for the push channel. You can pass multiple values.
`direction`	string	Optional	The direction of the message. Values: • `IN`: from the receiver; • `OUT`: to the recipient.
`trafficType`	array of strings	Optional	The traffic type. The value is `"direction":"OUT"`. Possible options: • `AD`: marketing messages; • `SERVICE`: service messages; • `HSM`: template messages (WhatsApp); • `CHAT`: free messages (WhatsApp).
`subjectID`	integer	Optional	The subject ID.
`offset`	integer	Optional	The number of messages to skip after sorting. The default value is 0.
`sort.property`	string	Optional	The parameter for sorting. You can use the value of any parameter from the response example to sort.

Response Format

A JSON object is returned in response to the request. The JSON object contains 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": "35000000001",
            "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	The array of transmitted messages.
`content.messageId`	integer	The internal ID of the message.
`content.tenantId`	integer	The user’s personal account ID.
`content.channelType`	string	The channel type. Possible values: `WHATSAPP`, `SMS`, `VIBER`, `PUSH`.
`content.direction`	string	The message direction: `IN` (incoming) or `OUT` (outgoing). By default, all messages are returned.
`content.address`	string	The sender’s address for incoming messages and the recipient’s address for outgoing messages.
`content.content`	string	The text of the message.
`content.deliveryStatus`	string	The message delivery status. Possible values: • `ACCEPTED`: message accepted to edna Pulse. • `INVALID`: outgoing message didn’t pass validation on the edna Pulse side. • `ENQUEUED`: outgoing message was successfully sent on the edna Pulse side. • `SENT`: outgoing message was successfully sent to the recipient. • `UNDELIVERED`: outgoing message wasn’t delivered to the recipient or was sent unsuccessfully. • `DELIVERED`: outgoing message was delivered to the recipient. • `READ`: outgoing message was read by the recipient.
`content.deliveryStatusAt`	string	The date and time of delivery status in ISO 8601 format (for example, “2024-07-01T00:00:00Z”).
`content.deliveryStatusMessage`	string	The delivery status message.
`content.sentOrReceivedAt`	string	The date and time of sending for outgoing messages and delivery for incoming messages in ISO 8601 format (for example, “2024-07-01T00:00:00Z”).
`content.subjectId`	integer	The subject ID.
`content.subjectName`	string	The subject name.
`content.cascadeId`	integer	The cascade ID.
`content.cascadeName`	string	The cascade name.
`content.cascadeStageUuid`	string	The cascade step number.
`content.broadcastId`	integer	The broadcast ID.
`content.broadcastName`	string	The broadcast name.
`content.trafficType`	string	The traffic type. The value is `"direction":"OUT"`. Possible options: • `AD`: marketing messages; • `SERVICE`: service messages; • `HSM`: template messages (WhatsApp); • `CHAT`: free messages (WhatsApp).
`content.segments`	integer	The number of message segments.
`content.subscriberId`	integer	The recipient’s ID in edna Pulse.
`content.matcherId`	integer	The ID of the template used to send messages. The value is `"direction":"OUT"`.
`content.matcherName`	string	The name of the template used to send messages. The value is `"direction":"OUT"`.
`content.comment`	string	The `comment` parameter can be passed when sending messages. It can be used to uniquely identify a message or broadcast.
`number`	integer	The page number.
`size`	integer	The number of items in the response.
`hasNext`	boolean	The flag indicating the presence of the next page.
`content.replyInMessageId`	integer	The internal identifier of the user’s quoted message. The user quotes their message sent to the company.
`content.replyOutMessageId`	integer	The internal identifier of the company’s quoted message. The user quotes a message received from the company.
`content.replyOutMessage` `ExternalRequestId`	integer	The external identifier of the company’s quoted message, which it specifies when sending an outgoing message via the API if the user has quoted a message received from the company.

Errors

Possible errors after calling the hiapi/messages/historystory method:

Code	Error	Description
`401`	`Api-key not found`	An invalid API key is specified.
`400`	`not-valid-request`	An empty value is specified for the `address` parameter.
`400`	`limit-not-valid`	A value greater than 1000 is specified in the `limit` parameter.
`400`	`date-from-not-valid`	The specified date is more than one year before the current date in the value of the `dateFrom` parameter.
`400`	`message-matcher-subject-not-found`	An invalid identifier is specified in the value of the `subjectID` parameter.

Log in with a single edna account