Message Status Logs

What Are Message Status Logs?

Message status logs track the delivery lifecycle of messages you send through your WhatsApp Business Account. These logs provide real-time updates on whether your messages were successfully sent, delivered, read, or if they failed with specific error details.

Each status update represents a stage in the message delivery process, helping you monitor message performance and troubleshoot delivery issues.

Endpoint Details

Endpoint: GET /v1/logs
Event Type Filter: eventTypes=Message%20Status (URL encoded)

Understanding Message Statuses

The payload contains status information with the following possible values:

sent: Message was successfully sent from your account

delivered: Message was delivered to the recipient's device

read: Message was read by the recipient

failed: Message delivery failed (includes error details)

Request Parameters

Required Parameters

Parameter	Type	Description
`eventTypes`	string	Must be `Message%20Status` (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 by specific WhatsApp Business phone number ID
`url`	string	Filter by specific webhook URL (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 Range Format

Dates use Ticks format (100-nanosecond intervals since January 1, 0001 UTC).

Example: 638000000000000000

Request Examples

Retrieve All Message Status Logs

Retrieve all message status logs without date filters:

Or with date range:

Filter by Phone Number

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": "Message Status",
                "payload": "{\"object\":\"whatsapp_business_account\",\"entry\":[{\"id\":\"123456789012345\",\"changes\":[{\"field\":\"messages\",\"value\":{\"messaging_product\":\"whatsapp\",\"metadata\":{\"display_phone_number\":\"15551234567\",\"phone_number_id\":\"123456789012345\"},\"statuses\":[{\"id\":\"msg_ABC123XYZ\",\"recipient_id\":\"1234567890\",\"status\":\"delivered\",\"timestamp\":\"1704067200\",\"conversation\":{\"id\":\"5f7375311518ef490638d5b08aee9eb5\",\"origin\":{\"type\":\"service\"}},\"pricing\":{\"pricing_model\":\"PMP\",\"billable\":false,\"category\":\"service\"}}]}}]}]}",
                "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": "Message Status",
                "payload": "{\"object\":\"whatsapp_business_account\",\"entry\":[{\"id\":\"123456789012345\",\"changes\":[{\"field\":\"messages\",\"value\":{\"messaging_product\":\"whatsapp\",\"metadata\":{\"display_phone_number\":\"15551234567\",\"phone_number_id\":\"123456789012345\"},\"statuses\":[{\"id\":\"msg_DEF456UVW\",\"recipient_id\":\"9876543210\",\"status\":\"failed\",\"timestamp\":\"1704067300\",\"errors\":[{\"code\":131047,\"href\":\"https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes/\",\"title\":\"Re-engagement message\",\"message\":\"Re-engagement message\",\"error_data\":{\"details\":\"Message failed to send because more than 24 hours have passed since the customer last replied to this number.\"}}]}]}}]}]}",
                "created_at": 638500000200000000,
                "direction": 1,
                "flyout_delivery_status": "-",
                "flyout_delivery_response": "-",
                "flyout_delivery_response_code": 0,
                "flyout_url": "-"
            }
        ],
        "next_page_token": "eyJQcm9qZWN0SWQiOnsiTiI6IjEyMzQ1In0sIkNyZWF0ZWRBdCI6eyJOOiI2Mzg1MDAwMDAwMDAwMDAwMCJ9fQ=="
    }
}

Response Field Reference

Top-Level Response

Field	Type	Description
`message`	string	Success message
`data`	object	Response data container

Log Entry Fields

Field	Type	Description
`project_id`	string	Project identifier
`phone_number_id`	string	WhatsApp Business phone number ID
`event_type`	string	Always "Message Status" for this endpoint
`payload`	string	JSON string containing status webhook payload
`created_at`	integer	Timestamp in Ticks format
`direction`	integer	Message direction (1 = incoming)
`flyout_delivery_status`	string	Flyout delivery status
`flyout_delivery_response`	string	Flyout delivery response
`flyout_delivery_response_code`	integer	HTTP response code for flyout
`flyout_url`	string	Flyout notification URL

