WhatsApp Message History API

openapi: 3.2.0
info:
  title: Meta Graph API - Application Connected Client Businesses…
  version: v23.0
  description: 'API for retrieving connected client businesses associated with a Meta application.


    This endpoint allows applications to retrieve information about businesses that have

    established client connections through the application. This is essential for managing

    business relationships and understanding client business configurations.'
  contact:
    name: Meta Business Platform Team
    url: https://developers.facebook.com/support
  license:
    name: Meta Platform Terms
    url: https://developers.facebook.com/terms
  termsOfService: https://developers.facebook.com/terms
servers:
- url: https://graph.facebook.com
  description: Production Graph API server
- url: https://graph.facebook.com
- url: https://graph.facebook.com
  description: WhatsApp Business Cloud API
- url: https://graph.facebook.com
  description: Meta Graph API production server
tags:
- name: Message History
  description: APIs for retrieving WhatsApp Business Account message history and delivery status information
paths:
  /{Version}/{Phone-Number-ID}/message_history:
    get:
      summary: Get WhatsApp Business Account Message History
      description: '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.'
      operationId: getMessageHistory
      tags:
      - Message History
      parameters:
      - $ref: '#/components/parameters/UserAgent'
      - $ref: '#/components/parameters/Authorization'
      - name: Version
        in: path
        required: true
        description: 'Graph API version to use for this request. Determines the API behavior and available features.

          '
        schema:
          type: string
          pattern: ^v[0-9]+\.[0-9]+$
        example: v23.0
      - name: Phone-Number-ID
        in: path
        required: true
        description: '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.

          '
        schema:
          type: string
          pattern: ^[0-9]+$
        example: '1234567890123456'
      - name: message_id
        in: query
        required: false
        description: 'Filter results by specific WhatsApp message ID (WAMID). When provided,

          only message history for this specific message will be returned.

          '
        schema:
          type: string
        example: wamid.HBgLMTY0NzM3Nzc3NzUVAgARGBI5QTNEQTA2RjdGMEY4RTRGAA==
      - name: fields
        in: query
        required: false
        description: '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}

          '
        schema:
          type: string
        example: id,message_id,events{delivery_status,timestamp,webhook_update_state}
      - name: limit
        in: query
        required: false
        description: 'Maximum number of message history entries to return per page.

          Default is 25, maximum is 100.

          '
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
        example: 25
      - name: after
        in: query
        required: false
        description: 'Cursor for pagination. Use this to get the next page of results.

          This value comes from the `paging.cursors.after` field in previous responses.

          '
        schema:
          type: string
        example: MTAxNTExOTQ1MjAwNzI5NDE=
      - name: before
        in: query
        required: false
        description: 'Cursor for pagination. Use this to get the previous page of results.

          This value comes from the `paging.cursors.before` field in previous responses.

          '
        schema:
          type: string
        example: MAZDZD
      responses:
        '200':
          description: Successfully retrieved WhatsApp Business Account message history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageHistoryResponse'
              examples:
                message_history_with_events:
                  summary: Message history with delivery status events
                  value:
                    data:
                    - id: '1234567890123456'
                      message_id: wamid.HBgLMTY0NzM3Nzc3NzUVAgARGBI5QTNEQTA2RjdGMEY4RTRGAA==
                      events:
                        data:
                        - id: '2345678901234567'
                          delivery_status: SENT
                          timestamp: 1640995200
                          webhook_update_state: DELIVERED
                          application:
                            id: '9876543210987654'
                          webhook_uri: https://example.com/webhook
                        - id: '3456789012345678'
                          delivery_status: DELIVERED
                          timestamp: 1640995260
                          webhook_update_state: DELIVERED
                          application:
                            id: '9876543210987654'
                          webhook_uri: https://example.com/webhook
                    - id: '4567890123456789'
                      message_id: wamid.HBgLMTY0NzM3Nzc3NzUVAgARGBI5QTNEQTA2RjdGMEY4RTJHAA==
                      events:
                        data:
                        - id: '5678901234567890'
                          delivery_status: READ
                          timestamp: 1640995320
                          webhook_update_state: DELIVERED
                          application:
                            id: '9876543210987654'
                          webhook_uri: https://example.com/webhook
                    paging:
                      cursors:
                        after: MTAxNTExOTQ1MjAwNzI5NDE=
                        before: MAZDZD
                      next: https://graph.facebook.com/v23.0/1234567890123456/message_history?after=MTAxNTExOTQ1MjAwNzI5NDE=
                filtered_by_message_id:
                  summary: Message history filtered by specific message ID
                  value:
                    data:
                    - id: '1234567890123456'
                      message_id: wamid.HBgLMTY0NzM3Nzc3NzUVAgARGBI5QTNEQTA2RjdGMEY4RTRGAA==
                      events:
                        data:
                        - id: '2345678901234567'
                          delivery_status: SENT
                          timestamp: 1640995200
                          webhook_update_state: DELIVERED
                        - id: '3456789012345678'
                          delivery_status: DELIVERED
                          timestamp: 1640995260
                          webhook_update_state: DELIVERED
                        - id: '4567890123456789'
                          delivery_status: READ
                          timestamp: 1640995320
                          webhook_update_state: DELIVERED
        '400':
          description: Bad Request - Invalid parameters or malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: 'Invalid parameter: message_id format is invalid'
                  type: OAuthException
                  code: 100
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '401':
          description: Unauthorized - Invalid or missing access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Invalid OAuth access token
                  type: OAuthException
                  code: 190
                  error_subcode: 463
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '403':
          description: Forbidden - Insufficient permissions or access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Your app doesn't have permission to access message history for this phone number
                  type: OAuthException
                  code: 200
                  error_subcode: 1349174
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  error_user_title: Permission Denied
                  error_user_msg: Your app doesn't have permission to access this resource
        '404':
          description: Not Found - Phone number ID does not exist or is not accessible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: WhatsApp Business Account phone number not found
                  type: GraphMethodException
                  code: 803
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '422':
          description: Unprocessable Entity - Request parameters are valid but cannot be processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: The requested message_id was not found in the message history
                  type: GraphMethodException
                  code: 100
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: Application request limit reached
                  type: OAuthException
                  code: 4
                  error_subcode: 2446079
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  is_transient: true
        '500':
          description: Internal Server Error - Unexpected server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphAPIError'
              example:
                error:
                  message: An unexpected error occurred. Please retry your request
                  type: GraphMethodException
                  code: 2
                  fbtrace_id: AXsgnV2Cm3ZMGF3dF_cfYIn
                  is_transient: true
      security:
      - bearerAuth: []
