Pass conversations between bots using bot-to-bot handover

Interested in connecting one chatbot to another? The bot-to-bot handover feature makes it is possible to create a network of bots that can communicate with each other.

Passing conversations between bots allows you to avoid having a very complex bot structure that is hard to maintain. Whether it's handling multiple brands with ease or ensuring multilingual bots don’t have to rely on third-party translation services or localization tools, this feature has great potential value.


In this article, we’ll introduce the feature, explain how to set it up in your bots, and address a few other relevant details.

Introduction to bot-to-bot handover

The bot-to-bot handover feature enables a customer to be handed over from Bot A to Bot B (to Bot C…and so on, even back to Bot A!) while sending messages via the original channel. This means the user can chat on the same widget the entire time.

For example, imagine a customer visits your website and starts a conversation with your original bot, Bot A, which is designed to handle English content. You also have Bot B, which is designed to handle Spanish content. If the user indicates they would prefer to communicate in Spanish, Bot A hands over the conversation to Bot B, the destination bot, using a Webhook.

Once handover is complete, Bot B starts responding to the end user’s messages. From the customer’s perspective, the transition is seamless, and they continue interacting with the bot using the original Bot A widget. But now, the conversation, messages, and user belong to Bot B, the destination bot.

Request the handover feature

The feature must be enabled by a member of our Customer Success team for each bot that will be handed over to. If you’re interested in taking advantage of this functionality, contact us at

Before reaching out, create the bots you’d like to use the bot-to-bot handover feature with and decide what order your handover process will follow. For instance, if you’d like Bot A to hand over to Bot B, and you want Bot B to hand back over to Bot A, the feature needs to be enabled for both of the bots. In your request, please list all bots you'd like to hand over to.

How to configure bot-to-bot handover

Now, we'll address the required Webhooks and how to configure the entire flow.

Create the handover Webhook

After we’ve enabled the feature, you’ll need to insert the handover Webhook(s) in the appropriate Module(s) of your bot(s). Before you can do that, you’ll need to navigate to the Webhook Marketplace and use the wh_iconCertainly Bot-to-bot Handover Webhook Template to create your own. 

