​
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 TypeBotpress 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
string
required
The content of the message
​
value
string
The value of the last message. Only specified for choices, postbacks, and buttons
​
imageUrl
string
required
The URL of the image file
​
audioUrl
string
required
The URL of the audio file
​
videoUrl
string
required
The URL of the video file
​
fileUrl
string
required
The URL of the file
​
filename
string
required
The name of the file
​
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.
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.