# MCP tools

> Every Whatsable MCP tool and the parameters its input schema declares.

An AI app only sees the tools its access allows. A parameter's name, whether it is required, its type, and its description are copied from that tool's input schema. Nothing on this page is typed by hand.

See [access](/mcp/manage-access) and [concepts](/mcp/concepts).

## Get Account and Plan

`get_account`

This tool takes no parameters.

## List WhatsApp Numbers

`list_numbers`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `limit` | no | integer |  |
| `cursor` | no | string |  |

## List Templates

`list_templates`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `limit` | no | integer |  |
| `cursor` | no | string |  |
| `status` | no | string | `pending`, `approved`, `rejected`, `paused`, `disabled`, or a newer one of Meta's. |
| `number_id` | no | string |  |
| `name` | no | string |  |
| `language` | no | string | Such as `en_US`. |

## Get Template

`get_template`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `id` | yes | string |  |

## List Messages

`list_messages`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `limit` | no | integer |  |
| `cursor` | no | string |  |
| `conversation_id` | no | string |  |
| `contact_id` | no | string |  |
| `number_id` | no | string |  |
| `direction` | no | "inbound" or "outbound" |  |
| `status` | no | "pending" or "sent" or "delivered" or "read" or "failed" |  |
| `created_after` | no | string |  |
| `created_before` | no | string | Exclusive. |
| `query` | no | string | Ignores case. Needs `conversation_id` or `contact_id`. |

## Get Message Status

`get_message`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `id` | yes | string |  |

## Find Contacts

`find_contacts`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `limit` | no | integer |  |
| `cursor` | no | string |  |
| `phone` | no | string | E.164; the `+`, spaces and dashes may be omitted. |
| `wa_user_id` | no | string | A Business-Scoped User ID. |
| `username` | no | string | With or without the leading `@`. |
| `label_id` | no | string |  |
| `updated_after` | no | string |  |
| `query` | no | string | Name: partial, ignoring case and accents. @username: partial, ignoring case. Phone: three or more digits. Every word must match. |

## Get Contact

`get_contact`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `id` | yes | string |  |

## List Labels

`list_labels`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `limit` | no | integer |  |
| `cursor` | no | string |  |

## Send Text Message

`send_text_message`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `to` | no | string | A new phone or user id creates a contact. |
| `conversation_id` | no | string | Replies from its number. |
| `from` | no | string | The number to send from, by id or E.164 phone. Absent, the key's default number sends. Never another fallback. |
| `pause_ai` | no | boolean | Default true: pauses the AI agent in this chat. False leaves it on. |
| `reply_to_message_id` | no | string | Quote this message (an id from list_messages). |
| `body` | yes | string | Up to 4,096 characters, 1,024 with `buttons`. |
| `preview_url` | no | boolean | Show a preview of the first link. Off by default. |
| `buttons` | no | array of object | Up to three reply buttons, ids and titles unique. |

## Send Template Message

`send_template_message`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `to` | no | string | A new phone or user id creates a contact. |
| `conversation_id` | no | string | Replies from its number. |
| `from` | no | string | The number to send from, by id or E.164 phone. Absent, the key's default number sends. Never another fallback. |
| `template` | yes | object |  |
| `pause_ai` | no | boolean | Default true: pauses the AI agent in this chat. False leaves it on. |

## Send Media Message

`send_media_message`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `to` | no | string | A new phone or user id creates a contact. |
| `conversation_id` | no | string | Replies from its number. |
| `from` | no | string | The number to send from, by id or E.164 phone. Absent, the key's default number sends. Never another fallback. |
| `pause_ai` | no | boolean | Default true: pauses the AI agent in this chat. False leaves it on. |
| `reply_to_message_id` | no | string | Quote this message (an id from list_messages). |
| `kind` | yes | "image" or "video" or "audio" or "document" or "sticker" | A `sticker` is a WebP image. |
| `url` | no | string | A public HTTPS link, no sign-in. |
| `media_id` | no | string | An id from upload_media. |
| `caption` | no | string | Under an image, video or document; not audio or a sticker. |
| `filename` | no | string | Documents only. |

## Create and Submit Template

`create_template`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `number_id` | no | string | A number on the WhatsApp Business Account the template is created in. Absent, the key's default number decides. |
| `name` | no | string | Meta's identifier. Derived from `display_name` when absent. |
| `display_name` | no | string | The name people read. With `name`, it must derive to `name`. |
| `language` | yes | string | Meta's language code, such as `en_US`. |
| `category` | yes | "marketing" or "utility" or "authentication" |  |
| `header` | no | value | `none` (default), `text`, or media by one of `url` (public HTTPS) or `media_id` (an upload). |
| `body` | no | string | Numbered variables only, not named ones. Absent only for an authentication template. |
| `body_examples` | no | array of string | One per body variable, in order. Absent, placeholders are submitted. |
| `footer` | no | string |  |
| `buttons` | no | array of value |  |
| `authentication` | no | object | For the `authentication` category only. |

