> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wavix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List WhatsApp events

> Returns a paginated list of your account's WhatsApp events, the same events Wavix posts to your webhooks, oldest first.

Read events here when your server can't receive webhooks, or to catch up on events your webhooks missed. Events are recorded even when your account has no webhook for their group.

**Behavior:** Events are ordered by when Wavix recorded them, oldest first, which can differ from `timestamp`. To read them all, pass `next_cursor` from each page as `after` until `has_more` is `false`; later, pass the last non-null `next_cursor` again, or no `after` if you have none, to get events recorded since. Events are kept for 30 days, and test events never appear. When both `type` and `group` are specified, an event must match both filters.

**Requires:** Your account must have WhatsApp enabled, must have a subscription plan, and must not be blocked or suspended.



## OpenAPI

````yaml https://wavix.github.io/wavix-openapi/wavix-api.yaml get /v1/whatsapp/events
openapi: 3.1.0
info:
  title: Wavix APIs
  description: >-
    Wavix provides robust APIs that let you integrate voice and text messaging
    features directly into your app. Send text, place calls, and access detailed
    reports  programmatically.
  termsOfService: https://wavix.com/terms-and-conditions
  license:
    name: MIT
    identifier: MIT
  contact:
    name: Wavix
    url: https://wavix.com
    email: support@wavix.com
  version: 2.0.0
servers:
  - url: https://api.wavix.com
    description: https://api.wavix.com
    variables: {}
security:
  - bearerAuth: []
tags:
  - name: SIP trunks
    description: SIP trunks
  - name: Buy
    description: Numbers
  - name: Cart
    description: Numbers
  - name: My numbers
    description: Numbers
  - name: Billing
    description: Billing, transactions, and invoices
  - name: Profile
    description: Account profile and customer information
  - name: CDRs
    description: Call detail records and call history
  - name: Speech Analytics
    description: Call transcription and speech analytics
  - name: SMS and MMS
    description: Messaging
  - name: Number Validator
    description: Phone number validation
  - name: Link shortener
    description: Short link and click metrics
  - name: 2FA
    description: Two-factor authentication
  - name: 10DLC
    description: 10DLC Campaigns and Brands
  - name: API Keys
    description: API key management
  - name: Call webhooks
    description: Webhook configuration for call events
  - name: Call control
    description: Programmable Voice
  - name: Call streaming
    description: Real-time call audio streaming over WebSocket
  - name: Call recording
    description: Call recording
  - name: Sub-accounts
    description: Sub-account management
  - name: Voice campaigns
    description: Outbound voice campaigns
  - name: Wavix Embeddable
    description: WebRTC embeddable widget
  - name: WhatsApp
    description: WhatsApp senders, templates, messages, webhooks, and events
  - name: WhatsApp webhook payloads
    description: >-
      Message, template, sender, and marketing preference events Wavix posts to
      your WhatsApp webhooks