After selecting the template, we recommend renaming it to be specific to the handover you're setting up, such as “Handover: Bot A to Bot B”. This will help you differentiate the Webhooks when you add them to your Modules. Then follow the instructions in the description at the top of the Webhook. As noted there, you'll need to define these two values in each Webhook instance:

  • Public API authorization token preceded by "JWT" in Headers (requires admin access to destination bot)
  • Bot UUID of the destination bot in the Body (in the Bot A to Bot B example, you'd use the bot ID for Bot B)

You'll need to create an instance of this Webhook for each possible handover, since it's specific to the destination bot's ID.

Configure the handover Module

Once the Webhooks are created, return to the bot canvas and refresh the webpage. Now you're ready to insert the Webhooks into the bot's handover Module(s). The Webhooks must be used in Modules where a user needs to be handed over to the destination bot.

We’ll share one example of the step-by-step process, showing a Bot A to Bot B handover. In the following image, you can see the canvas of Bot A, the original bot, which allows for handover to Bots B or C.


In the handover Module, <md>Starting Module – Bot A, the user is presented with three options:

  • If they select Topic A, their conversation will continue within Bot A, the original bot.
  • If they select Topic B, they will be handed over to Bot B.
  • If they select Topic C, they will be handed over to Bot C.

You can see the Message tab of Bot A's handover Module here:


In the Connections tab of <md>Starting Module – Bot A, we set two optional variables and configure the Connections based on the user’s response. Please note that this Module contains the handover Webhooks. You can see the setup below.


The variables set here are not necessary for the handover to work, but since they're passed along with the user and conversation, they can be valuable later in the process. You can of course adjust these to your own needs.

The variables we've set in this example are as follows:

  • origin: Informs destination bot of where the user came from. Here, set with “Bot A”.
  • mainAnswer: Informs destination bot of the user’s response to the initial question. Set with “this module end-user reply”.

Remember that any Set Variable Connections must be positioned above the other Connections in this tab, otherwise the user will move to the next Module without the variable(s) being set.

In the image above, you can also see the two Webhooks that are required to enable the bot-to-bot handover:

  • wh_iconHandover: Bot A to Bot B allows the customer to be passed from Bot A – Original Bot to Bot B – Destination Bot if they select “Topic B”. The flow will then continue to <md>First Message – Bot B.
  • wh_iconHandover: Bot A to Bot C allows the customer to be passed from Bot A – Original Bot to Bot C – Destination Bot if they select “Topic C”. The flow will then continue to <md>First Message – Bot C.

We'll explain the purpose of these "First Message" Modules in the following section.

Configure the segue Module

It's very important to keep in mind that when the customer is handed over via the Webhook, the destination bot can't initiate the chat automatically. As such, once the handover Webhook is triggered, the customer must send one more message to get to the destination bot’s starting Module. 

Since customers will be unaware of the need to respond to complete the handover, they will likely need a prompt of some kind, regardless of the exact scenario. You’ll want to consider what creates the best user experience in each situation.

In this case, the segue Modules help make a smoother transition. The segue Modules of this example are labeled "First Message" Modules. If the user selects “Topic B”, the wh_iconHandover: Bot A to Bot B Webhook is triggered and the user is sent to the <md>First Message – Bot B, which acts as a segue to the destination bot. You can view the Message tab below:


As you can see, the chatbot acknowledges the customer’s answer to the previous Module, then asks a relevant question to get one more response. In this example, we've offered a Suggested Reply to make the process as simple as possible.

In the next image, you can see that no Connections are configured in this Module, <md>First Message – Bot B. The customer’s response is the only thing necessary for Bot B – Destination Bot to continue the conversation.


At this point, Bot B – Destination Bot picks up the conversation.

Continue the conversation in the destination bot

Bot B's first Module, <md>Starting Module – Bot B, is automatically triggered by the customer’s response to the <md>First Message – Bot B Module, which was in Bot A – Original Bot.

You can see the canvas of Bot B – Destination Bot here:


In this bot’s starting Module, <md>Starting Module – Bot B, the bot responds to the user’s previous answer and continues the conversation in a way that aligns with its own flows. The Message tab of this Module is shown below.


Here, you can also see an example of how to use the “origin” variable we set in Bot A – Original Bot. This variable has been passed to acknowledge where the user came from. Then a new “origin” variable is set to “Bot B” for any possible handovers from Bot B. Again, while setting this variable is not required, it can be helpful later on.

The Connections tab of <md>Starting Module – Bot B can be viewed here:


The handover process can be repeated as many times as is needed, including back to the original bot. Just remember that our Customer Success team must enable the feature for any bots that may be handed over to.

Below, you can see a test of the full flow we've described, starting in Bot A and ending in Bot B:


That’s it! A setup like this will allow your bots to communicate with each other and reduce the complexity of their structure. Any questions about configuring this feature? Just reach out to our Customer Success team at

Additional considerations

Agent handover/takeover

Human handover needs to be aligned with whichever channel the original bot is deployed on. For example, a bot using Sunshine Conversations will need to hand over to Zendesk using the Sunshine Conversations method, not the traditional Zendesk method. When an agent hands the user back over, the user will return to the last bot they were in before handover. 

Messages in Inbox

Messages from this conversation will appear in the inbox of the latest bot where the end user has interacted. Messages from the user's interactions with all previous bots will be visible here. For example, if a user is handed over from Bot A to Bot B, then from Bot B to Bot C, and the chat ends in Bot C, all messages from the entire conversation will appear in the inbox of Bot C.

If handover to a human agent took place, any text from that conversation will also be included in the inbox transcripts.

Natural flow of conversation

As a reminder, your customers won't know an additional response is necessary before the handover can be completed, so it's important to add a segue Module in the original bot. Having a prompt relevant to the conversation can greatly improve the user experience. It may require creative thinking, but there are many ways to ensure these Modules maintain a natural flow!>