## Find or Create Contact

`create_contact`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `phone` | no | string | E.164; the `+`, spaces and dashes may be omitted. |
| `wa_user_id` | no | string | A Business-Scoped User ID. |
| `name` | no | string | Set on a contact this call creates. An existing contact keeps its name. |

## Update Contact

`update_contact`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `id` | yes | string |  |
| `name` | no | string |  |
| `note` | no | value |  |
| `automation_note` | no | value |  |

## Add Label to Contact

`add_contact_label`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `id` | yes | string | The contact id. |
| `label` | yes | string | A name matches ignoring case and accents. |

## Remove Label from Contact

`remove_contact_label`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `id` | yes | string | The contact id. |
| `label_id` | yes | string | The label id. |

## Create Label

`create_label`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `name` | yes | string |  |
| `color` | yes | "label-1" or "label-2" or "label-3" or "label-4" or "label-5" or "label-6" |  |
| `description` | no | string |  |
| `keywords` | no | array of string |  |
| `number_ids` | no | array of string | Empty or absent: every number. |

## Update Label

`update_label`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `id` | yes | string |  |
| `name` | no | string |  |
| `color` | no | "label-1" or "label-2" or "label-3" or "label-4" or "label-5" or "label-6" |  |
| `description` | no | value |  |
| `keywords` | no | array of string |  |
| `number_ids` | no | array of string | Empty: every number. |

## Delete Label

`delete_label`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `id` | yes | string |  |

## List Conversations

`list_conversations`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `limit` | no | integer |  |
| `cursor` | no | string |  |
| `number_id` | no | string |  |
| `contact_id` | no | string |  |
| `updated_after` | no | string |  |
| `query` | no | string | Contact name, @username or phone digits, or text in the last message. Partial; for a name, every word must match. |
| `label_id` | no | string |  |
| `unread` | no | value | `true`: unread messages, or marked unread. `false`: neither. |
| `window_open` | no | value | `true`: a session message can be sent now. |
| `awaiting_reply` | no | value | `true`: the customer wrote last. |
| `figures_to_check` | no | value | `true`: an AI message has a figure nobody checked. |

## Get Conversation

`get_conversation`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `id` | yes | string |  |

## Turn AI On or Off in Conversation

`set_conversation_ai`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `id` | yes | string | The conversation id. |
| `status` | no | "active" or "off" | Left out, the status is kept. |
| `bot_id` | no | value | Which AI agent answers this chat; null = the number's default. |

## Schedule Message

`schedule_message`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `to` | no | string | A new phone or user id creates a contact. |
| `conversation_id` | no | string | Replies from its number. |
| `from` | no | string | The number to send from, by id or E.164 phone. Absent, the key's default number sends. Never another fallback. |
| `text` | no | object | A text message. Or send `template`. |
| `template` | no | object | Approved, by `id` or `name` and `language`, `variables` as get_template lists. Or `text`. |
| `send_at` | yes | string | Future RFC 3339 with offset, such as `2026-10-22T09:00:00-03:00`. |
| `time_zone` | no | string | For display only: `send_at` is never read in it. |
| `send_if` | no | object |  |

## List Scheduled Messages

`list_scheduled_messages`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `limit` | no | integer |  |
| `cursor` | no | string |  |
| `status` | no | "pending" or "sent" or "suppressed" or "failed" or "cancelled" or "missed" |  |
| `conversation_id` | no | string |  |
| `number_id` | no | string |  |

## Get Scheduled Message

`get_scheduled_message`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `id` | yes | string |  |

## Cancel Scheduled Message

`cancel_scheduled_message`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `id` | yes | string |  |

## List Broadcasts

`list_broadcasts`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `limit` | no | integer |  |
| `cursor` | no | string |  |
| `number_id` | no | string |  |
| `status` | no | "scheduled" or "running" or "paused" or "completed" or "cancelled" |  |

## Get Broadcast

`get_broadcast`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `id` | yes | string |  |

## List Broadcast Recipients

`list_broadcast_recipients`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `id` | yes | string | The broadcast id. |
| `limit` | no | integer |  |
| `cursor` | no | string |  |

## Launch Broadcast

