MCP tools
Find the right tool for a customer-support or campaign task.
Reviewed
MCP tools work within your role, allowed numbers and app permissions. Seeing a tool does not grant permission to run it.
Start with MCP setup. Your client shows current inputs and results. Preserve returned identifiers when confirming previews or continuing pagination.
Check the connection
| Tool | What it does |
|---|---|
get_workspace | Check which workspace the client is using. |
list_instances | List the WhatsApp numbers you can access. |
get_instance | Check number status and handling mode. |
request_permissions | Request a permission review without granting access. |
Look up contacts and segments
| Tool | What it does |
|---|---|
list_contacts | Search active contacts. |
find_contact | Find by exact phone; optionally include archived contacts. |
list_recent_contacts | Read recently updated active contacts. |
get_contact | Read a contact, its consent state and labels. |
list_labels | List active labels. |
list_segments | List static segments, optionally including archived ones. |
get_segment | Inspect one static segment. |
list_segment_members | Read contact IDs in an active static segment. |
Read customer conversations
| Tool | What it does |
|---|---|
list_conversations | Find conversations for your permitted numbers. |
get_message | Read one message's permitted content and delivery status. |
list_conversation_messages | Read a conversation's message history with pagination and filters. |
list_message_changes | Follow retained message and status revisions for one number. |
get_message_media | Read authorized incoming media from conversations covered by your Inbox access. |
Follow the message changes guide for cursors and recovery. Store number and conversation IDs: one contact can have conversations on different numbers.
View templates and reports
| Tool | What it does |
|---|---|
list_templates | List cached templates, including supported lifecycle filters. |
get_template | Read template content, eligibility and form inputs. |
get_campaign_status | Read a campaign's status and delivery counts. |
list_campaigns | List campaign summaries for one number. |
get_campaign | Read delivery, failure and settlement summaries. |
list_campaign_recipients | Read recipient outcomes and supported failure filters. |
get_activity_report | Read messaging, API and webhook-health summaries. |
Campaign reads do not grant send or retargeting permission. See campaign results for uncertainty, filters and pagination.
Download incoming media
| Tool | What it does |
|---|---|
get_number_message_media | Download ready incoming files without general Inbox access. |
Media tools return bounded base64 chunks. Decode each chunk, concatenate bytes in offset order and verify the complete file hash. They do not expose storage URLs or upload files.
Read event history
| Tool | What it does |
|---|---|
list_recent_events | Read permitted contact-created and incoming-message events. |
Event access does not grant webhook administration or expose signing secrets.
Manage contacts and audiences
| Tool | What it does |
|---|---|
upsert_contact | Create or update a contact; preserve opt-out consent. |
update_contact | Update or explicitly restore a contact at its current revision. |
create_label | Create a label. |
update_label | Rename an eligible active label. |
archive_label | Archive an eligible label after checking its dependencies. |
apply_contact_label | Attach an existing label to an active contact. |
remove_contact_label | Remove a label from a contact. |
create_segment | Create a static segment. |
update_segment | Update a static segment. |
archive_segment | Archive an eligible static segment after dependency checks. |
add_segment_member | Add an active contact to a static segment. |
remove_segment_member | Remove a contact from a static segment. |
These tools change shared records without permanent deletion. Review contact restoration. Keep the same idempotency key when reconciling an uncertain mutation.
Claim conversations as yourself
| Tool | What it does |
|---|---|
get_conversation_assignment | Check the active session, current owner, revision and teams you can use. |
claim_conversation | Take an eligible unassigned conversation as yourself after explicit approval. |
A claim pauses automated handling but sends no message. It cannot take another teammate's conversation or move it to another team. Follow claim and reply for the separate approvals.
Reply to customers
| Tool | What it does |
|---|---|
preview_message | Prepare a text reply for a conversation assigned to you. |
preview_rich_message | Preview a text, media, location, contact-card or interactive reply. |
preview_media_message | Prepare a reply using an existing authorized shared-media asset. |
confirm_message | Submit the exact reviewed reply after explicit approval. |
Replies need a conversation assigned to you and an open service window. Previews expire after five minutes. Queued is not delivered; reconcile uncertainty before retrying.
Send approved templates
| Tool | What it does |
|---|---|
preview_template_message | Preview a template, its variables and supported send time. |
confirm_template_message | Confirm that unchanged template-message preview after approval. |
Template approval does not bypass consent, quality or recipient restrictions. A scheduled template message also needs offline_access.
Schedule template messages
The Schedule template messages choice uses preview_template_message and confirm_template_message with an approved send time and offline_access.
For a single-contact campaign, Schedule broadcasts provides:
| Tool | What it does |
|---|---|
preview_scheduled_template | Preview a campaign for a static segment with exactly one contact. |
Confirm this campaign with confirm_broadcast. Review its name, contact, singleton segment, variables and delivery time. Campaign authority and offline_access are required.
Schedule broadcasts
| Tool | What it does |
|---|---|
preview_broadcast | Review the exact recipients, rendered content, sender and scheduled time. |
confirm_broadcast | Submit an unchanged broadcast or scheduled-template campaign preview after explicit approval. |
Broadcast previews must fit within 100 recipients and 48 KiB; larger previews are rejected. Schedule 30 minutes to 15 days ahead with offline_access. Check the timezone before converting to UTC. See scheduling rules.
Edit template definitions
| Tool | What it does |
|---|---|
preview_template_update | Review a complete replacement of an existing template definition. |
confirm_template_update | Submit the unchanged replacement after explicit approval. |
An edit affects the template shared by every number in its WhatsApp business account and may remove its approval. It requires unrestricted number access. Create and delete templates in the dashboard; MCP does not expose those operations.
Manage API keys, number handling, webhooks and signing secrets in the dashboard. The REST API reference describes the separate API-key surface.