Skip to main content
You will need:
WhatsApp only allows proactively sending messages if they’re created from a template. You can create a template from your WhatsApp Manager dashboard.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
2

Fill in the required fields

Fill in the fields:
The user’s phone number, including the country code.Example: +1 123 456 7890
The name of your WhatsApp message template.Example: proactive_message
The language code for your WhatsApp message template. Defaults to en_US.
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).
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:For example, if you selected the English (UK) option, enter en_GB.
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:
["First value", "Second value"]
With the above array:
  • "First value" will be assigned to {{1}}
  • "Second value" will be assigned to {{2}}.
The WhatsApp Phone Number ID that will message your user. Defaults to the Phone Number ID you used to configure your integration.
To use a different WhatsApp Phone Number ID, you need to have added it via your Meta developer dashboard.
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 The output value of this action will be an object with the following structure: 
{
  conversationId: 'xxxxxxxxxxxxxxxxxxxxx'
}

​
Create the conversation from code

You can also call actions.whatsapp.startConversation in an Execute Code Card to start a conversation: 
actions.whatsapp.startConversation({
  conversation: {
    userPhone: '+1 123 456 7890',
    templateName: 'test_message',
    templateLanguage: 'en',
    templateVariablesJson: JSON.stringify(['First value', 'Second value'])
  }
})
Last modified on November 19, 2025