`create_broadcast`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `name` | no | string |  |
| `from` | no | string | The number to send from, by id or E.164 phone. Absent, the key's default number sends. It must be `active`. |
| `template` | yes | object | Approved, of the sending number's account: by `id`, or `name` and `language`. Not authentication, nor with a coupon-code button. |
| `variables` | no | object | Per recipient, keyed by `variables[].key`: a string, or `{ "url": "https://..." }` for a media header. |
| `recipients` | yes | array of object | 1 to 10,000, at most 2 MB. A repeated phone gets one message, with its first values. |
| `scheduled_at` | no | string | RFC 3339 with offset. Absent or under 60 s past: now; older is refused. |
| `time_zone` | no | string | For display only: `scheduled_at` is never read in it. |
| `labels` | no | array of string | By id or exact name, added to each recipient once sent; each must be on the sending number. |
| `mode` | no | "regular" or "smart" | `regular`: `batch_size` per minute. `smart`: `batch_size` while the read rate holds `target_read_rate`. |
| `batch_size` | no | integer | `regular`: messages a minute, 1 to 60, default 3. `smart`: the batch, 1 to 20, default 5. Not for `risk`. |
| `target_read_rate` | no | number | `smart` only: the share of sent messages that must be read before the next batch, 0.1 to 1, default 0.3. |

## Cancel Broadcast

`cancel_broadcast`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `id` | yes | string |  |

## List AI Bots

`list_ai_bots`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `limit` | no | integer |  |
| `cursor` | no | string |  |

## Get AI Bot

`get_ai_bot`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `id` | yes | string |  |

## List AI Bot Knowledge Files

`list_knowledge_files`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `id` | yes | string | The bot id. |
| `limit` | no | integer |  |
| `cursor` | no | string |  |

## List AI Bot Sendable Files

`list_ai_bot_files`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `id` | yes | string | The bot id. |
| `limit` | no | integer |  |
| `cursor` | no | string |  |

## Create AI Bot

`create_ai_bot`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `name` | yes | string | Unique in the organization, ignoring case and accents. |
| `mission` | yes | string | What the bot is for. |
| `tone` | yes | string | How the bot speaks. |
| `instructions` | yes | string | The organization's instructions to the bot. |
| `knowledge` | no | value | Plain-text facts it may state. |
| `status` | no | "draft" or "active" or "archived" | `draft` answers no one. Only an `archived` bot can be deleted. |
| `time_zone` | no | string | IANA name; quiet hours use it. |
| `debounce_seconds` | no | integer | Wait for more messages before answering. |
| `reply_message_mode` | no | "single" or "multiple" | `single`: one message per reply. `multiple`: as many as the bot chooses. |
| `handoff_keywords` | no | array of string | Words that hand a chat to a person. |
| `handoff_instructions` | no | value | When the bot hands the chat to a person. Not sent to the customer. |
| `notify_on_handoff` | no | boolean | Stored only: no notification is sent yet. |
| `flag_unverified_figures` | no | boolean | When false, a missing price, amount or date is not flagged. The message is still sent. |
| `resume_policy` | no | "never" or "new_session" or "timer" | After a takeover: `never`, `new_session` (the customer writes after the window closed) or `timer`. |
| `resume_after_seconds` | no | value | Required with `resume_policy: "timer"`. |
| `label_permissions` | no | object | Labels the bot may add or remove. |
| `proactive` | no | object | Follow-ups when a customer goes quiet. |

## Update AI Bot

`update_ai_bot`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `id` | yes | string |  |
| `version` | yes | string | The bot's `updated_at`, exactly as get_ai_bot returned it. |
| `name` | no | string | Unique in the organization, ignoring case and accents. |
| `mission` | no | string | What the bot is for. |
| `tone` | no | string | How the bot speaks. |
| `instructions` | no | string | The organization's instructions to the bot. |
| `knowledge` | no | value | Plain-text facts it may state. |
| `status` | no | "draft" or "active" or "archived" | `draft` answers no one. Only an `archived` bot can be deleted. |
| `time_zone` | no | string | IANA name; quiet hours use it. |
| `debounce_seconds` | no | integer | Wait for more messages before answering. |
| `reply_message_mode` | no | "single" or "multiple" | `single`: one message per reply. `multiple`: as many as the bot chooses. |
| `handoff_keywords` | no | array of string | Words that hand a chat to a person. |
| `handoff_instructions` | no | value | When the bot hands the chat to a person. Not sent to the customer. |
| `notify_on_handoff` | no | boolean | Stored only: no notification is sent yet. |
| `flag_unverified_figures` | no | boolean | When false, a missing price, amount or date is not flagged. The message is still sent. |
| `resume_policy` | no | "never" or "new_session" or "timer" | After a takeover: `never`, `new_session` (the customer writes after the window closed) or `timer`. |
| `resume_after_seconds` | no | value | Required with `resume_policy: "timer"`. |
| `label_permissions` | no | object | Labels the bot may add or remove. |
| `proactive` | no | object | Follow-ups when a customer goes quiet. |
| `knowledge_append` | no | string |  |
| `instructions_append` | no | string |  |

