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

# WhatsApp Tools

> Send templates, create campaigns, write template and Flow drafts, and review campaign results.

## What is this?

These tools cover WhatsApp messaging: sending an approved template, sending a free-form utility message with Direct Send, creating campaigns, writing template and WhatsApp Flow drafts, and reading campaign results. Tools that reach customers are marked **Reaches customers** in the Developer Portal.

These tools belong to the [Workspace MCP](https://docs.xpressbot.org/api-reference/mcp/workspace/overview.md). Each tool below shows its **Mode** (**Read** runs immediately; **Write** asks your MCP client to confirm first) and the **Permission needed** for it to appear for your key — "None" means every connected key sees it.

## What can I do here?

* Send an approved template or a Direct Send utility/authentication message
* Create a campaign from an approved template, now or scheduled
* Write a template draft or a WhatsApp Flow draft for you to review
* Read campaigns and their results, and label contacts by what happened to their message

## Tools

### `send_template`

Send one of this channel's approved WhatsApp templates to the customer of a conversation. Templates have fixed text approved by WhatsApp: you cannot write a new message here, only pick an existing template (exact name from list\_templates) and fill its `{{1}}`, `{{2}}`… variables in order with `parameters` (exactly as many as it has).

**Mode:** Write · **Permission needed:** `inbox:send`

### `direct_send`

Send a free-form WhatsApp utility or authentication message to the customer of a conversation without a pre-approved template (Meta's Direct Send beta). Use this only when no matching approved template exists via list\_templates — prefer send\_template whenever an approved template already fits. Only for utility (order/appointment/status updates) or authentication (verification codes) content; never for marketing, which must use an approved template. `templateName` (business-named templates) works with utility only, never authentication. Authentication category and Direct Send itself are restricted by Meta per WABA — a channel that isn't onboarded will get a clear rejection.

**Mode:** Write · **Permission needed:** `inbox:send`

### `create_campaign`

Create a WhatsApp campaign that sends an approved template to a set of contacts, now or at a scheduled time. Find the template with list\_templates and labels with list\_labels first; fill every `{{n}}` placeholder in the template body, one `variables` entry each (fixed text, the contact's name/phone/email, or a custom field). The user sees one Confirm card with the template, audience, number of recipients and the send time; nothing is sent until they confirm. Once started, a campaign can only be stopped from the dashboard.

**Mode:** Write · **Permission needed:** `campaigns:create`

### `create_template_draft`

Write a WhatsApp message template and save it as a DRAFT in the user's current channel (text templates only: optional header text, body with `{{1}}` `{{2}}` placeholders and an example value for each, optional footer, up to 3 buttons). Nothing is sent to WhatsApp and nothing reaches customers: the user opens it in Templates, reviews it and submits it for approval, which can take minutes to a day. A campaign can only use an approved template. Check list\_templates first so you do not duplicate one. Write the text from what the user said; never invent offers, prices or links. Marketing templates should read as marketing, utility templates as plain updates. Templates with a header image, video or document, carousels and authentication codes are made in the dashboard.

**Mode:** Write · **Permission needed:** `templates:create`

### `list_campaigns`

List WhatsApp campaigns in the user's current channel, newest first, with status, template and results (recipients, sent, delivered, read, replied, failed, pending, and delivery/read/reply/failure rates).

**Mode:** Read · **Permission needed:** `campaigns:view`

### `get_campaign`

Details and results of one campaign: audience labels, template, schedule, progress, totals, rates and the failure reason when it failed. Pass campaignId from list\_campaigns, or the campaign's name when you only know the name (e.g. a campaign named earlier in the chat).

**Mode:** Read · **Permission needed:** `campaigns:view`

### `apply_campaign_label_action`

Add a label to, or remove a label from, the contacts of one campaign by what happened to their message: delivered (sent, delivered or read), read, or failed (failed or never sent). Same as Campaign Actions on the campaign's page. Find the campaign with list\_campaigns and the label with list\_labels first; only an existing label can be used. Only that campaign's own contacts are changed, and a contact is never given the same label twice. You see one Confirm card with how many contacts match.

**Mode:** Write · **Permission needed:** `contacts:edit` (and `campaigns:view`)

### `list_templates`

Find WhatsApp message templates in the user's current channel: name, category, language, approval status, the template's fixed text, how many `{{n}}` body values it takes, which URL buttons need a value, and whether it needs a header file. Use `search` (part of the name or text) whenever you are looking for a specific template; `total` tells you how many match, and if it is larger than what was returned, search more narrowly instead of guessing. Only approved templates can be sent, and their text cannot be changed; only the values are filled.

**Mode:** Read · **Permission needed:** `templates:view`

### `list_whatsapp_flows`

List the WhatsApp Flows (in-chat forms) of the user's current channel with their id, name, and status (such as DRAFT or PUBLISHED). Use it before creating one so you don't duplicate a flow, and to find a flow id for a Send Flow automation step.

**Mode:** Read · **Permission needed:** `flows:view`

### `create_whatsapp_flow_draft`

Build a WhatsApp Flow (a multi-screen form that opens inside the chat) from a description and save it as a **draft** on WhatsApp. It isn't published and isn't sent to anyone — you open it in **Flows**, review it in the builder and phone preview, and save it there (saving publishes it). Screens can contain headings, text, short answers (text, number, email, or phone), paragraphs, dates, single and multiple choice, dropdowns, and an opt-in. Images, photo or document upload, the calendar picker, conditional If/Switch parts, lists that navigate, dynamic data from an endpoint, and mapping answers to contact fields are not covered — build those in Flows.

**Mode:** Write · **Permission needed:** `flows:create`

## Troubleshooting / Technical Notes

* **A tool I expect isn't offered.** The MCP server only offers tools whose required permission your API key's owner holds, re-checked on every call. Grant the permission shown on the tool — see [Team](https://docs.xpressbot.org/workspace/team.md).
* **A Write tool never seems to run.** Your MCP client asks you to approve every Write tool call. Check for a pending approval prompt.
* **A call returns an error.** See [MCP errors](https://docs.xpressbot.org/api-reference/mcp/errors.md).

## Related docs

* [Workspace MCP tool catalog](https://docs.xpressbot.org/api-reference/mcp/workspace/tools/overview.md)
* [Workspace MCP](https://docs.xpressbot.org/api-reference/mcp/workspace/overview.md)
* [Templates](https://docs.xpressbot.org/workspace/whatsapp/templates.md)
* [Campaigns](https://docs.xpressbot.org/workspace/whatsapp/campaigns.md)
* [Flow](https://docs.xpressbot.org/workspace/whatsapp/flow.md)


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