Skip to main content
The whatsapp MCP adapter sends messages through Meta’s WhatsApp Cloud API — text, media, and pre-approved templates.

​
Prerequisites

  • A Meta developer account and Business app with the WhatsApp product enabled
  • A WhatsApp Business Account (WABA) linked to the app
  • project_contributor access in AgentRuntime

​
Connect in AgentRuntime

AgentRuntime supports two connection paths:
1

Open Connections

On Connections, click Connect WhatsApp in the Console.
2

Start embedded signup

Click Connect and complete Meta’s embedded signup flow. You authorize the app and select your business phone number.
3

Complete registration

The Console exchanges the OAuth code server-side and stores access_token, business_account_id, and phone_number_id. Tokens never appear in the browser.
4

Install the MCP instance

Go to MCP, click Add instance for whatsapp, wire your WhatsApp connection on Instance config, and set the profile active.

​
Manual credentials

If you already have a System User token and IDs from Meta Business Manager:
1

Gather credentials

From Meta Business Settings, collect:
  • Access token — System User token with whatsapp_business_messaging and whatsapp_business_management
  • WhatsApp Business Account ID (WABA)
  • Phone number ID
2

Enter manually

In the Connect WhatsApp flow, choose manual entry and paste the three values.
3

Wire MCP instance

Go to MCP, click Add instance for whatsapp, and wire the connection on Instance config.
Embedded signup for onboarding customers outside your Business Manager requires Meta’s Tech Provider programme. Until approved, embedded signup works for accounts you administer in dev mode. Manual tokens work for production messaging on your own WABA.

​
What you can build

  • Order updates — Shopify get_shopify_order → send_message or send_template_message when status changes.
  • Appointment reminders — Schedule workflow → template message with date/time parameters (24h+ outbound requires approved templates).
  • Support handoff — Inbound webhook message → LLM draft → human_task → send_message reply.
  • Ops alerts — Workflow failure → send_message to on-call number with run summary.

​
Tools

ToolDescription
send_messageSend a text message
send_mediaSend image, audio, document, sticker, or video
send_template_messageSend a pre-approved template with parameters
list_phone_numbersList phone numbers on the WABA
list_message_templatesList message templates (optionally filter by status)
All send tools accept an optional per-call phone_number_id override. Otherwise the connector uses the ID from your connection.

​
Example

Send a notification after a workflow step completes: 
{
  "id": "notify-customer",
  "type": "mcp_call",
  "name": "WhatsApp notification",
  "tool_name": "send_message",
  "tool_args": {
    "to": "{{input.customer_phone}}",
    "body": "Your order {{input.order_id}} is ready for pickup."
  },
  "depends_on": ["validate-order"],
  "timeout_s": 30
}
For marketing or outbound messages to users who have not messaged you in 24 hours, use send_template_message with an approved template.

​
Templates

WhatsApp requires pre-approved templates for most outbound business messaging:
  1. Call list_message_templates to find an approved template name and language
  2. Use send_template_message with header, body, and button parameters
While your Meta app is in development mode, add recipient test numbers under WhatsApp → API setup.

​
Configuration

Stored in your connection / MCP instance profile:
KeyRequiredDescription
access_tokenYesSystem User or exchanged OAuth token
business_account_idYesWABA ID
phone_number_idRecommendedDefault sender phone number
api_baseNoDefault https://graph.facebook.com
api_versionNoDefault v20.0

​
Troubleshooting

IssueFix
401 / token errorsRegenerate System User token; update connection
Message not delivered (dev mode)Add recipient as a test number in Meta API setup
Template rejectedUse only APPROVED templates from list_message_templates
Wrong senderPass phone_number_id explicitly or update connection default
See Troubleshooting for MCP binding and OAuth issues.