Connects to the WhatsApp Business Cloud API. An agent can send text, template, media, interactive (buttons/list), and reaction messages, mark messages as read, fetch media URLs, and list approved message templates.
This connector's tools are also used by the whatsapp-send workflow node.
Add to an agent node's tools array with _node_type: "tool-whatsapp". See Connector Reference — How connectors are used.
Authentication
| Field | Required | Description |
|---|---|---|
access_token | Yes (or token) | System User access token from Meta Business Manager, granted whatsapp_business_messaging permission. |
token | Yes (or access_token) | Used if access_token is not set. |
phone_number_id | Yes | WhatsApp Business phone number ID (Meta Business Manager → WhatsApp → Getting Started). |
{
"name": "whatsapp",
"_node_type": "tool-whatsapp",
"access_token": "{{ secret.WHATSAPP_ACCESS_TOKEN }}",
"phone_number_id": "{{ secret.WHATSAPP_PHONE_NUMBER_ID }}"
}
Tools
whatsapp_send_text
Send a free-form text message to a WhatsApp user. Only works within the 24-hour customer service window after the user last messaged. Use whatsapp_send_template outside that window.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
to | string | Yes | Recipient phone number with country code, e.g. 14155551234 |
body | string | Yes | Message text (max 4096 chars). Only works within 24h of last customer message |
preview_url | boolean | No | Show a URL preview if the message contains a link (default false) |
reply_to_message_id | string | No | Quote-reply to a specific message ID (optional) |
Returns: A confirmation message with the new message ID and recipient.
whatsapp_send_template
Send a pre-approved WhatsApp message template. Use this for proactive outreach or messaging outside the 24-hour window. Templates must be approved in Meta Business Manager.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
to | string | Yes | Recipient phone number with country code, e.g. 14155551234 |
template_name | string | Yes | Name of the approved WhatsApp message template |
language_code | string | No | Template language code, e.g. en_US, en, hi (default en_US) |
body_params | string | No | JSON array of body parameter values, e.g. [{type:text,text:John}] |
header_params | string | No | JSON array of header parameter values (optional) |
Returns: A confirmation message with the template name, new message ID, and recipient.
whatsapp_send_media
Send a media message (image, video, audio, document, or sticker) to a WhatsApp user via a public URL.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
to | string | Yes | Recipient phone number with country code |
media_type | string | Yes | Media type: image, video, audio, document, sticker |
media_url | string | Yes | Publicly accessible URL of the media file |
caption | string | No | Caption text for image or video (optional, max 1024 chars) |
filename | string | No | Filename shown to the recipient for documents (optional) |
Returns: A confirmation message with the media type, new message ID, and recipient.
whatsapp_send_interactive
Send an interactive WhatsApp message with quick-reply buttons or a selection list. Great for menus, surveys, and guided conversations.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
to | string | Yes | Recipient phone number with country code |
body_text | string | Yes | Main message body text |
interactive_type | string | Yes | Interactive message type: button (up to 3 buttons) or list (up to 10 items) |
buttons | string | No | JSON array of buttons for type=button: [{id:btn1,title:Yes},{id:btn2,title:No}] |
list_sections | string | No | JSON list sections for type=list: [{title:Options,rows:[{id:opt1,title:Choose this}]}] |
list_button_text | string | No | Button label that opens the list (type=list only, default Choose an option) |
header_text | string | No | Optional header text shown above the message body |
footer_text | string | No | Optional footer text shown below the buttons |
Returns: A confirmation message with the interactive type, new message ID, and recipient.
whatsapp_send_reaction
React to a WhatsApp message with an emoji (e.g. thumbs up, heart). Send an empty emoji to remove an existing reaction.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
to | string | Yes | Recipient phone number with country code |
message_id | string | Yes | ID of the message to react to |
emoji | string | Yes | Unicode emoji to react with (e.g. 👍). Send empty string to remove reaction |
Returns: A confirmation message with the emoji and target message ID.
whatsapp_mark_read
Mark a WhatsApp message as read. This sends a read receipt (double blue ticks) to the sender.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
message_id | string | Yes | ID of the message to mark as read (shows blue ticks to sender) |
Returns: A confirmation message naming the message ID.
whatsapp_get_media_url
Get the download URL for a media file received in a WhatsApp message. The URL is valid for 5 minutes.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
media_id | string | Yes | Media ID from the incoming webhook message payload |
Returns: The media download URL, MIME type, and file size in bytes, with a note that the URL is valid for 5 minutes.
whatsapp_get_templates
List all message templates for a WhatsApp Business Account. Use this to find available template names before calling whatsapp_send_template.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
business_account_id | string | Yes | WhatsApp Business Account ID (WABA ID) from Meta Business Manager |
status | string | No | Filter by status: APPROVED, PENDING, REJECTED (default APPROVED) |
Returns: A list of templates as - <name> (lang: <language>, category: <category>) lines, or "No <status> templates found.".