> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/integrations/catalog/whatsapp-business.md).

# WhatsApp Business

WhatsApp Business Cloud API by Meta. Send text, template, interactive, and media messages, and trigger workflows on incoming messages and status updates.

## Connectors

Choose the connector that matches your authentication method. The options below use the names shown in StackAI.

| Connector         | Authentication |
| ----------------- | -------------- |
| WhatsApp Business | Access Token   |

### WhatsApp Business

Connect to the WhatsApp Business Cloud API to send messages and receive inbound message events. Requires a Meta System User access token, Phone Number ID, and WhatsApp Business Account ID.

#### Set up in WhatsApp Business

1. Prepare the WhatsApp Business account or service that the workflow will access. Grant access to the required resources and operations.
2. **Access Token:** A System User access token with the whatsapp\_business\_messaging permission, from Meta Business Suite > System Users.
3. **Phone Number ID:** The Phone Number ID of your WhatsApp sender, from the Meta App dashboard > WhatsApp > API Setup.
4. **WhatsApp Business Account ID:** The WhatsApp Business Account (WABA) ID that owns the phone number, from the Meta App dashboard > WhatsApp > API Setup.

#### Set up in StackAI

1. Open **Settings → Connections**, add a connection, and select **WhatsApp Business**.
2. Enter the credentials and connection details in the fields below.
3. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

**Connection fields**