paths:
  /v1/whatsapp/events:
    get:
      tags:
        - WhatsApp
      summary: List WhatsApp events
      description: >-
        Returns a paginated list of your account's WhatsApp events, the same
        events Wavix posts to your webhooks, oldest first.


        Read events here when your server can't receive webhooks, or to catch up
        on events your webhooks missed. Events are recorded even when your
        account has no webhook for their group.


        **Behavior:** Events are ordered by when Wavix recorded them, oldest
        first, which can differ from `timestamp`. To read them all, pass
        `next_cursor` from each page as `after` until `has_more` is `false`;
        later, pass the last non-null `next_cursor` again, or no `after` if you
        have none, to get events recorded since. Events are kept for 30 days,
        and test events never appear. When both `type` and `group` are
        specified, an event must match both filters.


        **Requires:** Your account must have WhatsApp enabled, must have a
        subscription plan, and must not be blocked or suspended.
      operationId: whatsapp_events_list
      parameters:
        - name: type
          in: query
          required: false
          description: Filters events by type.
          schema:
            $ref: '#/components/schemas/WhatsAppEventType'
          example: whatsapp.message.received
        - name: group
          in: query
          required: false
          description: Filters events by the webhook group their type belongs to.
          schema:
            $ref: '#/components/schemas/WhatsAppWebhookGroup'
          example: messages
        - name: after
          in: query
          required: false
          description: >-
            Returns only events recorded after the event with this ID. Pass
            `next_cursor` from the previous page. Without it, the list starts at
            the oldest event kept.
          schema:
            type: string
            pattern: ^evt_[0-9a-f]{32}$
          example: evt_8a1d3c5e7f9b4d2a6c8e0f1a3b5c7d9e
        - name: limit
          in: query
          required: false
          description: Maximum number of events to return. Defaults to 25.
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 25
          example: 25
      responses:
        '200':
          description: A paginated list of WhatsApp events, oldest first.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WhatsAppEventListResponse'
              examples:
                default:
                  summary: A received message and a delivered message
                  value:
                    events:
                      - id: evt_8a1d3c5e7f9b4d2a6c8e0f1a3b5c7d9e
                        type: whatsapp.message.received
                        timestamp: '2026-10-21T08:30:00.123456Z'
                        data:
                          message_uuid: 9d4e1c7a-2b86-4f3d-b5a0-71e8c3f6a924
                          from: '+447537151866'
                          to: '+14155550100'
                          profile_name: Jane Smith
                          content:
                            type: button_reply
                            button_reply:
                              id: confirm-order-1001
                              title: Confirm
                          context:
                            message_uuid: 3a525ca2-6909-4c72-9399-905adf7f3a74
                          referral: null
                          service_window_open_until: '2026-10-22T08:30:00Z'
                      - id: evt_1b3d5f7a9c2e4b6d8f0a1c3e5b7d9f2a
                        type: whatsapp.message.delivered
                        timestamp: '2026-10-21T08:31:05.000000Z'
                        data:
                          message_uuid: 3a525ca2-6909-4c72-9399-905adf7f3a74
                          from: '+14155550100'
                          to: '+447537151866'
                          template:
                            name: order_shipped
                            language: en_US
                    next_cursor: evt_1b3d5f7a9c2e4b6d8f0a1c3e5b7d9f2a
                    has_more: false
                caught-up:
                  summary: No events since the cursor
                  value:
                    events: []
                    next_cursor: null
                    has_more: false
        '400':
          description: >-
            A query parameter is invalid. A parameter is empty or repeated,
            `type` or `group` has an unsupported value, `limit` isn't an integer
            from 1 to 100, or `after` isn't an event ID or isn't an event of
            your account that's still kept. For an `after` that's no longer
            kept, start again without `after` and discard events you already
            handled by `id`. The `detail` field says which.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/WhatsAppProblem'
              examples:
                invalid-request:
                  summary: The cursor isn't a kept event of your account
                  value:
                    type: https://docs.wavix.com/errors/invalid-request
                    title: Invalid Request
                    status: 400
                    detail: 'after: event not found'
                    instance: 3a525ca2-6909-4c72-9399-905adf7f3a74
                    error_class: permanent
                    error_code: INVALID_REQUEST
        '401':
          $ref: '#/components/responses/WhatsAppUnauthorizedResponse'
        '403':
          $ref: '#/components/responses/WhatsAppForbiddenResponse'
        '404':
          $ref: '#/components/responses/WhatsAppChannelUnavailableResponse'
        '500':
          $ref: '#/components/responses/WhatsAppInternalServerErrorResponse'
        '503':
          $ref: '#/components/responses/WhatsAppServiceUnavailableResponse'
      deprecated: false
      security:
        - bearerAuth:
            - whatsapp:read
