Mapping from WhatsApp to Botpress

Content mapping for the official WhatsApp integration.

Overview

In Botpress, you can read data sent from a user’s WhatsApp message using the event’s properties. This is useful if you want to store user-provided data and access it later.

Here’s a breakdown of how data from WhatsApp is mapped to Botpress:

WhatsApp Message Type	Botpress Type	How to Read
Text messages	text	event.preview or event.payload
Choices from interactive buttons or lists	text	event.preview or event.payload
Image messages	image	event.payload
Sticker messages	image	event.payload
Audio messages	audio	event.payload
Video messages	video	event.payload
Document messages	file	event.payload
Location messages	location	event.payload

Read data from a payload

To read data from event.payload:

1. Add a Wait for User Input Card to the Node where you want to prompt the user.
2. After that Card, check that event.type is equal to the data type you’re expecting from the user.
3. Read event.payload.

The payload’s properties depend on the data type:

Text

text · string · required

The content of the message

value · string

The value of the last message. Only specified for choices, postbacks, and buttons

Image

imageUrl · string · required

The URL of the image file

Audio

audioUrl · string · required

The URL of the audio file

Video

videoUrl · string · required

The URL of the video file

File

fileUrl · string · required

The URL of the file

filename · string · required

The name of the file

Location

latitude · number · required

The latitude coordinate of the location

longitude · number · required

The longitude coordinate of the location

title · string

The title of the location (Optional)

address · string

The address of the location (Optional)

Get raw file contents

By default, any media sent by a user is automatically uploaded to the Botpress Files API. This means you can read the raw file contents directly from the payload’s URL.

For example, if you prompt the user to send an image, you can read {{event.payload.imageUrl}} to get the image.

You can also set an expiry time for downloaded files — just update the Downloaded Media Expiry field in the Configuration menu.

From WhatsApp API

If you’d rather get file contents from a WhatsApp media URL, you can disable Download Media in the Configuration menu. When disabled, you’ll have to authenticate with the WhatsApp API to get files.

Get raw file content from the WhatsApp API

1. Set a configuration variable

   1. In your dashboard, navigate to your bot’s Configuration Variables section in the left sidebar.
   2. Create a Configuration Variable named WHATSAPP_ACCESS_TOKEN.
   3. Set its value to your WhatsApp access token.
2. Make a `GET` request

   Now you can make an HTTP GET request to get the raw file data:

   const whatsappAccessToken = env.WHATSAPP_ACCESS_TOKEN
   
   const response = await axios.get(event.payload.<URL>, {
     headers: {
       Authorization: `Bearer ${whatsappAccessToken}`,
     },
   })
   

   Be sure to:

   • Replace <URL> with the actual URL provided in the payload

   • Pass whatsappAccessToken as a Bearer token in the HTTP Authorization header

     For more information, check the WhatsApp documentation on downloading media files.

Tags

You can read event tags to get information about the current WhatsApp user and conversation:

Phone number

To get the user’s phone number:

event.tags.conversation['whatsapp:userPhone']

This number contains the country code. It has no spaces, dashes (-) or symbols.

Phone number ID

To get the conversation’s WhatsApp phone number ID:

event.tags.conversation['whatsapp:botPhoneNumberId']

This is useful if you have multiple phone number IDs pointing to the same bot.

Check if message is reply

To check if a message was a reply to another:

event.tags.message['whatsapp:replyTo']

If the message is a reply, the tag’s value will be the Botpress messageId of the quoted message.