Message Status Payload Structure

When you parse the payload JSON string, it contains:

{
    "object": "whatsapp_business_account",
    "entry": [
        {
            "id": "123456789012345",
            "changes": [
                {
                    "field": "messages",
                    "value": {
                        "messaging_product": "whatsapp",
                        "metadata": {
                            "display_phone_number": "15551234567",
                            "phone_number_id": "123456789012345"
                        },
                        "statuses": [
                            {
                                "id": "msg_ABC123XYZ",
                                "recipient_id": "1234567890",
                                "status": "delivered",
                                "timestamp": "1704067200",
                                "conversation": {
                                    "id": "5f7375311518ef490638d5b08aee9eb5",
                                    "origin": {
                                        "type": "service"
                                    }
                                },
                                "pricing": {
                                    "pricing_model": "PMP",
                                    "billable": false,
                                    "category": "service"
                                }
                            }
                        ]
                    }
                }
            ]
        }
    ]
}

Status Payload Fields

Field	Type	Description
`statuses[].id`	string	Unique message identifier
`statuses[].recipient_id`	string	WhatsApp ID of the recipient
`statuses[].status`	string	Status: "sent", "delivered", "read", or "failed"
`statuses[].timestamp`	string	Unix timestamp of the status update
`statuses[].conversation.id`	string	Conversation identifier
`statuses[].conversation.origin.type`	string	Origin type (e.g., "service")
`statuses[].pricing.pricing_model`	string	Pricing model (e.g., "PMP")
`statuses[].pricing.billable`	boolean	Whether the message is billable
`statuses[].pricing.category`	string	Message category
`statuses[].errors[]`	array	Error details (only present when status is "failed")

Failed Message Errors

When a message fails, the payload includes error information:

{
    "statuses": [
        {
            "status": "failed",
            "errors": [
                {
                    "code": 131047,
                    "href": "https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes/",
                    "title": "Re-engagement message",
                    "message": "Re-engagement message",
                    "error_data": {
                        "details": "Message failed to send because more than 24 hours have passed since the customer last replied to this number."
                    }
                }
            ]
        }
    ]
}

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

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

401 Unauthorized

{
    "message": "Unauthorized"
}

403 Forbidden

{
    "message": "Forbidden"
}

500 Internal Server Error

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

Important Considerations

7-Day Retention: Logs are only available for the last 7 days

Payload Parsing: The payload field is a JSON string that must be parsed

Multiple Statuses: A single message may have multiple status updates (sent → delivered → read)

Error Codes: Failed messages include error codes and details for troubleshooting

Timestamp Format: All timestamps use Ticks format

Use Cases

Delivery Monitoring: Track message delivery success rates

Read Receipt Tracking: Monitor when recipients read your messages

Failure Analysis: Identify and troubleshoot failed message deliveries

Performance Metrics: Calculate delivery and read rates

Compliance: Maintain audit trails of message statuses

Code Example: Parsing Status Logs

Retrieve All Logs - Get all event types

Retrieve Incoming Message Logs - Get incoming messages only

Retrieve Other Event Logs - Get other event types

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 ********************

What Are Message Status Logs?#

Endpoint Details#

Understanding Message Statuses#

Request Parameters#

Required Parameters#

Optional Parameters#

Date Range Format#

Request Examples#

Retrieve All Message Status Logs#

Filter by Phone Number#

Filter by Webhook URL#

With Page Size#

Response Structure#

Success Response (200 OK)#

Response Field Reference#

Top-Level Response#

Log Entry Fields#

Message Status Payload Structure#

Status Payload Fields#

Failed Message Errors#

Pagination#

Error Responses#

400 Bad Request#

401 Unauthorized#

403 Forbidden#

500 Internal Server Error#

Important Considerations#

Use Cases#

Code Example: Parsing Status Logs#

Related Endpoints#

Request

Responses