Interested in connecting one chatbot to another? The bot-to-bot handover feature makes it possible to create a network of bots that can communicate with each other.
Passing conversations between bots helps you avoid complex, hard-to-maintain bot structures. 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 value.
We'll introduce the feature, explain how to set it up, and address a few other relevant details:
- Introduction to bot-to-bot handover
- Request the handover feature
- Create the handover Webhook
- Configure the handover flow
- Additional considerations
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'd 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 responds to the user’s messages. From the customer’s view, 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 team for each bot that will be handed over to. If you’re interested in using this functionality, contact us at support@certainly.io.
Both source and destination bots should be created (owned) by the same user and the JWT token of this person must be used in the webhook.Before reaching out, create the bots with which you’d like to use the bot-to-bot handover feature and decide what order your handover process will follow. For instance, if you’d like Bot A to hand over to Bot B and want Bot B to hand back over to Bot A, the feature needs to be enabled for both bots.
In your request, please list all bots you'd like to hand over to.
Create the handover Webhook
After we’ve enabled the feature, you’ll insert the handover Webhook(s) in the appropriate Module(s) of your bot(s). To do so, you’ll need to first navigate to the Webhook Marketplace and create an instance of the 
Certainly Bot-to-bot Handover Webhook Template.
We recommend renaming the Webhook instance to be specific to the handover you're setting up, such as “Handover: Bot A to Bot B”. This will help differentiate the Webhooks when you add them to your Modules. Then follow the instructions in the Webhook description.
As noted there, you'll need to define the following:
- Public API authorization token preceded by "JWT" in Headers (find in your User Profile)
- Bot UUID of the destination bot (find in the bot URL after https://app.certainly.io/bots/list/)
- Destination Module ID (Module ID of where the chat will land in the destination bot)
You can define the Bot UUID and the Module ID in one of two ways:
- Set directly in the Webhook's body (requires a separate Webhook instance for each destination bot)
- Use Custom Variables (one Webhook can hand over to multiple bots), shown here:
Note that "botId" is a string type and "moduleId" is a number.
Configure the handover flow
Once you've created the required Webhook(s), return to the original bot's canvas and refresh the webpage so the new Webhooks are available in the Conversation Builder.
Now you're ready to configure the handover flow. We'll share an example setup process below.
- Set up the Modules in the original bot:
- Next, configure the Message tab of the original bot's handover Module:
- Then set up the Connections tab of the original bot's handover Module:
In this example, we store the original bot's name in the Custom Variable originBot so the destination bot knows where the user came from. When a user selects Topic A, they continue to the next Module in the original bot, Bot A.
When a user selects Topic B, we set the relevant Bot and Module IDs for where the conversation will land in the destination bot, Bot B. Then we call the handover Webhook.
- Finally, configure the rest of the flow in the destination bot:
You can repeat the handover process as often as needed, including back to the original bot. Just remember, we must enable the feature for any destination bots.
A conversation following the above flow will appear as such in the Inbox of Bot B:
Learn more about the effect of bot-to-bot handover on messages in the Inbox.
That’s it! A setup like this will allow your bots to communicate with each other and reduce the complexity of their structure. Questions about configuration? Just reach out to us!
Additional considerations
Messages in the Inbox
Please note the following about the impact of bot-to-bot handover on Inbox results:
- All messages from the conversation will appear in the Inbox of the last destination bot with which a visitor interacted. 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 an agent occurs, text from that chat will also be included in the transcript.
- The transcript contains an empty line indicating the point of bot handover.
- The channel-specific icon in the list of conversations will be a right arrow icon.
Agent handover or takeover
Human handover must 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.