Incoming Message Logs

Overview

This endpoint retrieves incoming text messages that have been received by your WhatsApp Business Account. These are the same payloads that would be sent to your configured webhook when an incoming message event occurs.

When a user sends a text message to your WhatsApp Business number, the system captures this event and stores it as a log entry. You can retrieve these logs using this endpoint to view all incoming messages within a specified time range.

Important: Logs are retained for the last 7 days only. You can only retrieve logs that fall within this 7-day window from the current date.

Request Parameters

Required Parameters

Parameter	Type	Description
`eventTypes`	string	Must be `Incoming%20Message` (URL encoded)

Optional Parameters

Parameter	Type	Description
`fromDate`	integer	Start date in Ticks format (100-nanosecond intervals since January 1, 0001 UTC). If omitted, retrieves logs from the beginning of available data.
`toDate`	integer	End date in Ticks format. If omitted, retrieves logs up to the current time.
`phoneNumberId`	string	Filter logs for a specific WhatsApp Business phone number ID
`url`	string	Filter logs for a specific webhook URL (must be URL encoded)
`pageSize`	integer	Number of log entries to return per page. Default: 20, Maximum: 20
`nextPageToken`	string	Token for pagination to retrieve the next page of results. Use the `next_page_token` value from the previous response.

Date Format

The fromDate and toDate parameters use Ticks format, which represents the number of 100-nanosecond intervals that have elapsed since January 1, 0001 at 00:00:00 UTC.

Example: 638000000000000000 represents a specific timestamp in this format.

Request Examples

Basic Request

Retrieve all incoming messages without date filters:

Or with date range:

Filter by Phone Number ID

Filter by Webhook URL

With Page Size

Response Structure

Success Response (200 OK)

{
    "message": "Notification logs retrieved successfully",
    "data": {
        "logs": [
            {
                "project_id": "12345",
                "phone_number_id": "123456789012345",
                "event_type": "Incoming Message",
                "payload": "{\"object\":\"whatsapp_business_account\",\"entry\":[{\"id\":\"123456789012345\",\"changes\":[{\"field\":\"messages\",\"value\":{\"messaging_product\":\"whatsapp\",\"metadata\":{\"display_phone_number\":\"15551234567\",\"phone_number_id\":\"123456789012345\"},\"contacts\":[{\"wa_id\":\"1234567890\",\"profile\":{\"name\":\"John Doe\"}}],\"messages\":[{\"from\":\"1234567890\",\"id\":\"wamid.HBgMDEyMzQ1Njc4OTAFQIAEhgWM0VCMDI5NTg3MDU0MDIxQUVCMzA0RgA=\",\"timestamp\":\"1704067200\",\"type\":\"text\",\"text\":{\"body\":\"Hello, this is a test message\"}}]}}]}]}",
                "created_at": 638500000000000000,
                "direction": 1,
                "flyout_delivery_status": "-",
                "flyout_delivery_response": "-",
                "flyout_delivery_response_code": 0,
                "flyout_url": "-"
            },
            {
                "project_id": "12345",
                "phone_number_id": "123456789012345",
                "event_type": "Incoming Message",
                "payload": "{\"object\":\"whatsapp_business_account\",\"entry\":[{\"id\":\"123456789012345\",\"changes\":[{\"field\":\"messages\",\"value\":{\"messaging_product\":\"whatsapp\",\"metadata\":{\"display_phone_number\":\"15551234567\",\"phone_number_id\":\"123456789012345\"},\"contacts\":[{\"wa_id\":\"9876543210\",\"profile\":{\"name\":\"Jane Smith\"}}],\"messages\":[{\"from\":\"9876543210\",\"id\":\"wamid.HBgMDk4NzY1NDMyMTBFQIAEhgWM0VCMDM0NDk3MUE3RTJFNzA0MUJGMAA=\",\"timestamp\":\"1704067260\",\"type\":\"text\",\"text\":{\"body\":\"How can I help you today?\"}}]}}]}]}",
                "created_at": 638500000100000000,
                "direction": 1,
                "flyout_delivery_status": "-",
                "flyout_delivery_response": "-",
                "flyout_delivery_response_code": 0,
                "flyout_url": "-"
            }
        ],
        "next_page_token": "eyJQcm9qZWN0SWQiOnsiTiI6IjEyMzQ1In0sIkNyZWF0ZWRBdCI6eyJOOiI2Mzg1MDAwMDAwMDAwMDAwMCJ9fQ=="
    }
}

Response Fields

