# WhatsApp — how to use (mcp.ai)

Send and read WhatsApp messages, manage chats and contacts from your agent.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_whatsapp?ms=1781685480000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `whatsapp_list`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/whatsapp`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/whatsapp/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/whatsapp/chat/archive` — Change a chat's state. action: archive/unarchive, pin/unpin, mute/unmute. Requires chat_jid.
  - body: { chat_jid: string, duration_secs?: number, account?: string }
- `POST https://api.mcp.ai/api/whatsapp/chat/metadata` — Get metadata for a single chat (subject/name, archived/pinned/muted state, unread count, timestamps). Requires chat_jid.
  - body: { chat_jid: string, account?: string }
- `POST https://api.mcp.ai/api/whatsapp/chat/mute` — Change a chat's state. action: archive/unarchive, pin/unpin, mute/unmute. Requires chat_jid.
  - body: { chat_jid: string, duration_secs?: number, account?: string }
- `POST https://api.mcp.ai/api/whatsapp/chat/pin` — Change a chat's state. action: archive/unarchive, pin/unpin, mute/unmute. Requires chat_jid.
  - body: { chat_jid: string, duration_secs?: number, account?: string }
- `POST https://api.mcp.ai/api/whatsapp/chat/unarchive` — Change a chat's state. action: archive/unarchive, pin/unpin, mute/unmute. Requires chat_jid.
  - body: { chat_jid: string, duration_secs?: number, account?: string }
- `POST https://api.mcp.ai/api/whatsapp/chat/unmute` — Change a chat's state. action: archive/unarchive, pin/unpin, mute/unmute. Requires chat_jid.
  - body: { chat_jid: string, duration_secs?: number, account?: string }
- `POST https://api.mcp.ai/api/whatsapp/chat/unpin` — Change a chat's state. action: archive/unarchive, pin/unpin, mute/unmute. Requires chat_jid.
  - body: { chat_jid: string, duration_secs?: number, account?: string }
- `POST https://api.mcp.ai/api/whatsapp/chats` — List WhatsApp chats (individual + group). Sorted by most recent activity.
  - body: { limit?: number, archived?: boolean, account?: string }
- `POST https://api.mcp.ai/api/whatsapp/contacts/get` — Read WhatsApp contacts.
  - body: { query?: string, limit?: number, jid?: string, account?: string }
- `POST https://api.mcp.ai/api/whatsapp/contacts/list` — Read WhatsApp contacts.
  - body: { query?: string, limit?: number, jid?: string, account?: string }
- `POST https://api.mcp.ai/api/whatsapp/group/manage/create` — Group lifecycle/admin (the connected account must be a group admin for most actions).
  - body: { group_jid?: string, name?: string, description?: string, participants?: string[], link_action?: string, invite?: string, req_action?: string, users?: string[], account?: string }
- `POST https://api.mcp.ai/api/whatsapp/group/manage/invite/link` — Group lifecycle/admin (the connected account must be a group admin for most actions).
  - body: { group_jid?: string, name?: string, description?: string, participants?: string[], link_action?: string, invite?: string, req_action?: string, users?: string[], account?: string }
- `POST https://api.mcp.ai/api/whatsapp/group/manage/join` — Group lifecycle/admin (the connected account must be a group admin for most actions).
  - body: { group_jid?: string, name?: string, description?: string, participants?: string[], link_action?: string, invite?: string, req_action?: string, users?: string[], account?: string }
- `POST https://api.mcp.ai/api/whatsapp/group/manage/leave` — Group lifecycle/admin (the connected account must be a group admin for most actions).
  - body: { group_jid?: string, name?: string, description?: string, participants?: string[], link_action?: string, invite?: string, req_action?: string, users?: string[], account?: string }
- `POST https://api.mcp.ai/api/whatsapp/group/manage/requests` — Group lifecycle/admin (the connected account must be a group admin for most actions).
  - body: { group_jid?: string, name?: string, description?: string, participants?: string[], link_action?: string, invite?: string, req_action?: string, users?: string[], account?: string }
- `POST https://api.mcp.ai/api/whatsapp/group/manage/update` — Group lifecycle/admin (the connected account must be a group admin for most actions).
  - body: { group_jid?: string, name?: string, description?: string, participants?: string[], link_action?: string, invite?: string, req_action?: string, users?: string[], account?: string }
- `POST https://api.mcp.ai/api/whatsapp/group/members` — List the members of a WhatsApp group (live). Returns each participant's JID, phone, and admin/super-admin flag. Requires group_jid (…@g.us, from whatsapp_groups).
  - body: { group_jid: string, account?: string }
- `POST https://api.mcp.ai/api/whatsapp/group/participants/add` — Manage participants of a WhatsApp group (the connected account must be a group admin). action: 'remove' kicks members, 'promote' makes them admin, 'demote' removes admin, 'add' invites. Pass 1–50 phon
  - body: { group_jid: string, users: string[], account?: string }
- `POST https://api.mcp.ai/api/whatsapp/group/participants/demote` — Manage participants of a WhatsApp group (the connected account must be a group admin). action: 'remove' kicks members, 'promote' makes them admin, 'demote' removes admin, 'add' invites. Pass 1–50 phon
  - body: { group_jid: string, users: string[], account?: string }
