At a glance
- Availability: Experimental (how to enable).
- Auth: API key.
- Connection: The key from
WHATSAPP_ACCESS_TOKENis sent as theBearerprefixedAuthorizationheader. - Docs: https://developers.facebook.com/docs/whatsapp/cloud-api/get-started
Credentials
Set these per environment. See Connect an integration.| Variable | Required | Description |
|---|---|---|
WHATSAPP_ACCESS_TOKEN | Yes | Meta access token with whatsapp_business_messaging and whatsapp_business_management permissions (use a System User token in production) Docs. |
WHATSAPP_PHONE_NUMBER_ID | Yes | Phone number ID of the business phone number (from WhatsApp > API Setup in the Meta app dashboard); pass it as the phoneNumberId parameter of messaging tools Docs. |
WHATSAPP_BUSINESS_ACCOUNT_ID | No | WhatsApp Business Account (WABA) ID, needed to list message templates; pass it as the wabaId parameter Docs. |
Setup
- Create a Meta app with the WhatsApp product: Sign in at https://developers.facebook.com (a free Meta developer account works), create a Business-type app, and add the WhatsApp product. Meta provisions a free test phone number and sandbox automatically.
- Get a test token and phone number ID: In WhatsApp > API Setup, copy the temporary access token and the Phone number ID for the test number. Add up to 5 verified recipient numbers for sandbox testing. Set WHATSAPP_ACCESS_TOKEN and WHATSAPP_PHONE_NUMBER_ID.
- Note your WhatsApp Business Account ID: The WABA ID is shown in WhatsApp > API Setup (and in Meta Business Suite). Set it as WHATSAPP_BUSINESS_ACCOUNT_ID if you want to list message templates.
- Create a permanent token for production: Temporary tokens expire after about 24 hours. For production, create a System User in Meta Business Suite, grant it the whatsapp_business_messaging and whatsapp_business_management permissions, generate a non-expiring token, and use it as WHATSAPP_ACCESS_TOKEN.
- Free-form text messages are only delivered within 24 hours of the customer’s last message; outside that window you must send an approved template.
- Use the internal phone number ID in API calls, not the E.164 phone number.
- New templates must be approved by Meta before they can be sent; check status with the List Message Templates tool.
Tools
| Tool | Access | Description |
|---|---|---|
| Send Text Message | Write | Send a free-form text message to a WhatsApp user (only within 24 hours of their last message; otherwise use a template) |
| Send Template Message | Write | Send an approved message template to a WhatsApp user; required to start conversations outside the 24-hour customer service window |
| Send Media Message | Write | Send an image, document, video, or audio message to a WhatsApp user by public URL or uploaded media ID (subject to the same 24-hour window as text messages) |
| Get Media URL | Read | Get a short-lived download URL and metadata for a media ID, e.g. to retrieve an image or document a customer sent inbound |
| Update Business Profile | Write | Update the business profile (about, address, description, email, websites, vertical) shown to customers for a business phone number |
| Mark Message as Read | Write | Mark an inbound WhatsApp message as read so the customer sees read receipts after the agent processes it |
| Get Business Profile | Read | Read the business profile (about, address, email, websites) shown to customers for a business phone number |
| List Message Templates | Read | List the message templates on a WhatsApp Business Account so an agent can pick an approved template name and language before sending |
Example prompts
- Send a WhatsApp message to a customer following up on their recent inquiry.
- List my approved WhatsApp message templates and summarize what each one is for.
- Show my WhatsApp business profile and suggest improvements to the description and website links.