> ## Documentation Index
> Fetch the complete documentation index at: https://botpress.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp Setup

> Add a bot to WhatsApp using the official integration.

{/* vale on */}

[Open in Hub](https://studio.botpress.cloud/home?exploreHub=1\&hubItemId=intver_01KRC1AEDCE4P5HTZP5G41495H)
*v4.15.0*

The official WhatsApp integration allows your users to chat with your bot by messaging a WhatsApp number.

## Setup

> [tab] Basic configuration
>
> > [!NOTE]
> >
> > You will need:
> >
> > * A [published bot](https://botpress.com/docs/botpress-quickstart)
> > * A [Facebook account](https://www.facebook.com/signup)
>
> > [!TIP]
> >
> > Visual learner?
> >
> > Check out our [WhatsApp Setup guide](https://www.youtube.com/watch?v=Fs6dIxgEKoY) on YouTube for a step-by-step video guide.
>
> **Step 1**
>
> In Botpress Studio, select **Explore Hub** in the upper-right corner.
>
> **Step 2**
>
> Search for the **WhatsApp** integration, then select **Install Integration**.
>
> **Step 3**
>
> In the **Configuration** menu, select **Authorize WhatsApp**.
>
> **Step 4**
>
> Follow the instructions to connect Botpress to your WhatsApp account.
>
> > [!NOTE]
> >
> > Additional requirements:
> >
> > * While setting up your WhatsApp integration, we will ask you to create or select:
> >
> >   * A [Facebook business page](https://www.facebook.com/business/help/1968057156746246?id=939256796236247)
> >   * A [WhatsApp business account](https://business.whatsapp.com)
> > * After setup is complete, your business will undergo a [verification process by Meta](https://www.facebook.com/business/help/1095661473946872?id=180505742745347), the parent company of WhatsApp. This verification confirms the identity and eligibility of your business to use Meta's platforms.

> [tab] Manual configuration
>
> For advanced use cases, you can use your own Meta app with our integration.
>
> > [!NOTE]
> >
> > You will need:
> >
> > * A [Meta developer app](https://developers.facebook.com/apps/creation/) with the . Check out the [Meta developer documentation](https://developers.facebook.com/docs/whatsapp/cloud-api/get-started#set-up-developer-assets) to learn more about the setup process.
>
> ### Step 1: Install the integration in Botpress
>
> **Step 1**
>
> In Botpress Studio, select **Explore Hub** in the upper-right corner.
>
> **Step 2**
>
> Search for the **WhatsApp** integration, then select **Install Integration**.
>
> **Step 3**
>
> In the **Configuration** menu, open the drop-down menu and select **Manual Configuration**.
>
> ### Step 2: Configure the integration
>
> Next, fill in the integration's configuration fields using information from your Meta app:
>
> > [accordion] Verify Token
> >
> > Used by Meta to verify that you're the real owner of the provided webhook. Can be any alphanumeric string.
>
> > [accordion] Access Token
> >
> > **Step 1**
> >
> > In your Meta app's left sidebar, go to **Use cases > Connect with customers through WhatsApp > Customize**.
> >
> > > [!NOTE]
> > >
> > > If you haven't added WhatsApp as a use case yet, select **Add use cases**, then **Connect with customers through WhatsApp**.
> >
> > **Step 2**
> >
> > Select a WhatsApp business portfolio (if you haven't already).
> >
> > **Step 3**
> >
> > Go to **API testing**.
> >
> > **Step 4**
> >
> > Select **Generate access token**, then copy the token.
> >
> > **Step 5**
> >
> > In Botpress, paste the token into the integration's **Access Token** configuration field.
>
> > [accordion] Client Secret
> >
> > **Step 1**
> >
> > In your Meta App's left sidebar, expand the **App Settings** menu and select **Basic**.
> >
> > **Step 2**
> >
> > In the **App Secret** field,  select **Show**, then copy your secret.
> >
> > **Step 3**
> >
> > In Botpress, paste the secret into the integration's **Client Secret** configuration field.
>
> > [accordion] Default Bot Phone Number ID
> >
> > **Step 1**
> >
> > In your Meta app's left sidebar, go to **Use cases > Connect with customers through WhatsApp > Customize**.
> >
> > > [!NOTE]
> > >
> > > If you haven't added WhatsApp as a use case yet, select **Add use cases**, then **Connect with customers through WhatsApp**.
> >
> > **Step 2**
> >
> > Select a WhatsApp business portfolio (if you haven't already).
> >
> > **Step 3**
> >
> > Go to **API testing**.
> >
> > **Step 4**
> >
> > Under **Select a 'From' phone number**, copy the **Phone number ID**.
> >
> > **Step 5**
> >
> > In Botpress, paste the ID into the integration's **Default Bot Phone Number ID** configuration field.
>
> > [accordion] WABA ID (WhatsApp Business Account ID)
> >
> > **Step 1**
> >
> > In your Meta app's left sidebar, go to **Use cases > Connect with customers through WhatsApp > Customize**.
> >
> > > [!NOTE]
> > >
> > > If you haven't added WhatsApp as a use case yet, select **Add use cases**, then **Connect with customers through WhatsApp**.
> >
> > **Step 2**
> >
> > Select a WhatsApp business portfolio (if you haven't already).
> >
> > **Step 3**
> >
> > Go to **API testing**.
> >
> > **Step 4**
> >
> > Under **Select a 'From' phone number**, copy the **WhatsApp Business Account ID**.
> >
> > **Step 5**
> >
> > In Botpress, paste the ID into the integration's **WhatsApp Business Account ID** configuration field.
>
> When you've filled in all the fields, select **Save Configuration**. This will automatically enable your integration.
>
> ### Step 3: Add your webhook
>
> Now that you've enabled your integration, you can add your webhook to your Meta app's configuration:
>
> **Step 1**
>
> In Botpress, copy the webhook URL and **Verify Token** from the integration's **Configuration** section.
>
> **Step 2**
>
> In your Meta app's left sidebar, go to **Use cases > Connect with customers through WhatsApp > Customize**.
>
> > [!NOTE]
> >
> > If you haven't added WhatsApp as a use case yet, select **Add use cases**, then **Connect with customers through WhatsApp**.
>
> **Step 3**
>
> Select a WhatsApp business portfolio (if you haven't already).
>
> **Step 4**
>
> Go to **Configuration**.
>
> **Step 5**
>
> Paste the webhook URL into the **Callback URL** field.
>
> **Step 6**
>
> Paste your **Verify Token** in the **Verify Token** field.
>
> **Step 7**
>
> Select **Verify and save**. Then, subscribe to the following webhook fields:
>
> * `message_template_components_update`
>
> * `message_template_quality_update`
>
> * `message_template_status_update`
>
> * `messages`
>
> * `template_category_update`
>
> > [!TIP]
> >
> > You've manually configured your WhatsApp integration!
> >
> > For more information, check out WhatsApp's guide on [getting started with Cloud API](https://developers.facebook.com/docs/whatsapp/cloud-api/get-started#send-test-message).

> [tab] Playground
>
> If you want to test your bot's behaviour in WhatsApp before going through the actual setup process, you can use the WhatsApp integration playground.
>
> > [!NOTE]
> >
> > You will need:
> >
> > * A [published bot](https://botpress.com/docs/botpress-quickstart)
> > * A [WhatsApp account](https://web.whatsapp.com)
>
> **Step 1**
>
> In Botpress Studio, select **Explore Hub** in the upper-right corner.
>
> **Step 2**
>
> Search for the **WhatsApp** integration, then select **Install Integration**.
>
> **Step 3**
>
> Select **Test your agent on WhatsApp**.
>
> **Step 4**
>
> Follow the instructions to set up the playground.

***

## Cards

> [!WARNING]
>
> Some of the integration's Cards use [WhatsApp message templates](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/) to send messages to users.
>
> In WhatsApp, these templates support both [named and positional parameters](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/#parameter-formats). However, the integration currently only supports positional parameters. This means you'll get an error if you try to provide named parameters in a Card's `conversation.templateVariablesJson` field.

{/* vale off */}

Here's a reference for all [Cards](https://botpress.com/docs/studio/concepts/cards/introduction.md) available with the integration:

### List Message Templates

Lists WhatsApp message templates from the connected WhatsApp Business Account, including parameter schemas and approval status

**input** `object`

**status** `enum\<string\>`

Filter templates by approval status. Returns all statuses if not specified.

Available options: `APPROVED`, `PENDING`, `REJECTED`, `PAUSED`, `DISABLED`, `ARCHIVED`, `LIMIT_EXCEEDED`, `IN_APPEAL`

**name** `string`

Filter templates by exact name match.

**limit** `number` (default: 20)

Maximum number of templates to return per page (default: 20, max: 100).

**nextCursor** `string`

Cursor for fetching the next page of results. Obtained from a previous listTemplates call.

**output** `object`

**templates** `array` *required*

Array of message templates

**array item properties**

**id** `string` *required*

Unique identifier of the template

**name** `string` *required*

Name of the message template

**status** `string` *required*

Approval status of the template

**category** `string` *required*

Category of the template (e.g. MARKETING, UTILITY, AUTHENTICATION)

**language** `string` *required*

Language and locale code of the template

**components** `array` *required*

Array of template components (HEADER, BODY, FOOTER, BUTTONS)

**array item properties**

**type** `string` *required*

Component type (HEADER, BODY, FOOTER, BUTTONS)

**format** `string`

Format of the component (e.g. TEXT, IMAGE, VIDEO for HEADER)

**text** `string`

Text content of the component, may contain \{\{N}} placeholders

**buttons** `array`

Array of button objects (only present for BUTTONS component type)

**array item properties**

**type** `string` *required*

Type of button (QUICK\_REPLY, URL, PHONE\_NUMBER, etc.)

**text** `string`

Label text of the button

**url** `string`

URL for URL-type buttons, may contain \{\{1}} placeholder

**phone\_number** `string`

Phone number for PHONE\_NUMBER-type buttons

**example** `object`

Example values for the component parameters

**nextCursor** `string`

Cursor for fetching the next page. Undefined if no more pages.

### Send Template Message

Sends a WhatsApp Message Template to a user in an existing conversation

**input** `object`

**conversation** `object` *required*

Details of the conversation

**userPhone** `string` *required*

Phone number of the WhatsApp user to start a conversation with. Add the country code (e.g. +81 for japan)

**templateName** `string` *required*

Name of the WhatsApp Message Template to start the conversation with

**templateLanguage** `string`

Language of the WhatsApp Message Template to start the conversation with. Defaults to "en" (English)

**templateVariablesJson** `string`

Deprecated: use templateBodyParams instead. JSON array of body variable values: \["val1", "val2"].

**templateHeaderParams** `object | object | object | object`

Header parameter. For text headers: type="text", value is the replacement text, parameterName is optional (for named params). For media headers: type="image"|"video"|"document", url is the media URL. Documents may include a filename.

**templateBodyParams** `object | object`

Body parameters. For positional params (\{\{1}}, \{\{2}}, ...): type="positional", values is an ordered array of strings. For named params (\{\{buyer\_name}}): type="named", values is a record mapping param names to values.

**templateButtonParams** `array`

Button parameters as an ordered array. url: value is the URL suffix. quick\_reply: payload is the callback data. copy\_code: code is the coupon code. skip: no parameter needed (for phone number buttons, etc.).

> [tab] url
>
> **type** `string` *required*
>
> **value** `string` *required*

> [tab] quick\_reply
>
> **type** `string` *required*
>
> **payload** `string` *required*

> [tab] copy\_code
>
> **type** `string` *required*
>
> **code** `string` *required*

> [tab] skip
>
> **type** `string` *required*

**botPhoneNumberId** `string`

Phone number ID to use as sender (uses the default phone number ID if not provided)

**output** `object`

**conversationId** `string` *required*

ID of the conversation created

**messageId** `string`

ID of the message created

### Start Conversation

Proactively starts a conversation with a WhatsApp user by sending them a message using a WhatsApp Message Template

**input** `object`

**conversation** `object` *required*

Details of the conversation

**userPhone** `string` *required*

Phone number of the WhatsApp user to start a conversation with. Add the country code (e.g. +81 for japan)

**templateName** `string` *required*

Name of the WhatsApp Message Template to start the conversation with

**templateLanguage** `string`

Language of the WhatsApp Message Template to start the conversation with. Defaults to "en" (English)

**templateVariablesJson** `string`

Deprecated: use templateBodyParams instead. JSON array of body variable values: \["val1", "val2"].

**templateHeaderParams** `object | object | object | object`

Header parameter. For text headers: type="text", value is the replacement text, parameterName is optional (for named params). For media headers: type="image"|"video"|"document", url is the media URL. Documents may include a filename.

**templateBodyParams** `object | object`

Body parameters. For positional params (\{\{1}}, \{\{2}}, ...): type="positional", values is an ordered array of strings. For named params (\{\{buyer\_name}}): type="named", values is a record mapping param names to values.

**templateButtonParams** `array`

Button parameters as an ordered array. url: value is the URL suffix. quick\_reply: payload is the callback data. copy\_code: code is the coupon code. skip: no parameter needed (for phone number buttons, etc.).

> [tab] url
>
> **type** `string` *required*
>
> **value** `string` *required*

> [tab] quick\_reply
>
> **type** `string` *required*
>
> **payload** `string` *required*

> [tab] copy\_code
>
> **type** `string` *required*
>
> **code** `string` *required*

> [tab] skip
>
> **type** `string` *required*

**botPhoneNumberId** `string`

Phone number ID to use as sender (uses the default phone number ID if not provided)

**output** `object`

**conversationId** `string` *required*

The Botpress ID of the created conversation

**messageId** `string`

ID of the message created

***

## Triggers

{/* vale off */}

Here's a reference for all [Triggers](https://botpress.com/docs/studio/concepts/triggers.md) available with the integration:

> [!TIP]
>
> You can access data returned from any of these Triggers by reading `event.payload` after the Trigger fires.

### Message Delivered

Triggered when a message is delivered to a user

**payload** `object`

This Trigger has no payload.

### Message Failed

Triggered when a message fails to be delivered

**payload** `object`

**error** `string` *required*

Error details describing why the message failed

### Message Read

Triggered when a user reads a message

**payload** `object`

This Trigger has no payload.

### Message Sent

Triggered when a message is sent

**payload** `object`

This Trigger has no payload.

### Message Template Components Update

Triggered when a template is edited

**payload** `object`

The message\_template\_components\_update webhook notifies you of changes to a template's components.

**id** `number` *required*

Template ID.

**name** `string` *required*

Template name.

**language** `string` *required*

Template language and locale code.

**element** `string` *required*

Template body text.

**title** `string`

Template Header Text.

**footer** `string`

Template Footer Text.

**buttons** `array`

Array of button objects, if present.

**array item properties**

**button\_type** `enum\<string\>` *required*

Button type.

Available options: `CATALOG`, `COPY_CODE`, `EXTENSION`, `FLOW`, `MPM`, `ORDER_DETAILS`, `OTP`, `PHONE_NUMBER`, `POSTBACK`, `REMINDER`, `SEND_LOCATION`, `SPM`, `QUICK_REPLY`, `URL`, `VOICE_CALL`

**button\_text** `string` *required*

Button label text.

**button\_url** `string`

Button URL.

**button\_phone\_number** `string`

Button phone number.

### Message Template Quality Update

Triggered when a template's quality score changes

**payload** `object`

The message\_template\_quality\_update webhook notifies you of changes to a template's quality score.

**previous\_quality\_score** `enum\<string\>` *required*

Previous template quality score.

Available options: `GREEN`, `RED`, `YELLOW`, `UNKNOWN`

**new\_quality\_score** `enum\<string\>` *required*

New template quality score.

Available options: `GREEN`, `RED`, `YELLOW`, `UNKNOWN`

**id** `number` *required*

Template ID.

**name** `string` *required*

Template name.

**language** `string` *required*

Template language and locale code.

### Message Template Status Update

Triggered when a template is approved, rejected or disabled

**payload** `object`

The message\_template\_status\_update webhook notifies you of changes to the status of an existing template.

**event** `enum\<string\>` *required*

Template status event.

Available options: `APPROVED`, `ARCHIVED`, `DELETED`, `DISABLED`, `FLAGGED`, `IN_APPEAL`, `LIMIT_EXCEEDED`, `LOCKED`, `PAUSED`, `PENDING`, `REINSTATED`, `PENDING_DELETION`, `REJECTED`

**id** `number` *required*

Template ID.

**name** `string` *required*

Template name.

**language** `string` *required*

Language and locale code.

**reason** `string | null` *required*

**disable\_info** `object`

only included if template disabled

**disable\_date** `number` *required*

Unix timestamp indicating when the template was disabled.

**other\_info** `object`

only included if template locked or unlocked

**title** `enum\<string\>` *required*

Title of template pause or unpause event.

Available options: `FIRST_PAUSE`, `SECOND_PAUSE`, `RATE_LIMITING_PAUSE`, `UNPAUSE`, `DISABLED`

**description** `string` *required*

String describing why the template was locked or unlocked.

### Message Echo Received

Triggered when an outbound message sent through another channel (e.g. a human agent) is echoed back via the webhook

**payload** `object`

This Trigger has no payload.

### Reaction Added

Triggered when a user adds a reaction to a message

**payload** `object`

**reaction** `string` *required*

The reaction that was added

**messageId** `string` *required*

ID of the message that was reacted to

**userId** `string`

ID of the user who added the reaction

**conversationId** `string`

ID of the conversation

### Reaction Removed

Triggered when a user removes a reaction from a message

**payload** `object`

**reaction** `string` *required*

The reaction that was removed

**messageId** `string` *required*

ID of the message that was reacted to

**userId** `string`

ID of the user who removed the reaction

**conversationId** `string`

ID of the conversation

### Template Category Update

Triggered when the category of a WhatsApp template is changed — whether manually or by an automated process, or when such a change is about to occur.

**payload** `object`

The template\_category\_update webhook notifies you of changes to template's category.

**id** `number` *required*

Template ID.

**name** `string` *required*

Template name.

**language** `string` *required*

Template language and locale code.

**correct\_category** `string`

The category that the template will be recategorized as in 24 hours.

**previous\_category** `string`

The template's previous category.

**new\_category** `string`

The template's new category.

***

## Troubleshooting

> [accordion] Not receiving messages from bot on WhatsApp
>
> Until Meta has verified your business, your bot won't be able to send messages to WhatsApp users, even if you've configured it correctly.
>
> If you need to test out your bot right away, you can use the [WhatsApp Playground](#playground) while waiting for business verification.

> [accordion] Meta business verification taking too long
>
> Unfortunately, we can't help speed up Meta's business verification process.
>
> If you need to test out your bot right away, you can use the [WhatsApp Playground](#playground) while waiting for business verification.

> [accordion] Bot receiving WhatsApp messages, but not sending messages back
>
> There may be a problem with the payment method in your WhatsApp business account. Check the billing hub and make sure your [payment method](https://business.facebook.com/billing_hub/) is configured correctly.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.