## Duplicate AI Bot

`duplicate_ai_bot`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `id` | yes | string | The bot to copy. |

## Delete AI Bot

`delete_ai_bot`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `id` | yes | string |  |

## Assign AI Bot to Number

`assign_ai_bot_to_number`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `id` | yes | string | The number id. |
| `bot_id` | yes | value |  |

## Turn AI Follow-ups On or Off for Contact

`set_contact_follow_ups`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `id` | yes | string | The contact id. |
| `status` | yes | "on" or "off" |  |

## Read Conversation History

`read_conversation`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `conversation_id` | yes | string | The conversation id. |
| `limit` | no | integer |  |
| `cursor` | no | string |  |
| `types` | no | string | Comma-separated: message, note, ai_decision, ai_status_changed, ai_bot_changed, label_added, label_removed. |

## Delete Template

`delete_template`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `id` | yes | string |  |

## Get Message Analytics

`get_message_analytics`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `from` | yes | string |  |
| `to` | yes | string | Included. |
| `time_zone` | yes | string | IANA name. |
| `number_id` | no | string | Absent: every number. Required if this connection has only some. |

## Get Template Analytics

`get_template_analytics`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `from` | yes | string |  |
| `to` | yes | string | Included. |
| `time_zone` | yes | string | IANA name. |
| `number_id` | no | string | Absent: every number. Required if this connection has only some. |

## Get Conversation Analytics

`get_conversation_analytics`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `from` | yes | string |  |
| `to` | yes | string | Included. |
| `time_zone` | yes | string | IANA name. |
| `number_id` | no | string | Absent: every number. Required if this connection has only some. |

## Get AI Bot Analytics

`get_ai_analytics`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `from` | yes | string |  |
| `to` | yes | string | Included. |
| `time_zone` | yes | string | IANA name. |
| `number_id` | no | string | Absent: every number. Required if this connection has only some. |

## Get Broadcast Analytics

`get_broadcast_analytics`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `from` | yes | string |  |
| `to` | yes | string | Included. |
| `time_zone` | yes | string | IANA name. |
| `number_id` | no | string | Absent: every number. Required if this connection has only some. |

## List Team Members

`list_members`

This tool takes no parameters.

## Pause or Resume Broadcast

`set_broadcast_status`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `id` | yes | string | The broadcast id. |
| `status` | yes | "paused" or "running" |  |

## Mark Conversation Read or Unread

`set_conversation_unread`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `id` | yes | string | The conversation id. |
| `unread` | yes | boolean | Reading through the API never marks it read. |

## Add Conversation Note

`add_conversation_note`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `id` | yes | string | The conversation id. |
| `body` | yes | string | The note, 1 to 4000 characters. Only the team sees it. |

## Delete Conversation Note

`delete_conversation_note`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `id` | yes | string | The conversation id. |
| `note_id` | yes | string | The timeline's `note.id`, of this conversation. |

## Cancel AI Retry

`cancel_ai_retry`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `id` | yes | string | The conversation id. |

## Mark Figures Checked

`mark_figures_checked`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `id` | yes | string | The message id. |

## List Saved Replies

`list_saved_replies`

This tool takes no parameters.

## Upload Media

`upload_media`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `filename` | yes | string |  |
| `mime_type` | yes | string |  |
| `content_base64` | yes | string |  |

## Read AI Bot Text

`read_ai_bot_text`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `id` | yes | string |  |
| `field` | yes | "mission" or "instructions" or "knowledge" or "handoff_instructions" or "label_instructions" or "proactive_instructions" |  |
| `offset` | no | integer |  |
| `limit` | no | integer | Characters. |
| `version` | no | string | The first page's `updated_at`; a later page is refused if the bot changed. |

## Create Number Connect Link

`create_number_connect_link`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `email` | no | string | A teammate's address. |
| `name` | no | string | For the greeting. |

## Get Setup Status

`get_setup_status`

This tool takes no parameters.

## React to Message

`react_to_message`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `message_id` | yes | string | The message id. |
| `emoji` | yes | string |  |

## Get WhatsAble Guide

`get_guide`

| Parameter | Required | Type | Description |
| --- | --- | --- | --- |
| `topic` | no | string | Absent: the overview of what this connection can do. Or an id from the overview, for its details. |