diff --git a/docs.json b/docs.json index 0c98173c..f5a72d3c 100644 --- a/docs.json +++ b/docs.json @@ -342,7 +342,8 @@ "/integrations/integration-guides/whatsapp/mapping/whatsapp-to-botpress" ] }, - "/integrations/integration-guides/whatsapp/whatsapp-start-proactively" + "/integrations/integration-guides/whatsapp/whatsapp-start-proactively", + "/integrations/integration-guides/whatsapp/start-conversation-through-webhook" ] }, "/integrations/integration-guides/zapier", diff --git a/integrations/integration-guides/whatsapp/assets/add-event-trigger.png b/integrations/integration-guides/whatsapp/assets/add-event-trigger.png new file mode 100644 index 00000000..ad9cb7d3 Binary files /dev/null and b/integrations/integration-guides/whatsapp/assets/add-event-trigger.png differ diff --git a/integrations/integration-guides/whatsapp/assets/add-execute-code-card-with-webhook.png b/integrations/integration-guides/whatsapp/assets/add-execute-code-card-with-webhook.png new file mode 100644 index 00000000..462a4e6f Binary files /dev/null and b/integrations/integration-guides/whatsapp/assets/add-execute-code-card-with-webhook.png differ diff --git a/integrations/integration-guides/whatsapp/assets/add-start-convo-card-with-webhook.png b/integrations/integration-guides/whatsapp/assets/add-start-convo-card-with-webhook.png new file mode 100644 index 00000000..3d6209e5 Binary files /dev/null and b/integrations/integration-guides/whatsapp/assets/add-start-convo-card-with-webhook.png differ diff --git a/integrations/integration-guides/whatsapp/assets/assign-convo-id.png b/integrations/integration-guides/whatsapp/assets/assign-convo-id.png new file mode 100644 index 00000000..db106517 Binary files /dev/null and b/integrations/integration-guides/whatsapp/assets/assign-convo-id.png differ diff --git a/integrations/integration-guides/whatsapp/assets/autonomous-node-with-start.png b/integrations/integration-guides/whatsapp/assets/autonomous-node-with-start.png new file mode 100644 index 00000000..880fccd2 Binary files /dev/null and b/integrations/integration-guides/whatsapp/assets/autonomous-node-with-start.png differ diff --git a/integrations/integration-guides/whatsapp/assets/copy-webhook-url.png b/integrations/integration-guides/whatsapp/assets/copy-webhook-url.png new file mode 100644 index 00000000..aa9581f0 Binary files /dev/null and b/integrations/integration-guides/whatsapp/assets/copy-webhook-url.png differ diff --git a/integrations/integration-guides/whatsapp/assets/start-conversation-with-webhook.png b/integrations/integration-guides/whatsapp/assets/start-conversation-with-webhook.png new file mode 100644 index 00000000..9e82544f Binary files /dev/null and b/integrations/integration-guides/whatsapp/assets/start-conversation-with-webhook.png differ diff --git a/integrations/integration-guides/whatsapp/assets/store-whatsapp-output.png b/integrations/integration-guides/whatsapp/assets/store-whatsapp-output.png new file mode 100644 index 00000000..d81ee0a1 Binary files /dev/null and b/integrations/integration-guides/whatsapp/assets/store-whatsapp-output.png differ diff --git a/integrations/integration-guides/whatsapp/start-conversation-through-webhook.mdx b/integrations/integration-guides/whatsapp/start-conversation-through-webhook.mdx new file mode 100644 index 00000000..ee74029a --- /dev/null +++ b/integrations/integration-guides/whatsapp/start-conversation-through-webhook.mdx @@ -0,0 +1,108 @@ +--- +title: Start a conversation on WhatsApp through a webhook +description: Trigger a new WhatsApp conversation from an external system using the Webhook integration and the Start Conversation Card. +sidebarTitle: Start conversation through a webhook +--- + +## Prerequisites + + + You will need: + + - A [configured WhatsApp integration](./introduction.mdx) + - A [WhatsApp Message Template](https://developers.facebook.com/docs/whatsapp/message-templates/guidelines/) (required for starting conversations proactively) + + +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 + + + + In Botpress Studio, select **Explore Hub** in the upper-right corner. Search for **Webhook**, then select **Install Integration**. + + + 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](./assets/copy-webhook-url.png) + + + 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](/integrations/integration-guides/webhook#send-data-to-your-webhook). + + +## 2. Add the webhook trigger and Start Conversation in Studio + + + + Open the [Workflow](/studio/concepts/workflows) 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](./assets/add-event-trigger.png) + + + Add a Node after the trigger and add the **Start Conversation** Card to it. + + ![Add Start Conversation Card to node](./assets/add-start-convo-card-with-webhook.png) + + Configure 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](./assets/start-conversation-with-webhook.png) + + + In the Start Conversation Card, set **Store result in** to a [Workflow variable](/studio/concepts/variables/scopes/workflow) (for example, `whatsAppOutput`). This variable will hold the new conversation's ID. + + ![Store output value in workflow variable](./assets/store-whatsapp-output.png) + + + +## 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](/studio/concepts/nodes/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. + + + + 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](./assets/add-execute-code-card-with-webhook.png) + + + In the Execute Code Card, assign the conversation ID from the Start Conversation output to the event: + + ```js + event.conversationId = workflow.whatsAppOutput.conversationId + ``` + + ![Store result in workflow variable](./assets/assign-convo-id.png) + + Replace `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](/studio/concepts/nodes/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](./assets/autonomous-node-with-start.png) + +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](/studio/concepts/nodes/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. +