Skip to main content

​
Prerequisites

You will need:
This guide walks you through starting a WhatsApp conversation when an external system sends a request to your bot’s webhook. Use this when you want to initiate a chat from your backend, CRM, or another service (for example, when a support ticket is created or a user signs up).

​
1. Install and configure the Webhook integration

1

Install the Webhook integration

In Botpress Studio, select Explore Hub in the upper-right corner. Search for Webhook, then select Install Integration.
2

Copy your webhook URL

Open the integration’s Configuration page. Copy the webhook URL shown there (it starts with https://webhook.botpress.cloud/).Webhook Configuration page with webhook URL
3

Send requests to the webhook

From your external system, send a POST request to this URL with the payload you need (for example, the user’s phone number and template variables). Ensure the request body is JSON and that you use the same URL when testing in Studio.
If you configured a Secret for the integration, include it in the request as the x-bp-secret header. For more details, see Send data to your webhook.

​
2. Add the webhook trigger and Start Conversation in Studio

1

Add the Event trigger

Open the Workflow where you want to handle the webhook. Right-click on the canvas and select Trigger, then choose the Event trigger from the Webhook integration.Add Event trigger from Webhook
2

Add the Start Conversation Card

Add a Node after the trigger and add the Start Conversation Card to it.Add Start Conversation Card to nodeConfigure the Card:
  • User Phone: Use the phone number from your webhook payload (for example, event.payload.body.userPhone if you send { "userPhone": "+1234567890" }).
  • Template Name and Template Language: Your approved WhatsApp message template and its language.
  • Template Variables JSON: If your template has variables, pass them from the webhook payload (for example, event.payload.body.templateVariables). Start Conversation Card with User Phone, Template name, Template language, and Template variables
3

Store the WhatsApp conversation ID

In the Start Conversation Card, set Store result in to a Workflow variable (for example, whatsAppOutput). This variable will hold the new conversation’s ID.Store output value in workflow variable

​
3. Set the conversation ID so the rest of the Workflow runs in the same conversation

So that subsequent nodes (such as the Autonomous Node or your main bot Workflow) run in the same WhatsApp conversation, set event.conversationId to the ID returned by the Start Conversation Card.
1

Add an Execute Code Card

Add an Execute Code Card in the same Node (after Start Conversation) or in a new Node connected right after it.Add Execute Code Card
2

Set the conversation ID

In the Execute Code Card, assign the conversation ID from the Start Conversation output to the event:
event.conversationId = workflow.whatsAppOutput.conversationId
Store result in workflow variableReplace whatsAppOutput with the name of the variable you chose in Store result in for the Start Conversation Card.
The Start Conversation Card returns an object with a conversationId property. By setting event.conversationId, you ensure that any subsequent nodes (including the Autonomous Node or your main Workflow) continue in the same WhatsApp conversation.

​
4. Connect to your main bot Workflow

Connect the node that contains the rest of your main Workflow to your START node. Workflow with start connection to main Workflow That way, when the webhook fires:
  1. The Event trigger runs.
  2. The Start Conversation Card starts a WhatsApp conversation and stores its ID.
  3. The Execute Code Card sets event.conversationId to that WhatsApp conversation ID.
  4. The conversation continues in your main Workflow (for example, in the Autonomous Node or your regular bot Workflow).
When your external system POSTs to the webhook URL with the right payload (user phone, template name, etc.), your bot will start a WhatsApp conversation and then follow your main Workflow for that conversation.
Last modified on March 5, 2026