Docs

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 TypeHow to Read
Text messagestextevent.preview or event.payload
Choices from interactive buttons or liststextevent.preview or event.payload
Image messagesimageevent.payload
Sticker messagesimageevent.payload
Audio messagesaudioevent.payload
Video messagesvideoevent.payload
Document messagesfileevent.payload
Location messageslocationevent.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.

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

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.

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

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.