components:
  schemas:
    WhatsAppEventType:
      title: WhatsAppEventType
      description: >-
        Type of a WhatsApp event. Each type belongs to one webhook group. Wavix
        can add event types to a group, so ignore an event whose `type` you
        don't recognize. Possible values:


        - `whatsapp.message.received` — One of your senders received a message.

        - `whatsapp.message.sent` — A message you sent has the `sent` status: it
        isn't delivered yet.

        - `whatsapp.message.delivered` — A message you sent was delivered to the
        recipient. WhatsApp can skip it when the recipient reads the message
        right away.

        - `whatsapp.message.read` — The recipient opened a message you sent.
        WhatsApp reports it only when the recipient has read receipts turned on.

        - `whatsapp.message.failed` — A message you sent wasn't delivered.
        `data.error` says why.

        - `whatsapp.contact.marketing_stopped` — A contact asked to stop
        marketing messages from one of your senders. Meta doesn't deliver
        marketing templates to the contact until they resume them.

        - `whatsapp.contact.marketing_resumed` — A contact asked to receive
        marketing messages from one of your senders again.

        - `whatsapp.template.approved` — The provider approved one of your
        templates, so you can send it.

        - `whatsapp.template.rejected` — The provider rejected one of your
        templates.

        - `whatsapp.template.paused` — The provider paused one of your
        templates.

        - `whatsapp.template.disabled` — One of your templates is disabled and
        can't be sent.

        - `whatsapp.template.flagged` — Meta flagged one of your templates
        because of negative feedback. It can still be sent, but it's at risk of
        being paused or disabled.

        - `whatsapp.template.category_changed` — Meta moved one of your
        templates to another category, which changes the rate of each message
        sent with it.

        - `whatsapp.template.quality_changed` — Meta changed the quality rating
        of one of your templates.

        - `whatsapp.template.updated` — The status of one of your templates
        changed to a value that has no event type of its own, such as `pending`,
        `in_appeal`, or `deleted`.

        - `whatsapp.sender.connected` — One of your senders can send messages
        within its messaging limit, for example after registration or when a
        restriction ends.

        - `whatsapp.sender.restricted` — One of your senders reached its
        messaging limit. It can't start new conversations until the 24-hour
        window resets, but it can still reply to customers who messaged it.

        - `whatsapp.sender.flagged` — The quality rating of one of your senders
        dropped to low. The status returns to `connected` if the rating returns
        to medium or high within 7 days.

        - `whatsapp.sender.banned` — The provider banned one of your senders.

        - `whatsapp.sender.disconnected` — One of your senders is disconnected
        from the provider.

        - `whatsapp.sender.quality_changed` — Meta changed the quality rating of
        one of your senders.

        - `whatsapp.sender.updated` — The status of one of your senders changed
        to a value that has no event type of its own, such as `pending`,
        `migrated`, or `deleted`.
      type: string
      enum:
        - whatsapp.message.received
        - whatsapp.message.sent
        - whatsapp.message.delivered
        - whatsapp.message.read
        - whatsapp.message.failed
        - whatsapp.contact.marketing_stopped
        - whatsapp.contact.marketing_resumed
        - whatsapp.template.approved
        - whatsapp.template.rejected
        - whatsapp.template.paused
        - whatsapp.template.disabled
        - whatsapp.template.flagged
        - whatsapp.template.category_changed
        - whatsapp.template.quality_changed
        - whatsapp.template.updated
        - whatsapp.sender.connected
        - whatsapp.sender.restricted
        - whatsapp.sender.flagged
        - whatsapp.sender.banned
        - whatsapp.sender.disconnected
        - whatsapp.sender.quality_changed
        - whatsapp.sender.updated
      example: whatsapp.message.received
    WhatsAppWebhookGroup:
      title: WhatsAppWebhookGroup
      description: >-
        Group of WhatsApp event types that a webhook receives. Your account can
        have one webhook per group. Possible values:


        - `messages` — Messages your senders receive, the delivery outcome of
        messages you send, and contacts' marketing preferences.

        - `templates` — Changes to the status, category, and quality rating of
        your templates.

        - `senders` — Changes to the status and quality rating of your senders.
      type: string
      enum:
        - messages
        - templates
        - senders
      example: messages
    WhatsAppEventListResponse:
      title: WhatsAppEventListResponse
      description: >-
        A paginated list of your account's WhatsApp events, returned by [List
        WhatsApp
        events](https://docs.wavix.com/api-reference/whatsapp/list-whatsapp-events).
      type: object
      additionalProperties: false
      required:
        - events
        - next_cursor
        - has_more
      properties:
        events:
          type: array
          description: >-
            Events in the order Wavix recorded them, oldest first. Empty when no
            event matches.
          items:
            $ref: '#/components/schemas/WhatsAppEvent'
        next_cursor:
          type:
            - string
            - 'null'
          description: >-
            ID of the last event on this page. Pass it as `after` to get the
            events that follow. Null when the page is empty; keep the cursor you
            have, or omit `after` if you have none.
          example: evt_1b3d5f7a9c2e4b6d8f0a1c3e5b7d9f2a
        has_more:
          type: boolean
          description: >-
            `true` when more events follow this page right now. `false` means
            you've caught up; events recorded later appear after the same
            cursor.
          example: false
    WhatsAppProblem:
      title: WhatsAppProblem
      description: >-
        An RFC 9457 problem document that describes an error from the WhatsApp
        API. Returned with the `application/problem+json` content type.
      required:
        - type
        - title
        - status
        - detail
        - instance
      type: object
      additionalProperties: false
      properties:
        type:
          type: string
          description: URI that identifies the problem type.
          example: https://docs.wavix.com/errors/whatsapp-not-available
        title:
          type: string
          description: Short, human-readable summary of the problem type.
          example: WhatsApp Not Available
        status:
          type: integer
          format: int32
          description: HTTP status code of the response.
          example: 404
        detail:
          type: string
          description: Human-readable explanation of this occurrence of the problem.
          example: WhatsApp is not available for this account.
        instance:
          type: string
          description: Request ID of this occurrence of the problem.
          example: 3a525ca2-6909-4c72-9399-905adf7f3a74
        error_class:
          type: string
          description: >-
            Machine-readable classification of the error. Possible values:


            - `permanent` — The request can't succeed as sent. Retrying doesn't
            help.

            - `retriable` — The failure is temporary. Retrying can succeed.

            - `rate_limited` — The request was rate limited. Retry later.

            - `invalid_template` — The template content is invalid.
          enum:
            - permanent
            - retriable
            - rate_limited
            - invalid_template
          example: permanent
        error_code:
          type: string
          description: >-
            Stable machine-readable error code. It's the problem type slug in
            upper case, with underscores in place of hyphens.
          example: WHATSAPP_NOT_AVAILABLE
        service_window_closed_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            Time the 24-hour service window of the recipient closed. Returned
            with `service-window-closed`. It's `null` when the recipient never
            wrote to the sender or the last message is older than the retained
            history.
          example: '2026-01-14T09:15:00.000Z'
    WhatsAppEvent:
      title: WhatsAppEvent
      description: >-
        A WhatsApp event returned by [List WhatsApp
        events](https://docs.wavix.com/api-reference/whatsapp/list-whatsapp-events).
        It has the same fields as the event Wavix posts to your webhook, and
        `type` decides the shape of `data`.
      type: object
      additionalProperties: false
      required:
        - id
        - type
        - timestamp
        - data
      properties:
        id:
          type: string
          pattern: ^evt_[0-9a-f]{32}$
          description: >-
            Unique ID of the event. It's the same in the event list and in the
            webhook request, so use it to discard events you already handled.
          example: evt_8a1d3c5e7f9b4d2a6c8e0f1a3b5c7d9e
        type:
          type: string
          description: >-
            Type of the event, such as `whatsapp.message.received`. The `type`
            query parameter lists every type. Wavix can add event types, so
            ignore an event whose `type` you don't recognize.
          example: whatsapp.message.delivered
        timestamp:
          type: string
          format: date-time
          description: >-
            When the event happened, in ISO 8601 UTC with 6 fractional digits.
            The list is ordered by when Wavix recorded events, so `timestamp`
            can be out of order.
          example: '2026-10-21T08:30:00.123456Z'
        data:
          type: object
          additionalProperties: true
          description: >-
            Details of the event. The fields depend on `type` and are the same
            as `data` in the webhook request for that type.
          example:
            message_uuid: 3a525ca2-6909-4c72-9399-905adf7f3a74
            from: '+14155550100'
            to: '+447537151866'
            template:
              name: order_shipped
              language: en_US
  responses:
    WhatsAppUnauthorizedResponse:
      description: >-
        Authentication failed or wasn't provided, or the account is suspended,
        blocked, or has no subscription plan.
      headers: {}
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/WhatsAppProblem'
          examples:
            authentication-required:
              summary: The API key or token is missing or isn't valid
              value:
                type: https://docs.wavix.com/errors/authentication-required
                title: Authentication Required
                status: 401
                detail: Authentication is required to access this resource.
                instance: 3a525ca2-6909-4c72-9399-905adf7f3a74
                error_class: permanent
                error_code: AUTHENTICATION_REQUIRED
            account-suspended:
              summary: The account is suspended
              value:
                type: https://docs.wavix.com/errors/authentication-required
                title: Authentication Required
                status: 401
                detail: The account is suspended.
                instance: 3a525ca2-6909-4c72-9399-905adf7f3a74
                error_class: permanent
                error_code: AUTHENTICATION_REQUIRED
            account-blocked:
              summary: The account is blocked
              value:
                type: https://docs.wavix.com/errors/authentication-required
                title: Authentication Required
                status: 401
                detail: The account is blocked.
                instance: 3a525ca2-6909-4c72-9399-905adf7f3a74
                error_class: permanent
                error_code: AUTHENTICATION_REQUIRED
            account-without-plan:
              summary: The account has no subscription plan
              value:
                type: https://docs.wavix.com/errors/authentication-required
                title: Authentication Required
                status: 401
                detail: The account has no subscription plan.
                instance: 3a525ca2-6909-4c72-9399-905adf7f3a74
                error_class: permanent
                error_code: AUTHENTICATION_REQUIRED
    WhatsAppForbiddenResponse:
      description: >-
        Returns when the API key doesn't have the scope the operation needs, or
        the request isn't allowed for the account's region.
      headers: {}
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/WhatsAppProblem'
          examples:
            access-denied:
              value:
                type: https://docs.wavix.com/errors/access-denied
                title: Access Denied
                status: 403
                detail: The API key has no access to this resource.
                instance: 3a525ca2-6909-4c72-9399-905adf7f3a74
                error_class: permanent
                error_code: ACCESS_DENIED
    WhatsAppChannelUnavailableResponse:
      description: >-
        WhatsApp isn't available for your account, or the WhatsApp channel isn't
        enabled for it yet.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/WhatsAppProblem'
          examples:
            whatsapp-not-available:
              summary: WhatsApp is not available for this account
              value:
                type: https://docs.wavix.com/errors/whatsapp-not-available
                title: WhatsApp Not Available
                status: 404
                detail: WhatsApp is not available for this account.
                instance: 3a525ca2-6909-4c72-9399-905adf7f3a74
                error_class: permanent
                error_code: WHATSAPP_NOT_AVAILABLE
            channel-not-enabled:
              summary: WhatsApp is not enabled yet for this account
              value:
                type: https://docs.wavix.com/errors/channel-not-enabled
                title: Channel Not Enabled
                status: 404
                detail: The WhatsApp channel is not enabled for this account.
                instance: 3a525ca2-6909-4c72-9399-905adf7f3a74
                error_class: permanent
                error_code: CHANNEL_NOT_ENABLED
    WhatsAppInternalServerErrorResponse:
      description: >-
        Returns when an unexpected error occurs on the server; the request may
        be retried.
      headers: {}
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/WhatsAppProblem'
          examples:
            internal-error:
              value:
                type: https://docs.wavix.com/errors/internal-error
                title: Internal Error
                status: 500
                detail: Internal Error
                instance: 3a525ca2-6909-4c72-9399-905adf7f3a74
                error_class: retriable
                error_code: INTERNAL_ERROR
    WhatsAppServiceUnavailableResponse:
      description: >-
        Returns when the service is temporarily unavailable; the request may be
        retried.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/WhatsAppProblem'
          examples:
            service-unavailable:
              value:
                type: https://docs.wavix.com/errors/service-unavailable
                title: Service Unavailable
                status: 503
                detail: The service is temporarily unavailable.
                instance: 3a525ca2-6909-4c72-9399-905adf7f3a74
                error_class: retriable
                error_code: SERVICE_UNAVAILABLE
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >
        Wavix API key. Pass as `Authorization: Bearer <api_key>`. Keys support
        per-resource scopes (none / read / write). See [Restricted keys and
        scopes](https://docs.wavix.com/api-reference/authentication#restricted-keys-and-scopes).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.