---
title: "List messages across all accounts"
method: GET
path: "/v1/messages"
tags: ["Messages"]
---

# List messages across all accounts

`GET /v1/messages`

## Request

- Base URL: `https://api.whatsmcp.com`
- URL: `https://api.whatsmcp.com/v1/messages`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Messages across all your accounts, oldest first. Poll with after_cursor = the last next_cursor you received to get only what has arrived since — no gaps, no duplicates. Filter with account_id, chat and since/until (when the message was sent; until is exclusive); include_history adds synced history. Mirrors the wa_list_messages MCP tool.

## Query parameters

- `after_cursor` integer: return messages after this cursor; omit or 0 to start from the beginning
- `limit` integer: how many to return, 1-200; omit or 0 for 50
- `account_id` string: only this account's messages; omit for every account
- `chat` string: only this conversation — a phone number or a group JID
- `since` string: only messages sent at or after this time: RFC3339 with a zone, or a date (midnight UTC)
- `until` string: only messages sent BEFORE this time (exclusive): one day is since=2026-10-01&until=2026-10-02
- `include_history` boolean: also return imported history; a page is then in storage order — sort by at

## Response `200`

OK

- ListMessagesOutput
  - `account_notices` AccountNotice[], nullable: present when a number this read covers is not working: new messages are not arriving on it; says why and what to do
    - `account_id` string, required: the account this notice is about
    - `message` string, required: what is wrong and what to do; tell the user
    - `since` string: when it stopped working, RFC3339, when known
    - `status` string, required: why it is not live: starting, not_running, whatsapp_down, suspended, pairing, unlinked or locked
    - `status_reason` string: the detail, e.g. no_egress, no_plan, stopped
  - `has_more` boolean, required: true when the page was full and more may be waiting
  - `messages` MessageView[], nullable, required: messages in order, oldest first
    - `account_id` string, required: which of your accounts this message belongs to
    - `account_name` string: the WhatsApp display name of that account
    - `account_phone` string: the phone number of your account this message was sent from or received on, E.164
    - `at` string, required: when the message was sent, RFC3339
    - `attachment` AttachmentView
      - `available` boolean, required: true when the file should be fetchable with wa_get_media(account_id, message_id) — a live received attachment; false for history and for files you sent, which are not kept
      - `file_name` string: documents only: the file name the sender gave it
      - `mime` string: the attachment's mime type as the sender declared it, e.g. image/jpeg or application/pdf; empty for a message stored before this was recorded
      - `size` integer: the attachment's size in bytes as the sender declared it; 0 when unknown
    - `chat` string: the conversation JID; pass it to wa_send_message's 'to' to reply here — a group is …@g.us, a channel …@newsletter
    - `chat_kind` string: dm, group, channel or broadcast
    - `cursor` integer, required: pass the highest cursor you have seen back as after_cursor to continue
    - `direction` string, required: inbound (received) or outbound (sent by you)
    - `imported` boolean: true for a message loaded as history (pairing sync or wa_load_history) rather than received live
    - `kind` string, required: what the message is: text, image, video, audio, document, sticker, reaction, location, live_location, contact, poll, poll_vote, video_note, album, event, comment, pin, group_invite, template or call_permission; other is a type this server does not classify. text carries a body, and so do image/video/document captions, template text and a call_permission request or answer; an image, video, audio, document or sticker attachment can be fetched with wa_get_media
    - `message_id` string, required: WhatsApp's id for this message
    - `peer` string, required: the other party's phone number (for a group/channel this is the individual SENDER; use chat to reply)
    - `received_at` string: when this server received and stored the message, RFC3339; later than at for a message delivered late or loaded as history
    - `send_error` string: set on an outbound message that failed to send
    - `sender_name` string: who wrote the message, by name: for inbound the sender's name as saved in this account's contacts, or else the name they chose for themselves; for outbound this account's own WhatsApp name. Empty when no name is known
    - `status` string: delivery status of an outbound message from the provider's receipts: sent, delivered, read or failed; empty when no receipt has arrived (or for inbound). Only Business (Cloud API) numbers report this today
    - `text` string, required: the message body
  - `next_cursor` integer, required: pass this as after_cursor next time to get only newer messages
  - `refusal` Refusal
    - `account_status` string: when the number is not working: its status — starting, not_running, whatsapp_down, suspended, pairing, unlinked or locked
    - `account_status_reason` string: the detail of account_status, e.g. no_egress, stopped, no_plan
    - `message` string, required: a human-readable explanation
    - `reason` string, required: why the call was declined
    - `refused` boolean, required: true when the call was declined rather than performed
    - `retry_after_seconds` integer: seconds to wait before retrying; absent or 0 means retrying will not help
    - `since` string: when the number stopped working, RFC3339, when known

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `422`: Unprocessable Entity
- `500`: Internal Server Error

---

[API](https://skmtc.dev/whatsmcp/apis/whatsmcp-api.md) · [All operations](https://skmtc.dev/whatsmcp/apis/whatsmcp-api/llms.txt) · [OpenAPI document](https://skmtc.dev/whatsmcp/apis/whatsmcp-api/revisions/719dc99224ce?raw)