> ## 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.

# 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](https://developers.facebook.com/docs/whatsapp/cloud-api/messages/text-messages) | `text` | `event.preview` or `event.payload` |
| Choices from interactive [buttons](https://developers.facebook.com/docs/whatsapp/cloud-api/messages/interactive-reply-buttons-messages) or [lists](https://developers.facebook.com/docs/whatsapp/cloud-api/messages/interactive-list-messages) | `text` | `event.preview` or `event.payload` |
| [Image messages](https://developers.facebook.com/docs/whatsapp/cloud-api/messages/image-messages) | `image` | `event.payload` |
| [Sticker messages](https://developers.facebook.com/docs/whatsapp/cloud-api/messages/sticker-messages) | `image` | `event.payload` |
| [Audio messages](https://developers.facebook.com/docs/whatsapp/cloud-api/messages/audio-messages) | `audio` | `event.payload` |
| [Video messages](https://developers.facebook.com/docs/whatsapp/cloud-api/messages/video-messages) | `video` | `event.payload` |
| [Document messages](https://developers.facebook.com/docs/whatsapp/cloud-api/messages/document-messages) | `file` | `event.payload` |
| [Location messages](https://developers.facebook.com/docs/whatsapp/cloud-api/messages/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:

> [accordion] Text
>
> **text** `string` *required*
>
> The content of the message
>
> **value** `string`
>
> The value of the last message. Only specified for choices, postbacks, and buttons

> [accordion] Image
>
> **imageUrl** `string` *required*
>
> The URL of the image file

> [accordion] Audio
>
> **audioUrl** `string` *required*
>
> The URL of the audio file

> [accordion] Video
>
> **videoUrl** `string` *required*
>
> The URL of the video file

> [accordion] File
>
> **fileUrl** `string` *required*
>
> The URL of the file
>
> **filename** `string` *required*
>
> The name of the file

> [accordion] 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](https://botpress.com/docs/api-reference/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.

> [!TIP]
>
> 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.

> [accordion] 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](https://botpress.com/docs/configuration-variables-1)  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:
>
> ```javascript theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> 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
>
>   > [!NOTE]
>   >
>   > For more information, check the [WhatsApp documentation](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media/#download-media) 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.


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