WhatsApp Setup

Open in Hub v4.18.0

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

Setup

You will need:

A published bot
A Facebook account

Visual learner?

Check out our WhatsApp Setup guide on YouTube for a step-by-step video guide.

In Botpress Studio, select Explore Hub in the upper-right corner.

Search for the WhatsApp integration, then select Install Integration.

In the Configuration menu, select Authorize WhatsApp.

Follow the instructions to connect Botpress to your WhatsApp account.

Additional requirements:

While setting up your WhatsApp integration, we will ask you to create or select:
- A Facebook business page
- A WhatsApp business account
After setup is complete, your business will undergo a verification process by Meta, the parent company of WhatsApp. This verification confirms the identity and eligibility of your business to use Meta’s platforms.

For advanced use cases, you can use your own Meta app with our integration.

You will need:

A Meta developer app with the . Check out the Meta developer documentation to learn more about the setup process.

Step 1: Install the integration in Botpress

In Botpress Studio, select Explore Hub in the upper-right corner.

Search for the WhatsApp integration, then select Install Integration.

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:

Verify Token

Used by Meta to verify that you’re the real owner of the provided webhook. Can be any alphanumeric string.

Access Token

In your Meta app’s left sidebar, go to Use cases > Connect with customers through WhatsApp > Customize.

If you haven’t added WhatsApp as a use case yet, select Add use cases, then Connect with customers through WhatsApp.

Select a WhatsApp business portfolio (if you haven’t already).

Go to API testing.

Select Generate access token, then copy the token.

In Botpress, paste the token into the integration’s Access Token configuration field.

Client Secret

In your Meta App’s left sidebar, expand the App Settings menu and select Basic.

In the App Secret field, select Show, then copy your secret.

In Botpress, paste the secret into the integration’s Client Secret configuration field.

Default Bot Phone Number ID

In your Meta app’s left sidebar, go to Use cases > Connect with customers through WhatsApp > Customize.

If you haven’t added WhatsApp as a use case yet, select Add use cases, then Connect with customers through WhatsApp.

Select a WhatsApp business portfolio (if you haven’t already).

Go to API testing.

Under Select a ‘From’ phone number, copy the Phone number ID.

In Botpress, paste the ID into the integration’s Default Bot Phone Number ID configuration field.

WABA ID (WhatsApp Business Account ID)

In your Meta app’s left sidebar, go to Use cases > Connect with customers through WhatsApp > Customize.

If you haven’t added WhatsApp as a use case yet, select Add use cases, then Connect with customers through WhatsApp.

Select a WhatsApp business portfolio (if you haven’t already).

Go to API testing.

Under Select a ‘From’ phone number, copy the WhatsApp Business Account ID.

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:

In Botpress, copy the webhook URL and Verify Token from the integration’s Configuration section.

In your Meta app’s left sidebar, go to Use cases > Connect with customers through WhatsApp > Customize.

If you haven’t added WhatsApp as a use case yet, select Add use cases, then Connect with customers through WhatsApp.

Select a WhatsApp business portfolio (if you haven’t already).

Go to Configuration.

Paste the webhook URL into the Callback URL field.

Paste your Verify Token in the Verify Token field.

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

You’ve manually configured your WhatsApp integration!

For more information, check out WhatsApp’s guide on getting started with Cloud API.

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.

You will need:

A published bot
A WhatsApp account

In Botpress Studio, select Explore Hub in the upper-right corner.

Search for the WhatsApp integration, then select Install Integration.

Select Test your agent on WhatsApp.

Follow the instructions to set up the playground.

Cards

Some of the integration’s Cards use WhatsApp message templates to send messages to users.

In WhatsApp, these templates support both named and positional parameters. 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.

List Message Templates

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

inputobject

outputobject

Send Template Message

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

inputobject

outputobject

Start Conversation

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

inputobject

outputobject

startTypingIndicator

inputobject

stopTypingIndicator

inputobject

Triggers

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

This Trigger has no payload.

Message Failed

Triggered when a message fails to be delivered

payloadobject

Message Read

Triggered when a user reads a message

This Trigger has no payload.

Message Sent

Triggered when a message is sent

This Trigger has no payload.

Message Template Components Update

Triggered when a template is edited

payloadobject

Message Template Quality Update

Triggered when a template's quality score changes

payloadobject

Message Template Status Update

Triggered when a template is approved, rejected or disabled

payloadobject

Message Echo Received

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

This Trigger has no payload.

Reaction Added

Triggered when a user adds a reaction to a message

payloadobject

Reaction Removed

Triggered when a user removes a reaction from a message

payloadobject

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.

payloadobject

Troubleshooting

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 while waiting for business verification.

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 while waiting for business verification.

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 is configured correctly.