Chatbot to Human handoff

Move a conversation to a human

This article is about transfering a conversation from the initial chatbot to a human using Tiledesk external-chatbot technology. This feature is named chatbot to human handoff.

In this example, after the initial greeting message the chatbot proposes you to move to an agent. If you reply "yes" the handoff will occur.

You can handoff to human agents from any Tiledesk chatbot (native or external) simply sending the \agent text as the last line of any message. This message tells Tiledesk to remove the chatbot from the current conversation and invite a human in its place. As soon as Tiledesk sees this command in the text it will remove the current chatbot from the current conversation and will try to invite a human, following the current department rules. If no agents are available the conversation will wait in the “unassigned” queue from where it can be pulled by an agent as soon as one becomes available again.

We wrote a full Node.js example that you can fork or copy.

Here follows the source code of index.js file in the example:

const express = require('express');
const bodyParser = require('body-parser');
const { TiledeskChatbotClient } = require('@tiledesk/tiledesk-chatbot-client');

const app = express();

app.get('/', (req, res) => {
  res.send("Tiledesk External-Chatbot to Human handoff Tutorial");
});'/bot', (req, res) => {
  const tdclient = 
    new TiledeskChatbotClient(
        request: req,
        APIKEY: '__APIKEY__'
  if (tdclient.text === "\\start") {
      text: 'Cheers! Need operator?'
  else if (tdclient.text === "yes") {
    tdclient.sendMessage({text: 'Moving you to an operator...'}, (err) => {
          text: '\\agent',
          attributes: {
            subtype: 'info' // widget-hidden message
  else {
    tdclient.sendMessage({text: 'Not trained for this'});

app.listen(3000, () => {
  console.log('server started');

Just note that if you send the '\agent' command it will be visible to the end-user in the Widget. If you want to hide this command-message you must send it as an "info" message. Info messages are always hidden from the end-user conversation.

In the example you see the code sending a first message to indicate the start of the "Agent switching" operation ('Moving you to an operator...'). As soon as this message is sent we send the handoff command ('\agent') as hidden (attributes.subtype = 'info'). This message will start the handoff operation.

Do you have suggestions on this article? Please send us your feedback writing an email to

Last updated