Field	Type	Description
`message`	string	Success message indicating the operation result
`data`	object	Container for the response data
`data.logs`	array	Array of log entries matching the query criteria
`data.logs[].project_id`	string	The project identifier
`data.logs[].phone_number_id`	string	The WhatsApp Business phone number ID that received the message
`data.logs[].event_type`	string	Type of event (e.g., "Incoming Message")
`data.logs[].payload`	string	JSON string containing the full webhook payload. This is the same payload structure that would be sent to your webhook endpoint.
`data.logs[].created_at`	integer	Timestamp in Ticks format when the log entry was created
`data.logs[].direction`	integer	Message direction (1 = incoming)
`data.logs[].flyout_delivery_status`	string	Delivery status for flyout notifications
`data.logs[].flyout_delivery_response`	string	Delivery response for flyout notifications
`data.logs[].flyout_delivery_response_code`	integer	HTTP response code for flyout delivery
`data.logs[].flyout_url`	string	URL for flyout notifications
`data.next_page_token`	string	Token for pagination. Use this token to retrieve the next page of results.

Webhook Payload Structure

The payload field in each log entry contains a JSON string that matches the webhook payload structure sent by WhatsApp Business API. When parsed, it has the following structure:

{
    "object": "whatsapp_business_account",
    "entry": [
        {
            "id": "123456789012345",
            "changes": [
                {
                    "field": "messages",
                    "value": {
                        "messaging_product": "whatsapp",
                        "metadata": {
                            "display_phone_number": "15551234567",
                            "phone_number_id": "123456789012345"
                        },
                        "contacts": [
                            {
                                "wa_id": "1234567890",
                                "profile": {
                                    "name": "John Doe"
                                }
                            }
                        ],
                        "messages": [
                            {
                                "from": "1234567890",
                                "id": "wamid.HBgMDEyMzQ1Njc4OTAFQIAEhgWM0VCMDI5NTg3MDU0MDIxQUVCMzA0RgA=",
                                "timestamp": "1704067200",
                                "type": "text",
                                "text": {
                                    "body": "Hello, this is a test message"
                                }
                            }
                        ]
                    }
                }
            ]
        }
    ]
}

Webhook Payload Fields

Field	Type	Description
`object`	string	Always "whatsapp_business_account" for WhatsApp Business API webhooks
`entry[].id`	string	Unique identifier for the WhatsApp Business Account entry
`entry[].changes[].field`	string	The field that changed (typically "messages" for message events)
`entry[].changes[].value.messaging_product`	string	Always "whatsapp"
`entry[].changes[].value.metadata.display_phone_number`	string	The phone number displayed to users
`entry[].changes[].value.metadata.phone_number_id`	string	The WhatsApp Business phone number ID
`entry[].changes[].value.contacts[].wa_id`	string	WhatsApp ID of the sender
`entry[].changes[].value.contacts[].profile.name`	string	Display name of the sender
`entry[].changes[].value.messages[].from`	string	WhatsApp ID of the message sender
`entry[].changes[].value.messages[].id`	string	Unique message identifier
`entry[].changes[].value.messages[].timestamp`	string	Unix timestamp when the message was sent
`entry[].changes[].value.messages[].type`	string	Message type (e.g., "text")
`entry[].changes[].value.messages[].text.body`	string	The text content of the message

Pagination

When there are more results available, the response includes a next_page_token. To retrieve the next page, include the nextPageToken parameter in your request:

Continue this process until no next_page_token is returned in the response.

Error Responses

400 Bad Request

Invalid request parameters or malformed query string.

{
    "message": "Invalid request parameters",
    "data": null
}

401 Unauthorized

Missing or invalid authentication token.

{
    "message": "Unauthorized"
}

403 Forbidden

Valid token but insufficient permissions.

{
    "message": "Forbidden"
}

500 Internal Server Error

Server error occurred while processing the request.

{
    "message": "Internal server error",
    "data": null
}

Use Cases

Retrieve Incoming Messages: Fetch all incoming text messages within a specific time range for your project

Webhook Verification: Compare webhook payloads received with stored logs

Message History: Build a message history interface for your application

Analytics: Analyze incoming message patterns and volumes

Debugging: Troubleshoot message delivery issues by reviewing stored payloads

Notes

Log Retention: Logs are only available for the last 7 days. Any requests for logs older than 7 days will not return results.

The payload field is stored as a JSON string. You'll need to parse it to access the nested structure.

The direction field value of 1 indicates an incoming message.

Timestamps in the created_at field use Ticks format.

The eventTypes parameter should be URL encoded when used in the query string (e.g., Incoming%20Message for "Incoming Message").

This endpoint retrieves logs that match the webhook payloads sent to your configured webhook endpoints.

Example: Parsing the Payload

Retrieve All Event Logs - Get all event types without filtering

Retrieve Message Status Logs - Get message status updates only

Retrieve Other Event Logs - Get other event types only

Retrieve Multiple Event Types - Get specific multiple event types

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Overview#

Request Parameters#

Required Parameters#

Optional Parameters#

Date Format#

Request Examples#

Basic Request#

Filter by Phone Number ID#

Filter by Webhook URL#

With Page Size#

Response Structure#

Success Response (200 OK)#

Response Fields#

Webhook Payload Structure#

Webhook Payload Fields#

Pagination#

Error Responses#

400 Bad Request#

401 Unauthorized#

403 Forbidden#

500 Internal Server Error#

Use Cases#

Notes#

Example: Parsing the Payload#

Related Endpoints#

Request

Responses