MEmeta
Message History

Get WhatsApp Business Account Message History

Retrieve paginated message history for a WhatsApp Business Account phone number, including delivery status events, timestamps, and webhook update information.

Use Cases:

  • Track message delivery status and events
  • Monitor webhook delivery and update states
  • Retrieve historical message delivery information
  • Debug message delivery issues and webhook failures

Rate Limiting: Standard Graph API rate limits apply. Use appropriate retry logic with exponential backoff.

Caching: Message history data can be cached for moderate periods, but delivery status events may change frequently. Implement appropriate cache invalidation strategies.

Pagination: This endpoint supports cursor-based pagination. Use the after and before cursors from the response to navigate through results.

get/{Version}/{Phone-Number-ID}/message_history

Request

  • Base URL
    https://graph.facebook.com
  • URL
    https://graph.facebook.com/{Version}/{Phone-Number-ID}/message_history
  • Auth
    HTTP bearer

Path parameters

Versionstring required

Graph API version to use for this request. Determines the API behavior and available features.

Phone-Number-IDstring required

Your WhatsApp Business Account phone number ID. This ID is provided when you register the phone number and can be found in your WhatsApp Business Manager or through phone number APIs.

Query parameters

message_idstring

Filter results by specific WhatsApp message ID (WAMID). When provided, only message history for this specific message will be returned.

fieldsstring

Comma-separated list of fields to include in the response. If not specified, default fields will be returned (id, message_id). Available fields: id, message_id, events{delivery_status,webhook_update_state,timestamp,application,webhook_uri,error_description}

limitinteger

Maximum number of message history entries to return per page. Default is 25, maximum is 100.

afterstring

Cursor for pagination. Use this to get the next page of results. This value comes from the paging.cursors.after field in previous responses.

beforestring

Cursor for pagination. Use this to get the previous page of results. This value comes from the paging.cursors.before field in previous responses.

Headers

User-Agentstring
Example:Meta-Business-Messaging-OpenAPI/1.0.0;spec=2025-10-21

The user agent string identifying the client software making the request.

Authorizationstring required
Example:Bearer EAABwzLixnjYBOzYmNMJJGfHq9DgNh...

Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token.

Response

Successfully retrieved WhatsApp Business Account message history

Example response

{
  "data": [
    {
      "id": "1234567890123456",
      "message_id": "wamid.HBgLMTY0NzM3Nzc3NzUVAgARGBI5QTNEQTA2RjdGMEY4RTRGAA==",
      "events": {
        "data": [
          {
            "id": "2345678901234567",
            "delivery_status": "DELIVERED",
            "webhook_update_state": "DELIVERED",
            "timestamp": 1640995200,
            "application": {
              "id": "9876543210987654"
            },
            "webhook_uri": "https://example.com/webhook",
            "error_description": "Webhook endpoint returned HTTP 500"
          }
        ],
        "paging": {
          "cursors": {
            "before": "MAZDZD",
            "after": "MTAxNTExOTQ1MjAwNzI5NDE="
          },
          "previous": "https://graph.facebook.com/v23.0/1234567890123456/message_history?before=MAZDZD",
          "next": "https://graph.facebook.com/v23.0/1234567890123456/message_history?after=MTAxNTExOTQ1MjAwNzI5NDE="
        }
      }
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MTAxNTExOTQ1MjAwNzI5NDE="
    },
    "previous": "https://graph.facebook.com/v23.0/1234567890123456/message_history?before=MAZDZD",
    "next": "https://graph.facebook.com/v23.0/1234567890123456/message_history?after=MTAxNTExOTQ1MjAwNzI5NDE="
  }
}

Changes

No recorded changes to this operation across all 5 revisions of this API.