> ## 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 messages > Returns a paginated list of the WhatsApp messages your account sent and received, each with its direction, delivery status, and phone numbers. Messages that customers send to your senders appear here alongside the messages you sent. **Behavior:** Messages are ordered from newest to oldest. If `direction` isn't specified, the response includes both directions, and when several filters are specified, a message must match all of them. Returns `400` when `direction`, `from`, or `to` isn't valid. **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/messages 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: 1.1.1 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, and messages paths: /v1/whatsapp/messages: get: tags: - WhatsApp summary: List WhatsApp messages description: >- Returns a paginated list of the WhatsApp messages your account sent and received, each with its direction, delivery status, and phone numbers. Messages that customers send to your senders appear here alongside the messages you sent. **Behavior:** Messages are ordered from newest to oldest. If `direction` isn't specified, the response includes both directions, and when several filters are specified, a message must match all of them. Returns `400` when `direction`, `from`, or `to` isn't valid. **Requires:** Your account must have WhatsApp enabled, must have a subscription plan, and must not be blocked or suspended. operationId: whatsapp_messages_list parameters: - name: direction in: query required: false description: >- Filters messages by direction. Possible values: - `outbound` — The message was sent from your account to a recipient. - `inbound` — A customer sent the message to one of your senders. schema: type: string enum: - outbound - inbound example: outbound - name: status in: query required: false description: >- Filters messages by delivery status. Inbound messages always have `delivered` status. Possible values: - `sent` — The message isn't delivered yet. - `delivered` — The message was delivered to the recipient. - `undelivered` — The message was sent but not delivered. - `expired` — The message expired before it was delivered. - `rejected` — The message was permanently rejected before or by the provider. - `unknown` — The provider hasn't reported a status. schema: type: string enum: - sent - delivered - undelivered - expired - rejected - unknown example: delivered - name: from in: query required: false description: >- Filters messages by the `from` phone number, in E.164 format. The leading `+` is optional. schema: type: string pattern: ^\+?\d{6,20}$ example: '+14155550100' - name: to in: query required: false description: >- Filters messages by the `to` phone number, in E.164 format. The leading `+` is optional. schema: type: string pattern: ^\+?\d{6,20}$ example: '+447537151866' - name: from_date in: query required: false description: >- Filters messages to those created on or after the start of this date in your account's time zone, in `YYYY-MM-DD` format. schema: type: string format: date example: '2026-01-01' - name: to_date in: query required: false description: >- Filters messages to those created on or before the end of this date in your account's time zone, in `YYYY-MM-DD` format. schema: type: string format: date example: '2026-01-31' - $ref: '#/components/parameters/WhatsAppPageParam' - $ref: '#/components/parameters/WhatsAppPerPageParam' responses: '200': description: A paginated list of WhatsApp messages. content: application/json: schema: $ref: '#/components/schemas/WhatsAppMessageListResponse' examples: default: summary: One outbound and one inbound message value: messages: - uuid: 9d4e1c7a-2b86-4f3d-b5a0-71e8c3f6a924 direction: inbound status: delivered from: '+447537151866' to: '+14155550100' country: GB created_at: '2026-01-15T10:45:00.456Z' - uuid: 3a525ca2-6909-4c72-9399-905adf7f3a74 direction: outbound status: delivered from: '+14155550100' to: '+447537151866' country: GB created_at: '2026-01-15T10:30:00.123Z' pagination: current_page: 1 per_page: 25 total: 2 total_pages: 1 '400': $ref: '#/components/responses/WhatsAppBadRequestResponse' '401': $ref: '#/components/responses/WhatsAppUnauthorizedResponse' '403': $ref: '#/components/responses/WhatsAppForbiddenResponse' '404': $ref: '#/components/responses/WhatsAppChannelUnavailableResponse' '429': $ref: '#/components/responses/WhatsAppTooManyRequestsResponse' '500': $ref: '#/components/responses/WhatsAppInternalServerErrorResponse' '503': $ref: '#/components/responses/WhatsAppServiceUnavailableResponse' deprecated: false security: - bearerAuth: - whatsapp:read components: parameters: WhatsAppPageParam: name: page in: query description: Page number to retrieve. Page numbering starts at 1. Defaults to 1. schema: type: integer format: int32 default: 1 example: 1 WhatsAppPerPageParam: name: per_page in: query description: >- Number of records to return per page. Defaults to 25. Values above 100 are treated as 100. schema: type: integer format: int32 default: 25 example: 25 schemas: WhatsAppMessageListResponse: title: WhatsAppMessageListResponse description: Returned by `whatsapp_messages_list`. required: - messages - pagination type: object additionalProperties: false properties: messages: type: array description: Messages that match the request. items: $ref: '#/components/schemas/WhatsAppMessageListItem' pagination: $ref: '#/components/schemas/Pagination' WhatsAppMessageListItem: title: WhatsAppMessageListItem description: >- A WhatsApp message your account sent or received. Returned by `whatsapp_messages_list` and `whatsapp_messages_get`. required: - uuid - direction - status - created_at - from - to - country type: object additionalProperties: false properties: uuid: type: string format: uuid description: ID of the message. example: 3a525ca2-6909-4c72-9399-905adf7f3a74 direction: type: string description: >- Message direction. Possible values: - `outbound` — The message was sent from your account to a recipient. - `inbound` — A customer sent the message to one of your senders. enum: - outbound - inbound example: outbound status: type: string description: >- Message delivery status. Inbound messages always have `delivered` status. Possible values: - `sent` — The message isn't delivered yet. - `delivered` — The message was delivered to the recipient. - `undelivered` — The message was sent but not delivered. - `expired` — The message expired before it was delivered. - `rejected` — The message was permanently rejected before or by the provider. - `unknown` — The provider hasn't reported a status. enum: - sent - delivered - undelivered - expired - rejected - unknown example: delivered from: type: string description: >- For `outbound` messages, the phone number of your sender. For `inbound`, the customer's phone number. example: '+14155550100' to: type: string description: >- For `outbound` messages, the recipient's phone number. For `inbound`, the phone number of your sender that received it. example: '+447537151866' country: type: - string - 'null' description: >- Country of the customer's phone number, as an ISO 3166-1 alpha-2 code, or `null` if the country can't be determined from the number. example: GB created_at: type: string format: date-time description: Date and time the message was created, in ISO 8601 format. example: '2026-01-15T10:30:00.123Z' Pagination: title: Pagination required: - current_page - per_page - total - total_pages type: object additionalProperties: false properties: current_page: type: integer description: Current page number. format: int32 example: 2 per_page: type: integer description: Number of records per page. format: int32 example: 25 total: type: integer description: Total number of records. format: int32 example: 101 total_pages: type: integer description: Total number of pages. format: int32 example: 5 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://wavix.com/problems/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 the `WAVIX_` prefix. example: WAVIX_WHATSAPP_NOT_AVAILABLE responses: WhatsAppBadRequestResponse: description: >- The `direction`, `from`, or `to` query parameter is invalid. The `detail` field says which one. headers: {} content: application/problem+json: schema: $ref: '#/components/schemas/WhatsAppProblem' examples: invalid-request: value: type: https://wavix.com/problems/invalid-request title: Invalid Request status: 400 detail: direction must be inbound or outbound instance: 3a525ca2-6909-4c72-9399-905adf7f3a74 error_class: permanent error_code: WAVIX_INVALID_REQUEST WhatsAppUnauthorizedResponse: description: Authentication failed or wasn't provided. 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://wavix.com/problems/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: WAVIX_AUTHENTICATION_REQUIRED WhatsAppForbiddenResponse: description: >- Returns when the account is suspended, blocked, or has no subscription plan, or the API key has no access to the endpoint. headers: {} content: application/problem+json: schema: $ref: '#/components/schemas/WhatsAppProblem' examples: account-suspended: value: type: https://wavix.com/problems/access-denied title: Access Denied status: 403 detail: The account is suspended. instance: 3a525ca2-6909-4c72-9399-905adf7f3a74 error_class: permanent error_code: WAVIX_ACCESS_DENIED access-denied: value: type: https://wavix.com/problems/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: WAVIX_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://wavix.com/problems/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: WAVIX_WHATSAPP_NOT_AVAILABLE channel-not-enabled: summary: WhatsApp is not enabled yet for this account value: type: https://wavix.com/problems/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: WAVIX_CHANNEL_NOT_ENABLED WhatsAppTooManyRequestsResponse: description: Returns when the account has exceeded its request rate limit. headers: Retry-After: description: Number of seconds to wait before retrying the request. schema: type: integer example: 30 content: application/problem+json: schema: $ref: '#/components/schemas/WhatsAppProblem' examples: rate-limited: value: type: https://wavix.com/problems/rate-limited title: Rate Limited status: 429 detail: Too many requests. Try again later. instance: 3a525ca2-6909-4c72-9399-905adf7f3a74 error_class: rate_limited error_code: WAVIX_RATE_LIMITED 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://wavix.com/problems/internal-error title: Internal Error status: 500 detail: Internal Error instance: 3a525ca2-6909-4c72-9399-905adf7f3a74 error_class: retriable error_code: WAVIX_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://wavix.com/problems/service-unavailable title: Service Unavailable status: 503 detail: The service is temporarily unavailable. instance: 3a525ca2-6909-4c72-9399-905adf7f3a74 error_class: retriable error_code: WAVIX_SERVICE_UNAVAILABLE provider-unavailable: value: type: https://wavix.com/problems/provider-unavailable title: Provider Unavailable status: 503 detail: The provider is temporarily unavailable. instance: 3a525ca2-6909-4c72-9399-905adf7f3a74 error_class: retriable error_code: WAVIX_PROVIDER_UNAVAILABLE securitySchemes: bearerAuth: type: http scheme: bearer description: > Wavix API key. Pass as `Authorization: Bearer `. 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.