| StackAI field                | Required | What to enter                                                                                                                                                                                        |
| ---------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Access Token                 | Yes      | A System User access token with the whatsapp\_business\_messaging permission, from Meta Business Suite > System Users. [Provider instructions](https://business.facebook.com/settings/system-users). |
| Phone Number ID              | Yes      | The Phone Number ID of your WhatsApp sender, from the Meta App dashboard > WhatsApp > API Setup. [Provider instructions](https://developers.facebook.com/apps/).                                     |
| WhatsApp Business Account ID | Yes      | The WhatsApp Business Account (WABA) ID that owns the phone number, from the Meta App dashboard > WhatsApp > API Setup. [Provider instructions](https://developers.facebook.com/apps/).              |

### Verify the connection

Check that the connection is healthy. Then run a read operation against a resource the connected account can access. A successful connection check confirms authentication; it does not guarantee permission for every action.

If access is denied, check the credential or OAuth permissions, the selected account or environment, and access to the specific resource. Update expired credentials or reconnect after permissions change.

## Use an action

1. Add the required **WhatsApp Business** action to the workflow.
2. Select a connection when the action requests one.
3. Complete the required fields. Use the reference picker when a value comes from another workflow step.
4. Run the workflow and inspect the action’s output. Check the result before using it in a later step.

## Actions

### Send Text Message

Send a WhatsApp text message

#### Inputs

| Field           | Type     | Required | Description                                                                                                                                                           |
| --------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| To Phone Number | string   | Yes      | The recipient's phone number in international format (e.g. +18575295760). Only works within the 24-hour customer service window; otherwise use Send Template Message. |
| Message Body    | textarea | Yes      | The text content of the message (up to 4096 characters).                                                                                                              |
| Preview URLs    | boolean  | No       | Render a link preview when the body contains a URL. Default: false.                                                                                                   |

#### Outputs

| Field                 | Type   | Description                                      |
| --------------------- | ------ | ------------------------------------------------ |
| Message ID            | string | The unique WhatsApp message identifier (wamid).  |
| Recipient WhatsApp ID | string | The recipient's WhatsApp ID as resolved by Meta. |

### Send Template Message

Send a pre-approved WhatsApp template message

#### Inputs

| Field           | Type            | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| --------------- | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| To Phone Number | string          | Yes      | The recipient's phone number in international format (e.g. +18575295760).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Template Name   | string          | Yes      | The name of a pre-approved message template from your WhatsApp Business Account (e.g. 'order\_confirmation').                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| Language Code   | select (string) | Yes      | The template's language/locale code. Must match the code the template was approved under (e.g. 'en\_US'). Available values: Afrikaans (af), Albanian (sq), Arabic (ar), Azerbaijani (az), Bengali (bn), Bulgarian (bg), Catalan (ca), Chinese (China) (zh\_CN), Chinese (Hong Kong) (zh\_HK), Chinese (Taiwan) (zh\_TW), Croatian (hr), Czech (cs), Danish (da), Dutch (nl), English (en), English (UK) (en\_GB), English (US) (en\_US), Estonian (et), Filipino (fil), Finnish (fi), French (fr), Georgian (ka), German (de), Greek (el), Gujarati (gu), Hausa (ha), Hebrew (he), Hindi (hi), Hungarian (hu), Indonesian (id), Irish (ga), Italian (it), Japanese (ja), Kannada (kn), Kazakh (kk), Kinyarwanda (rw\_RW), Korean (ko), Kyrgyz (Kyrgyzstan) (ky\_KG), Lao (lo), Latvian (lv), Lithuanian (lt), Macedonian (mk), Malay (ms), Malayalam (ml), Marathi (mr), Norwegian (nb), Persian (fa), Polish (pl), Portuguese (Brazil) (pt\_BR), Portuguese (Portugal) (pt\_PT), Punjabi (pa), Romanian (ro), Russian (ru), Serbian (sr), Sinhala (si), Slovak (sk), Slovenian (sl), Spanish (es), Spanish (Argentina) (es\_AR), Spanish (Spain) (es\_ES), Spanish (Mexico) (es\_MX), Swahili (sw), Swedish (sv), Tamil (ta), Telugu (te), Thai (th), Turkish (tr), Ukrainian (uk), Urdu (ur), Uzbek (uz), Vietnamese (vi), Zulu (zu). Default: en\_US. |
| Components      | array           | No       | Optional list of template components for variable substitution. Each entry is an object such as {"type": "body", "parameters": \[{"type": "text", "text": "John"}]}.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

#### Outputs

| Field                 | Type   | Description                                      |
| --------------------- | ------ | ------------------------------------------------ |
| Message ID            | string | The unique WhatsApp message identifier (wamid).  |
| Recipient WhatsApp ID | string | The recipient's WhatsApp ID as resolved by Meta. |

### Send Interactive Message

Send a WhatsApp interactive message with reply buttons or a list

#### Inputs

| Field            | Type            | Required | Description                                                                                                                                                                                                                                        |
| ---------------- | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| To Phone Number  | string          | Yes      | The recipient's phone number in international format (e.g. +18575295760).                                                                                                                                                                          |
| Interactive Type | select (string) | Yes      | Either 'button' (up to 3 reply buttons) or 'list' (a menu of options). Available values: Reply Buttons, List. Default: button.                                                                                                                     |
| Body Text        | textarea        | Yes      | The main body text shown above the buttons or list.                                                                                                                                                                                                |
| Action           | object          | Yes      | A JSON object for the interactive action. For buttons: {"buttons": \[{"type": "reply", "reply": {"id": "yes", "title": "Yes"}}]}. For lists: {"button": "Menu", "sections": \[{"title": "Section", "rows": \[{"id": "1", "title": "Option 1"}]}]}. |
| Header Text      | string          | No       | Optional short header text.                                                                                                                                                                                                                        |
| Footer Text      | string          | No       | Optional short footer text.                                                                                                                                                                                                                        |

#### Outputs

| Field                 | Type   | Description                                      |
| --------------------- | ------ | ------------------------------------------------ |
| Message ID            | string | The unique WhatsApp message identifier (wamid).  |
| Recipient WhatsApp ID | string | The recipient's WhatsApp ID as resolved by Meta. |

### Send Media Message

Send a WhatsApp media message (image, document, audio, video, or sticker)

#### Inputs

| Field           | Type            | Required | Description                                                                                                               |
| --------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------- |
| To Phone Number | string          | Yes      | The recipient's phone number in international format (e.g. +18575295760).                                                 |
| Media Type      | select (string) | Yes      | One of: image, document, audio, video, sticker. Available values: Image, Document, Audio, Video, Sticker. Default: image. |
| Media URL       | string          | No       | A public HTTPS URL to the media file. Provide either this or a Media ID.                                                  |
| Media ID        | string          | No       | The ID of media previously uploaded to WhatsApp. Provide either this or a Media URL.                                      |
| Caption         | string          | No       | Optional caption (image, document, and video only).                                                                       |
| Filename        | string          | No       | Optional filename shown to the recipient (documents only).                                                                |

#### Outputs

| Field                 | Type   | Description                                      |
| --------------------- | ------ | ------------------------------------------------ |
| Message ID            | string | The unique WhatsApp message identifier (wamid).  |
| Recipient WhatsApp ID | string | The recipient's WhatsApp ID as resolved by Meta. |

### Mark Message As Read

Mark an inbound WhatsApp message as read (blue ticks)

#### Inputs

| Field      | Type   | Required | Description                                                                                                              |
| ---------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| Message ID | string | Yes      | The WhatsApp message id (wamid) of an inbound message to mark as read. Typically taken from an incoming message trigger. |

#### Outputs

| Field   | Type    | Description                                          |
| ------- | ------- | ---------------------------------------------------- |
| Success | boolean | Whether the message was successfully marked as read. |

## Triggers

A trigger starts a workflow when its configured event occurs. Configure the event and filters before enabling the trigger.

### On Event

Trigger a workflow on WhatsApp Business webhook events: incoming messages (any type), delivery statuses, errors, and template, phone-number, and account notifications.

This trigger has its own webhook URL. In **your** Meta App ([developers.facebook.com/apps](https://developers.facebook.com/apps/)) under **WhatsApp > Configuration**: 1. Set the **Callback URL** to: {{webhook\_url}} 2. Set the **Verify token** to the same value you entered in this trigger's **Webhook Verify Token** setting. 3. Click **Verify and Save**, then subscribe to the webhook fields you selected under **Event Types** — at minimum the **messages** field, plus any template, phone-number, or account fields you chose. Note: a Meta App allows only one callback URL, so use one WhatsApp trigger per Meta App. Attachments: incoming media (PDFs, images, documents, audio) is downloaded automatically and exposed as the **File** and **File URL** outputs, ready to use in other nodes. WhatsApp sends one attachment per message, so several files sent together arrive as separate events — the workflow runs once per file.

#### Configuration

| Field                | Type                      | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| -------------------- | ------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Webhook Verify Token | secret                    | Yes      | A token you choose. Enter this same value as the Verify token in your Meta App > WhatsApp > Configuration when pointing the webhook at this trigger's URL.                                                                                                                                                                                                                                                                                                                                                                                                                               |
| Event Types          | multiple\_select (string) | No       | Which WhatsApp webhook events to capture. Defaults to incoming messages. Message status updates and errors ride on the 'messages' field; the template, phone-number, and account options require subscribing to those extra fields in your Meta App. Available values: Incoming Messages, Message Status Updates, Errors, Template Status Update, Template Quality Update, Template Category Update, Phone Number Name Update, Phone Number Quality Update, Account Update, Account Review Update, Account Alerts, Business Capability Update, User Preferences. Default: \["messages"]. |

#### Event inputs

| Field                  | Type        | Required | Description                                                                       |
| ---------------------- | ----------- | -------- | --------------------------------------------------------------------------------- |
| Event Category         | string      | Yes      | The kind of event: message, status, error, template, phone\_number, or account.   |
| Event Field            | string      | No       | The exact WhatsApp webhook field name that produced this event. Default: .        |
| Phone Number ID        | string      | No       | The Phone Number ID the event relates to (message-field events). Default: .       |
| Message ID             | string      | No       | The WhatsApp message id (wamid) for a message or status event. Default: .         |
| Timestamp              | string      | No       | The Unix timestamp (seconds) of the event. Default: .                             |
| Raw Event              | dict        | No       | The complete source object for this event (message or change value).              |
| From                   | string      | No       | The sender's WhatsApp ID (message events). Default: .                             |
| Message Type           | string      | No       | The message type (text, image, location, etc.) for message events. Default: .     |
| Text                   | string      | No       | The message text or best-effort text (message events). Default: .                 |
| Profile Name           | string      | No       | The sender's WhatsApp profile name (message events). Default: .                   |
| Media ID               | string      | No       | The media id for image/video/audio/document/sticker messages. Default: .          |
| Media MIME Type        | string      | No       | The MIME type of the media (message events). Default: .                           |
| Media Filename         | string      | No       | The filename of a document message. Default: .                                    |
| Media Caption          | string      | No       | The caption attached to a media message. Default: .                               |
| Media SHA256           | string      | No       | The SHA-256 hash of the media content. Default: .                                 |
| Files                  | files       | No       | The downloaded media file, ready to use in other nodes.                           |
| File URL               | string      | No       | A direct download URL for the media file, if any. Default: .                      |
| Latitude               | string      | No       | The latitude of a location message. Default: .                                    |
| Longitude              | string      | No       | The longitude of a location message. Default: .                                   |
| Location Name          | string      | No       | The name of a location message. Default: .                                        |
| Location Address       | string      | No       | The address of a location message. Default: .                                     |
| Reaction Emoji         | string      | No       | The emoji of a reaction message. Default: .                                       |
| Reacted Message ID     | string      | No       | The id of the message a reaction was applied to. Default: .                       |
| Reply ID               | string      | No       | The id of a selected interactive reply (button/list). Default: .                  |
| Reply Payload          | string      | No       | The payload of a template quick-reply button. Default: .                          |
| Context Message ID     | string      | No       | The id of the message this message replies to. Default: .                         |
| Referral Source URL    | string      | No       | The source URL of a click-to-WhatsApp ad referral. Default: .                     |
| Referral CTWA Click ID | string      | No       | The click id of a click-to-WhatsApp ad referral. Default: .                       |
| Referral Headline      | string      | No       | The headline of a click-to-WhatsApp ad referral. Default: .                       |
| Contacts               | dict\_array | No       | The shared contacts of a contacts message.                                        |
| Order                  | dict        | No       | The order payload of an order message.                                            |
| System Body            | string      | No       | The description of a system message (e.g. number change). Default: .              |
| Status                 | string      | No       | The delivery status (sent, delivered, read, failed) for status events. Default: . |
| Recipient ID           | string      | No       | The recipient's WhatsApp ID (status events). Default: .                           |
| Error Code             | string      | No       | The WhatsApp error code (error events). Default: .                                |
| Error Title            | string      | No       | The WhatsApp error title (error events). Default: .                               |
| Error Message          | string      | No       | The WhatsApp error message/details (error events). Default: .                     |
| Template Name          | string      | No       | The message template name (template events). Default: .                           |
| Template Status        | string      | No       | The new template status or quality event (template events). Default: .            |
| Template Language      | string      | No       | The template language (template events). Default: .                               |
| Template Category      | string      | No       | The template category (template category events). Default: .                      |
| Template Reason        | string      | No       | The reason for a template status change. Default: .                               |
| Display Phone Number   | string      | No       | The display phone number (phone-number events). Default: .                        |
| Quality Rating         | string      | No       | The phone-number quality rating or event. Default: .                              |
| Current Limit          | string      | No       | The current messaging limit tier (phone-number events). Default: .                |
| Account Event          | string      | No       | The account event or decision (account events). Default: .                        |
| Alert Severity         | string      | No       | The severity of an account alert. Default: .                                      |
| Alert Description      | string      | No       | The description of an account alert. Default: .                                   |

#### Outputs

| Field                  | Type        | Description                                                                     |
| ---------------------- | ----------- | ------------------------------------------------------------------------------- |
| Event Category         | string      | The kind of event: message, status, error, template, phone\_number, or account. |
| Event Field            | string      | The exact WhatsApp webhook field name that produced this event.                 |
| Phone Number ID        | string      | The Phone Number ID the event relates to (message-field events).                |
| Message ID             | string      | The WhatsApp message id (wamid) for a message or status event.                  |
| Timestamp              | string      | The Unix timestamp (seconds) of the event.                                      |
| Raw Event              | dict        | The complete source object for this event (message or change value).            |
| From                   | string      | The sender's WhatsApp ID (message events).                                      |
| Message Type           | string      | The message type (text, image, location, etc.) for message events.              |
| Text                   | string      | The message text or best-effort text (message events).                          |
| Profile Name           | string      | The sender's WhatsApp profile name (message events).                            |
| Media ID               | string      | The media id for image/video/audio/document/sticker messages.                   |
| Media MIME Type        | string      | The MIME type of the media (message events).                                    |
| Media Filename         | string      | The filename of a document message.                                             |
| Media Caption          | string      | The caption attached to a media message.                                        |
| Media SHA256           | string      | The SHA-256 hash of the media content.                                          |
| Files                  | files       | The downloaded media file, ready to use in other nodes.                         |
| File URL               | string      | A direct download URL for the media file, if any.                               |
| Latitude               | string      | The latitude of a location message.                                             |
| Longitude              | string      | The longitude of a location message.                                            |
| Location Name          | string      | The name of a location message.                                                 |
| Location Address       | string      | The address of a location message.                                              |
| Reaction Emoji         | string      | The emoji of a reaction message.                                                |
| Reacted Message ID     | string      | The id of the message a reaction was applied to.                                |
| Reply ID               | string      | The id of a selected interactive reply (button/list).                           |
| Reply Payload          | string      | The payload of a template quick-reply button.                                   |
| Context Message ID     | string      | The id of the message this message replies to.                                  |
| Referral Source URL    | string      | The source URL of a click-to-WhatsApp ad referral.                              |
| Referral CTWA Click ID | string      | The click id of a click-to-WhatsApp ad referral.                                |
| Referral Headline      | string      | The headline of a click-to-WhatsApp ad referral.                                |
| Contacts               | dict\_array | The shared contacts of a contacts message.                                      |
| Order                  | dict        | The order payload of an order message.                                          |
| System Body            | string      | The description of a system message (e.g. number change).                       |
| Status                 | string      | The delivery status (sent, delivered, read, failed) for status events.          |
| Recipient ID           | string      | The recipient's WhatsApp ID (status events).                                    |
| Error Code             | string      | The WhatsApp error code (error events).                                         |
| Error Title            | string      | The WhatsApp error title (error events).                                        |
| Error Message          | string      | The WhatsApp error message/details (error events).                              |
| Template Name          | string      | The message template name (template events).                                    |
| Template Status        | string      | The new template status or quality event (template events).                     |
| Template Language      | string      | The template language (template events).                                        |
| Template Category      | string      | The template category (template category events).                               |
| Template Reason        | string      | The reason for a template status change.                                        |
| Display Phone Number   | string      | The display phone number (phone-number events).                                 |
| Quality Rating         | string      | The phone-number quality rating or event.                                       |
| Current Limit          | string      | The current messaging limit tier (phone-number events).                         |
| Account Event          | string      | The account event or decision (account events).                                 |
| Alert Severity         | string      | The severity of an account alert.                                               |
| Alert Description      | string      | The description of an account alert.                                            |

## Important behavior

Actions that create, update, send, or delete data can change the connected service. Review their inputs before running them. A retry can repeat an operation; consider this when configuring retries for actions that change data.

The catalog lists the fields and capabilities available in the supplied provider definition. Availability can also depend on your deployment and organization’s Feature Access settings.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/integrations/catalog/whatsapp-business.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
