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 and 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

| 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. |

On this page