- `POST https://api.mcp.ai/api/whatsapp/group/participants/promote` — Manage participants of a WhatsApp group (the connected account must be a group admin). action: 'remove' kicks members, 'promote' makes them admin, 'demote' removes admin, 'add' invites. Pass 1–50 phon
  - body: { group_jid: string, users: string[], account?: string }
- `POST https://api.mcp.ai/api/whatsapp/group/participants/remove` — Manage participants of a WhatsApp group (the connected account must be a group admin). action: 'remove' kicks members, 'promote' makes them admin, 'demote' removes admin, 'add' invites. Pass 1–50 phon
  - body: { group_jid: string, users: string[], account?: string }
- `POST https://api.mcp.ai/api/whatsapp/groups` — List WhatsApp groups the account belongs to — subject, jid, participants count, owner.
  - body: { account?: string }
- `POST https://api.mcp.ai/api/whatsapp/history/backfill` — Request OLDER messages for a chat from your phone (on-demand history sync), extending what whatsapp_messages can read. Returns { status, messages_added }:
  - body: { chat_jid: string, count?: number, requests?: number, account?: string }
- `POST https://api.mcp.ai/api/whatsapp/history/coverage` — Show how far back the LOCAL message archive reaches per chat (oldest_ts, newest_ts, message_count, status). Use it to find pagination boundaries for whatsapp_messages and to decide whether to pull mor
  - body: { query?: string, kind?: string, limit?: number, chat_jid?: string, account?: string }
- `POST https://api.mcp.ai/api/whatsapp/list/accounts` — List WhatsApp accounts paired to this install — wa_jid, phone, label, proxy on/off, status.
  - body: { account?: string }
- `POST https://api.mcp.ai/api/whatsapp/message/delete` — Manage a message you can act on.
  - body: { chat_jid: string, message_id: string, for_everyone?: boolean, to?: string, text?: string, account?: string, message_ids?: string[] }
- `POST https://api.mcp.ai/api/whatsapp/message/edit` — Manage a message you can act on.
  - body: { chat_jid: string, message_id: string, for_everyone?: boolean, to?: string, text?: string, account?: string, message_ids?: string[] }
- `POST https://api.mcp.ai/api/whatsapp/message/forward` — Manage a message you can act on.
  - body: { chat_jid: string, message_id: string, for_everyone?: boolean, to?: string, text?: string, account?: string, message_ids?: string[] }
- `POST https://api.mcp.ai/api/whatsapp/messages` — List messages in a chat from LOCAL history. Requires chat_jid (from whatsapp_chats). Paginate backwards by passing the oldest message's timestamp as `before` (ISO 8601); `after` pages forward; `order`
  - body: { chat_jid: string, before?: string, after?: string, since?: string, order?: string, limit?: number, account?: string }
- `POST https://api.mcp.ai/api/whatsapp/messages/write` — Mark messages as read in a chat. Requires chat_jid. Optional message_id (marks up to this message; omit to mark all unread).
  - body: { chat_jid: string, message_id?: string, account?: string, message_ids?: string[] }
- `POST https://api.mcp.ai/api/whatsapp/poll/create` — Send a poll or vote on one.
  - body: { to?: string, name?: string, chat_jid?: string, message_id?: string, options: string[], selectable_count?: number, account?: string, message_ids?: string[] }
- `POST https://api.mcp.ai/api/whatsapp/poll/vote` — Send a poll or vote on one.
  - body: { to?: string, name?: string, chat_jid?: string, message_id?: string, options: string[], selectable_count?: number, account?: string, message_ids?: string[] }
- `POST https://api.mcp.ai/api/whatsapp/react` — React to a message with an emoji (or remove your reaction by passing an empty emoji). Requires chat_jid + message_id.
  - body: { chat_jid: string, message_id: string, emoji?: string, account?: string, message_ids?: string[] }
- `POST https://api.mcp.ai/api/whatsapp/search` — Full-text search across all stored messages (SQLite FTS5). Optional chat_jid to scope. Returns matches with context.
  - body: { query: string, chat_jid?: string, limit?: number, account?: string }
- `POST https://api.mcp.ai/api/whatsapp/send/media` — Send a WhatsApp message (text or media).
  - body: { to: string, text?: string, reply_to?: string, type?: string, media_url?: string, media_base64?: string, caption?: string, filename?: string, mimetype?: string, account?: string }
- `POST https://api.mcp.ai/api/whatsapp/send/text` — Send a WhatsApp message (text or media).
  - body: { to: string, text?: string, reply_to?: string, type?: string, media_url?: string, media_base64?: string, caption?: string, filename?: string, mimetype?: string, account?: string }
- `POST https://api.mcp.ai/api/whatsapp/sync` — Refresh this account's local data from WhatsApp — pulls recent messages and refreshes the groups/contacts lists into the local store. Call it BEFORE reading (chats/groups/messages/contacts/search) whe
  - body: { account?: string }

## More
- Page: https://mcp.ai/whatsapp
- Agent spec (llms.txt): https://mcp.ai/whatsapp/llms.txt
- Postman collection: https://mcp.ai/whatsapp/postman.json