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

# Start a WhatsApp conversation proactively

> Proactively start a WhatsApp conversation with a specific user.

> [!NOTE]
>
> You will need:
>
> * A [configured WhatsApp integration](https://botpress.com/docs/integrations/integration-guides/whatsapp/introduction.md)
> * A [WhatsApp Message Template](https://developers.facebook.com/docs/whatsapp/message-templates/guidelines/)

> [!NOTE]
>
> WhatsApp only allows proactively sending messages if they're created from a template. You can create a template from your [WhatsApp Manager dashboard](https://business.facebook.com/latest/whatsapp_manager/message_templates?business_id=3818287771769899\&tab=message-templates\&nav_ref=whatsapp_manager\&asset_id=1022022276691875).
>
> After WhatsApp reviews and approves your template, follow the steps in this guide.

## Setup

### 1. Add the Start Conversation Card

In Studio, add a **Start Conversation** Card to any Node:

![Start Conversation](https://mintcdn.com/botpress/6GtpoC_49xwNEX7S/integrations/integration-guides/whatsapp/assets/start-conversation.png?fit=max\&auto=format\&n=6GtpoC_49xwNEX7S\&q=85\&s=5a7e954a96b107696dcf0c10c077716f)

### 2. Fill in the required fields

Fill in the fields:

> [accordion] User Phone
>
> The user's phone number, including the country code.
>
> **Example**: `+1 123 456 7890`

> [accordion] Template Name
>
> The name of your WhatsApp message template.
>
> **Example**: `proactive_message`

> [accordion] Template Language (Optional)
>
> The language code for your WhatsApp message template. Defaults to `en_US`.
>
> > [!WARNING]
> >
> > Although this field is optional, an error will occur if you leave the field blank and your message template's language isn't **English (US)**.
>
> > [tab] Country qualifier
> >
> > If the language you selected for your template has a country qualifier, then you need to specify a value in the `language_COUNTRY` format, where:
> >
> > * `language` is the 2-letter lowercase [ISO language code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)
> > * `COUNTRY` is the 2-letter uppercase [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
> >
> > For example, if you selected the **English (UK)** option, enter `en_GB`.
>
> > [tab] No country qualifier
> >
> > If the language you selected for your template has no country qualifier, just specify the 2-letter lowercase [ISO language code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes).
> >
> > For example, if you selected the **French** option, enter `fr`.

> [accordion] Template Variables JSON (Optional)
>
> A JSON array containing the values for your message template's variables.
>
> WhatsApp uses numbers to name variables within message templates. For example, if you have two variables, you need to name them `{{1}}` and `{{2}}`
>
> When you enter your JSON array in Botpress, you can order the entries based on how you want WhatsApp to assign the values:
>
> ```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
> ["First value", "Second value"]
> ```
>
> With the above array:
>
> * `"First value"` will be assigned to `{{1}}`
> * `"Second value"` will be assigned to `{{2}}`.

> [accordion] Sender Phone Number ID (Optional)
>
> The WhatsApp Phone Number ID that will message your user. Defaults to the Phone Number ID you used to configure your integration.
>
> > [!NOTE]
> >
> > To use a different WhatsApp Phone Number ID, you need to have added it via your [Meta developer dashboard](https://developers.facebook.com/apps/).

> [!TIP]
>
> Your bot is ready to proactively start a conversation with your user!

## Access the Conversation ID

You can access the proactively started conversation's ID in Studio by storing the **Start Conversation** Card's output in a variable. Just select a variable to store the value in:

![Output Value field](https://mintcdn.com/botpress/KbMT91f_P0tr2fc3/integrations/integration-guides/whatsapp/assets/output-value.png?fit=max\&auto=format\&n=KbMT91f_P0tr2fc3\&q=85\&s=b1ce9c83a97b8a0b86beaf937350870e)

The output value of this action will be an object with the following structure:

```js theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  conversationId: 'xxxxxxxxxxxxxxxxxxxxx'
}
```

## Create the conversation from code

You can also call `actions.whatsapp.startConversation` in an [Execute Code](https://botpress.com/docs/studio/concepts/cards/execute-code.md) Card to start a conversation:

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
actions.whatsapp.startConversation({
  conversation: {
    userPhone: '+1 123 456 7890',
    templateName: 'test_message',
    templateLanguage: 'en',
    templateVariablesJson: JSON.stringify(['First value', 'Second value'])
  }
})
```


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