Whats MCP Integration for AI Agents

Block a contact on one of your WhatsApp accounts, so they can no longer call or message it — or set unblock=true to unblock one. Reports who it acted on: their number, the name this account's address book has for them, and the country the number belongs to.

[Not included in your plan — calling it returns a plan_required refusal; wa_get_plan's excluded_tools lists what your plan leaves out.] Create a WhatsApp group with a name and initial members from one of your accounts. Returns the new group's JID (use it as wa_send_message's 'to') and an invite link.

Submit a new WhatsApp Business message template for Meta's review on one of your Business (Cloud API) numbers. Meta reviews it (usually minutes, sometimes longer); it can be sent with wa_send_message's template option only once wa_list_templates shows it APPROVED. Categories: MARKETING or UTILITY. Number body variables {{1}}, {{2}}, … in order and give one body_examples value per variable. Templates apply only to Business numbers.

[Not included in your plan — calling it returns a plan_required refusal; wa_get_plan's excluded_tools lists what your plan leaves out.] Delete a WhatsApp group: remove every other member and then leave. The account must be a group admin. WhatsApp has no true group-delete, so this empties the group and exits it.

Delete a WhatsApp message for everyone. WhatsApp has no true delete for a peer that already has the message locally — this revokes it, which every modern client honours.

Delete a WhatsApp Business message template from one of your Business (Cloud API) numbers — one language, or every language of the name when language is omitted. Meta blocks reusing a deleted template's name for a while.

[Not included in your plan — calling it returns a plan_required refusal; wa_get_plan's excluded_tools lists what your plan leaves out.] Stop delivering inbound messages to the configured endpoint. Messages keep arriving and stay readable through wa_list_messages; only the push stops.

Edit a WhatsApp message you sent. WhatsApp only accepts an edit within about 20 minutes of the original send.

[Not included in your plan — calling it returns a plan_required refusal; wa_get_plan's excluded_tools lists what your plan leaves out.] Pause or resume delivery to the configured webhook WITHOUT changing the endpoint or its signing secret. Use this to stop deliveries temporarily — deleting and re-creating the webhook would issue a new secret. Messages keep arriving while paused and stay readable with wa_list_messages.

[Not included in your plan — calling it returns a plan_required refusal; wa_get_plan's excluded_tools lists what your plan leaves out.] Follow a WhatsApp Channel from one of your accounts using its link.

Read the most recent messages for one WhatsApp account, oldest first — or, with chat, one conversation, including older history loaded with wa_load_history. Use this for context before replying; use wa_list_messages to page through everything new. Narrow with since/until (when sent; until is exclusive).

[Not included in your plan — calling it returns a plan_required refusal; wa_get_plan's excluded_tools lists what your plan leaves out.] Get a WhatsApp group's invite link, or set reset=true to revoke it and issue a new one. The account must be a group admin.

Fetch the attachment (image/video/audio/document/sticker) a received WhatsApp message carried, as base64. Use the message_id from wa_list_messages. 'refused' means no retrievable media for that id.

Fetch ONE stored message from one of your accounts, by WhatsApp's message_id (as a webhook delivery or wa_list_messages gave it) or by its cursor. Use this to read the message a webhook told you about, or the one you are about to react to, edit or delete, without paging through history.

Show a plan, its limits and current usage. Plans are per WhatsApp number: pass account_id to see ONE number's plan, limits and the tools it does not include (excluded_tools); omit it for the whole workspace — every number's plan and limits (lines), with excluded_tools listing only what NO active number can use, and plan "mixed" when the numbers are on different plans. A tool listed on this server may still be refused on a number whose plan leaves it out; a tool called WITHOUT account_id acts on every number, so it needs every active number's plan to include it. Call this to see why a tool answers plan_required on a given number, why wa_send_message might be refused, or how much headroom is left. It also reports this service's version (server_version, server_build_date).

Look up who a phone number is on WhatsApp, from one of your accounts: whether it is registered, its public name, about text, profile picture and — for a business — its categories, contact details and hours. An empty about or picture means the peer has not shared it with this account, not that it has none.

[Not included in your plan — calling it returns a plan_required refusal; wa_get_plan's excluded_tools lists what your plan leaves out.] Show the currently configured inbound webhook, including whether it is still enabled and why it was disabled if it was. The signing secret is never returned — it is shown only when the webhook is created.

[Not included in your plan — calling it returns a plan_required refusal; wa_get_plan's excluded_tools lists what your plan leaves out.] Join a WhatsApp group from one of your accounts using its invite link.

[Not included in your plan — calling it returns a plan_required refusal; wa_get_plan's excluded_tools lists what your plan leaves out.] Leave a group or unfollow a channel on one of your accounts, by its JID.

List the WhatsApp accounts available to you. Call this first: every other wa_ tool needs an account_id from here. An account is only usable while its state is "connected".

List every contact one of your accounts has blocked. Each entry carries the contact's number, the name this account's address book has for them — absent for someone not saved on the phone — and the country the number belongs to. WhatsApp does not report when a contact was blocked, so no date is available.

[Not included in your plan — calling it returns a plan_required refusal; wa_get_plan's excluded_tools lists what your plan leaves out.] Read call history across your WhatsApp accounts, oldest first. Page with after_cursor: pass back the next_cursor you were given, and keep going until has_more is false to export the whole history. Each call says whether it was answered and how long it lasted. Narrow with since/until (until is exclusive).

[Not included in your plan — calling it returns a plan_required refusal; wa_get_plan's excluded_tools lists what your plan leaves out.] List the channels one of your accounts follows, with each channel's JID, name and subscriber count.

List or search the address book of one of your WhatsApp accounts — the contacts saved on the phone this account is linked to. Pass query to find someone by name or number; matching looks at saved names, the name the contact publishes, business names and the number. Use the returned phone numbers with wa_send_message. Set include_pictures to also get each contact's profile picture URL; that looks the contacts up on WhatsApp, so it returns at most 10 per page and is slower.

[Not included in your plan — calling it returns a plan_required refusal; wa_get_plan's excluded_tools lists what your plan leaves out.] List a group's members. Each item is one participant with their JID, phone number (in 'name'), and an 'admin' flag.

[Not included in your plan — calling it returns a plan_required refusal; wa_get_plan's excluded_tools lists what your plan leaves out.] List the groups one of your accounts has joined, with each group's JID, name and member count.

Read messages across all your WhatsApp accounts, oldest first. Page with after_cursor: pass back the next_cursor you were given to see only what has arrived since. Use this to catch up after being notified of a new message. Narrow with account_id, chat, and since/until (when the message was sent; until is exclusive). Add include_history to also read synced history.

List the WhatsApp Business message templates of one of your Business (Cloud API) numbers, with each one's review status (APPROVED, PENDING, REJECTED — a rejected one carries Meta's rejected_reason). Use an APPROVED template's name and language with wa_send_message's template/template_language to start a conversation or message outside the 24-hour window, and supply its 'variables' count as template_variables, in order. Templates apply only to Business numbers, not personal linked-device numbers.

Ask the account's phone for older messages in one conversation, before the oldest one stored here, and store them. The phone must be online; it usually answers within seconds. Read the result with wa_get_chat and the same chat. Loaded messages are history: they never trigger webhooks and appear in wa_list_messages only with include_history=true. They are kept for your plan's history window like any other message. A conversation needs at least one stored message to page back from.

Begin linking a new WhatsApp account. Returns a QR code as a PNG image for the user to scan with their phone. The code expires every ~20 seconds — poll wa_pair_status with the returned pair_id to get the current code and to find out when the account is linked. Pass import_history to choose whether this pairing loads the phone's recent messages as history.

Check a pairing started with wa_pair_account. While state is "qr" a new image is returned each time — show the latest to the user. When state becomes "paired" the account is ready and appears in wa_list_accounts.

React to a WhatsApp message with an emoji. Pass an empty reaction to remove a reaction you previously sent.

[Not included in your plan — calling it returns a plan_required refusal; wa_get_plan's excluded_tools lists what your plan leaves out.] Remove members from a WhatsApp group by phone number or JID. The account must be a group admin.

Send a bug report, feature request or feedback about WhatsMCP to the WhatsMCP team. Use it when the person asks to report a problem, suggest a feature or leave feedback — not to contact a WhatsApp user (that is wa_send_message). The report is emailed to the team with the workspace and the sender's address, so a reply reaches the person by email. Write it in the person's words; for a bug include what was done, what happened, what was expected and any error text. Never include passwords, API keys or message contents the person did not ask to share.

Send a WhatsApp message from one of your accounts — text, or an attachment: an image via image_base64 (JPEG/PNG, at most 5 MiB; text becomes the caption), a document via document_base64 (any file, at most 20 MiB; text becomes the caption), or audio via audio_base64 (at most 16 MiB; no caption). For a Business (WhatsApp Cloud API) number, set 'template' to send a pre-approved message template (e.g. hello_world) — the only way to start a conversation or to message that number outside the 24-hour window. Check the returned status: "sent" means delivered; "queued" means the message was accepted but not yet confirmed and may still arrive, so do NOT send it again; "refused" means nothing was sent and the reason explains whether retrying will help.

Announce a typing state ("composing"/"paused") to a chat, or set one of your accounts online/offline ("available"/"unavailable"). Fire-and-forget: there is no delivery confirmation.

Change the profile photo of one of your own WhatsApp accounts — the picture every contact sees. Pass image_base64 (JPEG, PNG or GIF, at most 5 MiB) to replace it: the image is center-cropped to a square and scaled to at most 640x640, as WhatsApp stores it. Or pass remove=true to delete the current photo. The previous photo cannot be restored afterwards. Contacts may keep seeing the old photo for a while until their app refreshes it.

[Not included in your plan — calling it returns a plan_required refusal; wa_get_plan's excluded_tools lists what your plan leaves out.] Register an HTTPS endpoint to receive inbound WhatsApp messages as they arrive, so you do not have to poll wa_list_messages. Returns a signing secret that is shown ONCE — store it immediately. Calling this again replaces the endpoint and issues a NEW secret.

Disconnect a WhatsApp account from this service. The account stops sending and receiving immediately. Message history is kept. Re-connecting requires pairing the phone again, so ask the user before calling this.

[Not included in your plan — calling it returns a plan_required refusal; wa_get_plan's excluded_tools lists what your plan leaves out.] Change a WhatsApp group's settings: its name, its description, whether only admins may change settings (locked), and whether only admins may post (announce). Pass only the fields to change; several can change in one call. If the group restricts settings to admins, the account must be one. WhatsApp applies each change separately, so on a refusal 'applied' lists the changes that took effect before it.

[Not included in your plan — calling it returns a plan_required refusal; wa_get_plan's excluded_tools lists what your plan leaves out.] Add members to a WhatsApp group (action=add), make members admins (action=promote), or make admins ordinary members again (action=demote), by phone number or JID. Adding needs the account to be a member (and, for private groups, an admin); promote and demote need an admin. To remove members, use wa_remove_participants.