components:
  parameters:
    Authorization:
      name: Authorization
      in: header
      description: 'Bearer token for API authentication. This should be a valid access token obtained through the appropriate OAuth flow or system user token.

        '
      required: true
      schema:
        type: string
        pattern: ^Bearer\s+[A-Za-z0-9\-_.]+.*$
        example: Bearer EAABwzLixnjYBOzYmNMJJGfHq9DgNh...
    UserAgent:
      name: User-Agent
      in: header
      description: The user agent string identifying the client software making the request.
      required: false
      schema:
        type: string
        default: Meta-Business-Messaging-OpenAPI/1.0.0;spec=2025-10-21
        pattern: ^[a-zA-Z0-9\-_]+\/[0-9]+\.[0-9]+\.[0-9]+(;[a-zA-Z0-9\-=\.]+)?(\s+[a-zA-Z0-9\-_]+\/[0-9\-\.]+)?$
        example: Meta-Business-Messaging-OpenAPI/1.0.0;spec=2025-10-21
  schemas:
    WhatsAppMessageHistory:
      type: object
      description: WhatsApp message history entry with delivery status information
      required:
      - id
      - message_id
      properties:
        id:
          type: string
          description: Unique identifier for the message history entry
          example: '1234567890123456'
        message_id:
          type: string
          description: WhatsApp message ID (WAMID) for the message
          example: wamid.HBgLMTY0NzM3Nzc3NzUVAgARGBI5QTNEQTA2RjdGMEY4RTRGAA==
        events:
          type: object
          description: Message delivery status events and occurrences
          properties:
            data:
              type: array
              description: Array of delivery status events
              items:
                $ref: '#/components/schemas/MessageDeliveryStatusEvent'
            paging:
              $ref: '#/components/schemas/PaginationInfo'
    GraphAPIError:
      type: object
      description: Standard Graph API error response
      required:
      - error
      properties:
        error:
          type: object
          required:
          - message
          - type
          - code
          properties:
            message:
              type: string
              description: Human-readable error message
              example: Invalid parameter
            type:
              type: string
              description: Error category type
              example: OAuthException
            code:
              type: integer
              description: Numeric error code
              example: 100
            error_subcode:
              type: integer
              description: More specific error subcode when available
              example: 33
            fbtrace_id:
              type: string
              description: Unique identifier for debugging and support requests with Meta
              example: AXsgnV2Cm3ZMGF3dF_cfYIn
            is_transient:
              type: boolean
              description: Indicates whether this error is temporary and the request should be retried
              example: false
            error_user_title:
              type: string
              description: User-friendly error title for display purposes
              example: Permission Denied
            error_user_msg:
              type: string
              description: User-friendly error message for display purposes
              example: Your app doesn't have permission to access this resource
    WebhookUpdateState:
      type: string
      description: State of webhook update delivery
      enum:
      - PENDING
      - DELIVERED
      - FAILED
      - RETRYING
      example: DELIVERED
    MessageDeliveryStatusEvent:
      type: object
      description: Message delivery status event occurrence
      required:
      - id
      - delivery_status
      - timestamp
      properties:
        id:
          type: string
          description: Unique identifier for the delivery status event
          example: '2345678901234567'
        delivery_status:
          $ref: '#/components/schemas/WhatsAppMessageDeliveryStatus'
        webhook_update_state:
          $ref: '#/components/schemas/WebhookUpdateState'
        timestamp:
          type: integer
          format: int64
          description: Unix timestamp when the delivery status event occurred
          example: 1640995200
        application:
          type: object
          description: Application information for the event
          properties:
            id:
              type: string
              description: Application ID that processed the event
              example: '9876543210987654'
        webhook_uri:
          type: string
          format: uri
          description: Webhook URI where the event was delivered
          example: https://example.com/webhook
        error_description:
          type: string
          description: Error description if the delivery failed
          example: Webhook endpoint returned HTTP 500
    WhatsAppMessageDeliveryStatus:
      type: string
      description: Message delivery status
      enum:
      - SENT
      - DELIVERED
      - READ
      - FAILED
      - DELETED
      example: DELIVERED
    MessageHistoryResponse:
      type: object
      description: Paginated response containing message history entries
      properties:
        data:
          type: array
          description: Array of message history entries
          items:
            $ref: '#/components/schemas/WhatsAppMessageHistory'
        paging:
          $ref: '#/components/schemas/PaginationInfo'
    PaginationInfo:
      type: object
      description: Pagination information for navigating through results
      properties:
        cursors:
          type: object
          description: Pagination cursors for navigation
          properties:
            before:
              type: string
              description: Cursor for the previous page of results
              example: MAZDZD
            after:
              type: string
              description: Cursor for the next page of results
              example: MTAxNTExOTQ1MjAwNzI5NDE=
        previous:
          type: string
          format: uri
          description: URL for the previous page of results
          example: https://graph.facebook.com/v23.0/1234567890123456/message_history?before=MAZDZD
        next:
          type: string
          format: uri
          description: URL for the next page of results
          example: https://graph.facebook.com/v23.0/1234567890123456/message_history?after=MTAxNTExOTQ1MjAwNzI5NDE=
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'System user access token with whatsapp_business_management permission. Format: Bearer YOUR_SYSTEM_USER_ACCESS_TOKEN

        '