WhatsApp

{/* Generated by scripts/generate-integration-catalog.mjs. Do not edit by hand. */}

At a glance

  • Availability: Experimental (how to enable).
  • Authentication: API key.
  • Connection: The key from WHATSAPP_ACCESS_TOKEN is sent as the Bearer prefixed Authorization header.
  • Provider documentation: Authentication reference.

Credentials

Set these per environment. See Connect an integration.

VariableRequiredDescription
WHATSAPP_ACCESS_TOKENYesMeta access token with whatsapp_business_messaging and whatsapp_business_management permissions (use a System User token in production) Docs.
WHATSAPP_PHONE_NUMBER_IDNoPhone 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_IDNoWhatsApp Business Account (WABA) ID, needed to list message templates; pass it as the wabaId parameter Docs.

Setup

  1. 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.
  2. 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.
  3. 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.
  4. 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.

Provider notes

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

Provider API reference.

Tools

ToolAccessDescription
Send Text Message<br /><code className="reference-identifier">whatsapp__send_text_message</code>WriteSend text within 24-hour window
Send Template Message<br /><code className="reference-identifier">whatsapp__send_template_message</code>WriteSend template to start conversation
Send Media Message<br /><code className="reference-identifier">whatsapp__send_media_message</code>WriteSend media within 24-hour window
Get Media URL<br /><code className="reference-identifier">whatsapp__get_media_url</code>ReadGet temporary media download URL
Update Business Profile<br /><code className="reference-identifier">whatsapp__update_business_profile</code>WriteUpdate business profile
Mark Message as Read<br /><code className="reference-identifier">whatsapp__mark_message_read</code>WriteMark message as read
Get Business Profile<br /><code className="reference-identifier">whatsapp__get_business_profile</code>ReadGet business profile
List Message Templates<br /><code className="reference-identifier">whatsapp__list_message_templates</code>ReadList message templates

Verify the connection

Call a read tool such as whatsapp__get_media_url with arguments for your account. Confirm that the result comes from the intended account or workspace before enabling write tools.