Bot-Human Collaboration

To help you with the conversation inquiries, we provide a conversations distribution through agents (as customer service agents). However if you are not willing to spend your resources to pay for some agents, then we already provide a solution you may like. That is by providing a bot integration feature that will enable a collaboration between human and bot in dealing with customer inquiries

Bot Integration

Qiscus Omnichannel Chat has provided a URL for your bot to hit back whenever any messages come to your bot, as depicted in the image above. To connect your bot to Qiscus Omnichannel Chat, just follow this steps (We assume you already build your bot).

Step 1 : Send Message To Qiscus Omnichannel Chat From Bot

Point your Chatbot engine to hit Qiscus Omnichannel Chat URL in STEP 1. So, get a copy of STEP 1 URL and make it the default URL to hit into whenever any messages coming for bot to response to,

When your bot making a post to Qiscus Omnichannel Chat, you will need your Qiscus Omnichannel Chat app credentials, such as: Agent ID (This will be your bot ID), App ID (AppCode), and Qiscus Secret Key. All this information has been provided in the bot integration page.

For more information about what type of message that has been supported in Qiscus Omnichannel Chat, please visit Message section#send-message

Grab your bot Webhook URL and paste it into the provided bot Webhook URL field in the bot integration tab as shown in the image above,
Click connect button.

That's all.

You can use this API for managing various behaviour of message. There are several type of message that bot can post to a chat room, instead of text (default). Each message has different payload format (particularly in JSON/JSON string).

1. Send Message Text

Base URL:

HTTP
    
 
https://omnichannel.qiscus.com
Copy

URL:

HTTP
    
 
[POST] {{BaseUrl}}/{{AppCode}}/bot
Copy

Headers:

HTTP
    
 
"Content-Type":"application/json""QISCUS_SDK_SECRET" : {{Qiscus Secret Key}}
Copy

Body:

JSON
    
 
{  "sender_email": "{{AdminEmail}}",   "message": "Hi good morning",  "type": "text",  "room_id": "2174484"}
Copy

An example request of send a message with default type (text):

curl
    
 
curl --location -g --request POST '{{BaseUrl}}/{{AppCode}}/bot' \--header 'Content-Type: application/json' \--header 'QISCUS_SDK_SECRET: {{Qiscus Secret Key}}' \--data-raw '{  "sender_email": "{{AdminEmail}}",   "message": "Hi good morning",  "type": "text",  "room_id": "2174484"}'
Copy

2. Send Message Attachment

URL:

HTTP
    
 
[POST] {{BaseUrl}}/{{AppCode}}/bot
Copy

Headers:

HTTP
    
 
"Content-Type":"application/json""QISCUS_SDK_SECRET" : {{Qiscus Secret Key}}
Copy

Body:

JSON
    
{  "sender_email": "{{AdminEmail}}",   "message": "Hi good morning",  "type": "file_attachment",  "room_id": "*****",  "payload": {    "url": "https://d1edrlpyc25xu0.cloudfront.net/ysotr-aja9u91emy3ecss/image/upload/w_320,h_320,c_limit/uRz8jFG3kC/download.jpeg",    "caption": "Qiscus"  }}
Copy

An example request of send a message with attachment:

Bash
    
curl --location --request POST "{{BaseUrl}}/{{AppCode}}/bot" \  --header "Content-Type: application/json" \  --header 'QISCUS_SDK_SECRET: {{Qiscus Secret Key}}' \  --data "{  \"sender_email\": \"{{AdminEmail}}\",   \"message\": \"Hi good morning\",  \"type\": \"file_attachment\",  \"room_id\": \"*****\",  \"payload\": {    \"url\": \"https://d1edrlpyc25xu0.cloudfront.net/ysotr-aja9u91emy3ecss/image/upload/w_320,h_320,c_limit/uRz8jFG3kC/download.jpeg\",    \"caption\": \"Qiscus\"  }}"
Copy

3. Send Message Button

URL:

HTTP
    
 
[POST] {{BaseUrl}}/{{AppCode}}/bot
Copy

Headers:

HTTP
    
 
"Content-Type":"application/json""QISCUS_SDK_SECRET" : {{Qiscus Secret Key}}
Copy

Body:

JSON
    
 
{  "sender_email": "{{AdminEmail}}",   "message": "Hi good morning",  "type": "buttons",  "room_id": "2174484",  "payload": {    "text": "silahkan pencet",      "buttons": [          {              "label": "button1",              "type": "postback",              "payload": {                  "url": "http://somewhere.com/button1",                  "method": "get",                  "payload": null              }          },          {              "label": "button2",              "type": "link",              "payload": {                  "url": "http://somewhere.com/button2?id=123"              }          }    ]  }}
Copy

An example request of send a message with button:

curl
    
 
curl --location --request POST "{{BaseUrl}}/{{AppCode}}/bot" \  --header "Content-Type: application/json" \  --header 'QISCUS_SDK_SECRET: {{Qiscus Secret Key}}' \  --data "{  \"sender_email\": \"{{AdminEmail}}\",   \"message\": \"Hi good morning\",  \"type\": \"buttons\",  \"room_id\": \"2174484\",  \"payload\": {    \"text\": \"silahkan pencet\",      \"buttons\": [          {              \"label\": \"button1\",              \"type\": \"postback\",              \"payload\": {                  \"url\": \"http://somewhere.com/button1\",                  \"method\": \"get\",                  \"payload\": null              }          },          {              \"label\": \"button2\",              \"type\": \"link\",              \"payload\": {                  \"url\": \"http://somewhere.com/button2?id=123\"              }          }    ]  }}"
Copy

Bot cannot post Button message type to chat room to Instagram, WhatsApp, and WhatsApp Cloud API channels.

4. Send Message Carousel

URL:

HTTP
    
 
[POST] {{BaseUrl}}/{{AppCode}}/bot
Copy

Headers:

HTTP
    
 
"Content-Type":"application/json""QISCUS_SDK_SECRET" : {{Qiscus Secret Key}}
Copy

Body:

JSON
    
{  "sender_email": "{{AdminEmail}}",   "message": "Hi good morning",  "type": "carousel",  "room_id": "{{roomId}}",  "payload": {    "cards": [      {        "image": "https://image-archive.developerhub.io/image/upload/22509/zrb6m4mgpr2z2bptxywq/1583214975.png",              "title": "Qiscus",              "description": "Qiscus Omnichannel Chat is an accelerator package as a solution for customers service engagement. ",              "default_action": {                  "type": "postback",                  "postback_text": "Load more",                  "payload": {                      "url": "https://www.qiscus.com/id",                      "method": "get",                      "payload": null                  }              },              "buttons": [                  {                      "label": "button1",                      "type": "postback",                      "postback_text": "Load more",                      "payload": {                          "url": "https://www.qiscus.com/id",                          "method": "get",                          "payload": null                      }                  },                  {                      "label": "button2",                      "type": "link",                      "payload": {                          "method": "get",                           "url": "https://www.qiscus.com/id"                      }                  }              ]      },      {        "image": "https://image-archive.developerhub.io/image/upload/22509/zrb6m4mgpr2z2bptxywq/1583214975.png",              "title": "Qiscus",              "description": "Qiscus Omnichannel Chat is an accelerator package as a solution for customers service engagement.",              "default_action": {                  "type": "postback",                  "postback_text": "Load more",                  "payload": {                      "url": "https://www.qiscus.com/id",                      "method": "get",                      "payload": null                  }              },              "buttons": [                  {                      "label": "button1",                      "type": "postback",                      "postback_text": "Load more",                      "payload": {                          "url": "https://www.qiscus.com/id",                          "method": "get",                          "payload": null                      }                  },                  {                      "label": "button2",                      "type": "link",                      "payload": {                          "method": "get",                           "url": "https://www.qiscus.com/id"                      }                  }              ]      }    ]  }}
Copy

An example request of send a message with carousel:

curl
    
curl --location --globoff --request POST '/{{AppCode}}/bot' \--header 'Content-Type: application/json' \--header 'QISCUS_SDK_SECRET: {{AppSecret}}' \--data '{  "sender_email": "{{AdminEmail}}",   "message": "Hi good morning",  "type": "carousel",  "room_id": "{{roomId}}",  "payload": {    "cards": [      {        "image": "https://image-archive.developerhub.io/image/upload/22509/zrb6m4mgpr2z2bptxywq/1583214975.png",              "title": "Qiscus",              "description": "Qiscus Omnichannel Chat is an accelerator package as a solution for customers service engagement. ",              "default_action": {                  "type": "postback",                  "postback_text": "Load more",                  "payload": {                      "url": "https://www.qiscus.com/id",                      "method": "get",                      "payload": null                  }              },              "buttons": [                  {                      "label": "button1",                      "type": "postback",                      "postback_text": "Load more",                      "payload": {                          "url": "https://www.qiscus.com/id",                          "method": "get",                          "payload": null                      }                  },                  {                      "label": "button2",                      "type": "link",                      "payload": {                          "method": "get",                           "url": "https://www.qiscus.com/id"                      }                  }              ]      },      {        "image": "https://image-archive.developerhub.io/image/upload/22509/zrb6m4mgpr2z2bptxywq/1583214975.png",              "title": "Qiscus",              "description": "Qiscus Omnichannel Chat is an accelerator package as a solution for customers service engagement.",              "default_action": {                  "type": "postback",                  "postback_text": "Load more",                  "payload": {                      "url": "https://www.qiscus.com/id",                      "method": "get",                      "payload": null                  }              },              "buttons": [                  {                      "label": "button1",                      "type": "postback",                      "postback_text": "Load more",                      "payload": {                          "url": "https://www.qiscus.com/id",                          "method": "get",                          "payload": null                      }                  },                  {                      "label": "button2",                      "type": "link",                      "payload": {                          "method": "get",                           "url": "https://www.qiscus.com/id"                      }                  }              ]      }    ]  }}'
Copy

Bot cannot post Carousel message type to chat room to Telegram, WhatsApp, and WhatsApp Cloud API channels.

Step 2 : Webhook From Qiscus Omnichannel Chat

In the step 2, you will need to put /endpoint so that Qiscus Omnichannel Chat can pass the data from end-customer to your chatbot platform.

Your /endpoint will be getting this kind of webhook payload :

JSON
    
{    "type": "post_comment_mobile", // either type "post_comment_mobile" if from client side or "post_comment_rest" if from REST API    "payload": {        "from": {            "id": 1,            "email": "user1@gmail.com",            "name": "User1",        },        "room": {            "id": 1,            "topic_id": 1, # same value with room.id            "type": "group", # can also be single            "name": "ini grup",            "options": {                "is_resolved": true,                "source": "wa",                "is_waiting": "false",                "channel_details": {                    "channel_id": 1,                    "name": "Wa Pertama"                }            },            "participants": [                {                    "id": 1,                    "email": "user1@gmail.com",                    "username": "User1",                    "avatar_url": "http://avatar1.jpg"                },                {                    "id": 2,                    "email": "user2@gmail.com",                    "username": "User2",                    "avatar_url": "http://avatar2.jpg"                }            ]        },        "message": {            "type": "text",            "text": "ini pesan",            "payload": {                # comment type specific payload            }        }    }}
Copy

Then, you will need to process the data. Once you done process the data, you will need to do Step 1 above to send message to Qiscus Omnichannel Chat, so that the end customer can receive the chatbot response.

This Webhook feature can be used beyond just chatbot integration, it also can be used to send customer message from Qiscus Omnichannel Chat to your own data processor.

This Webhook functionality can be used to other than Chatbot, it can be used to data ingestion from Qiscus Omnichannel Chat to your own data processor as well. For example to stream all of the customer message to your data lake or warehouse.

Global Activation vs Local De-Activation

Whenever this bot feature is activated, all incoming messages will be handled directly by the connected bot. That's why we have a global activation and local de-activation terms. It means that this bot feature can be activated/deactivated globally to handle all incoming messages, but it can also be deactivated locally. So if you want to turn this feature off for certain rooms, just do so by toggle it off in each room you want it to be handled by human. And by doing so, your bot will never get any messages in specific rooms.

Bot Human Collaboration

Sometimes, bot may fail to meet customers expectation for their inquiries. Therefore, Qiscus Omnichannel Chat provides a feature to help customer services (agents) to collaborate to handle unanswered question by bot, we call it Handover. This feature can be utilized by calling a handover endpoint Qiscus Omnichannel Chat API in bot's action. The idea behind this handover mechanism is by not passing any incoming messages to bot. So whenever bot webhook hits this endpoint, it will toggle off bot for specific room to receive any messages.

In doing so, there are several scenarios you may come up with,

By intentionally asking bot to handover the active conversation to available customer service agent.
By using sentiment analysis. So whenever user stating any negative message, it will activate handover.
By counting unanswered question. For example, if bot is unable to answer three times, the conversation will automatically be handed over to customer service.

Below are the couple endpoints API you can call in your bot action,

1. Handover bot to agent in certain chat rooms

This API will turn off the bot in certain chat rooms. When you use this API, a pop-up about Handover Request will appear on all roles (admin, supervisor, and agent) Inbox pages if one of the chat rooms is opened. whoever gets this pop-up can assign an agent to the chat room by clicking Accept and go to chat or ignore the pop-up by clicking Decline and close.

URL:

HTTP
    
 
[POST] {{BaseUrl}}/{{AppCode}}/bot/{{roomId}}/hand_over
Copy

Header:

HTTP
    
 
"Authorization": "{{Qiscus Secret Key}}"
Copy

You can get APP ID (AppCode) and Secret Key from Setting page.

Body

HTTP
    
 
not required
Copy

Response:

JSON
    
{    "data": {        "status": "ok",        "room_log": {            "id": 6xxxxx,            "app_id": 1xxxxxx,            "user_id": "oxxx@xxxil.com",            "room_id": "10xxxxxxx",            "source": "qiscus",            "created_at": "2022-12-06 03:36:42",            "updated_at": "2022-12-21 03:19:24",            "is_handled_by_bot": false,            "start_service_comment_id": "1165468939",            "user_avatar_url": "https://xxxxxx.cloudfront.net/kiwari-prod/image/upload/wMxxxxxa/xxxxx_qiscus_client.png",            "name": "Ana",            "has_no_message": false,            "extras": "{\"additional_extras\":{\"timezone_offset\":7},\"notes\":null,\"timezone_offset\":null,\"user_properties\":[]}",            "check_wa_contact": false,            "origin": "https://omnichannel.qiscus.com/iframes/v4/lxxxxxxxxxxy/omnichannel-widget/12xxxx",            "room_badge": null,            "is_waiting": false,            "sub_source": null,            "channel_id": 12xxxx,            "resolved": false,            "resolved_ts": null,            "type": null,            "deleted_at": null,            "customer_id": 2xxxxx,            "last_comment_ts": 1670297845,            "last_cust_comment_ts": 1670297809        }    }}
Copy

2. Handover to a specific Agent Role

This API will turn off the bot in certain chat rooms. You can specify to which agent's role your bot has to handover its conversation. For example, if for one case your customer wants to talk to a Billing agent, you can enable your bot to do so by specifying that role when calling our API endpoint for handover. The rest will be taken care by system. The API works only if Auto Agent Allocation is on.

Header:

HTTP
    
 
"Authorization": "{{Qiscus Secret Key}}"
Copy

URL:

HTTP
    
 
[POST] /{{appId}}/bot/{{roomId}}/hand_over_to_role
Copy

Body:

role is any role name you specify in Qiscus Omnichannel Chat in lower case

HTTP
    
 
'role'                => 'required''roles[]'              => 'required if role empty | array''find_online_agent'   => 'optional | boolean'
Copy

Response:

JSON
    
{    "data": {        "status": "ok",        "room_log": {            "id": 157,            "app_id": 1,            "user_id": "1613514882063983",            "room_id": "1021937",            "source": "fb",            "created_at": "2018-08-15 07:07:00",            "updated_at": "2018-08-20 08:00:51",            "is_handled_by_bot": false,            "start_service_comment_id": "5875494",            "user_avatar_url": "https://d1edrlpyc25xu0.cloudfront.net/oni-bgo2lummmhvzqxbt5/raw/upload/4yxWJ4-j8R/?psid=1613514882063983&height=200&width=200&ext=1536908820&hash=AeSfKm_oNpQvK9ph",            "name": "Aji Tirta",            "has_no_message": false,            "extras": null        }    }}
Copy

Handover agent to the same role via bot.

The Bot cannot assign the conversation to another Agent that is in the same division. For example, if the conversation has been assigned to Agent 1 from the Marketing Division, then The Bot will not be able to assign it to another Agent from the Marketing Division.

Please check the response below.

Response:

JSON
    
 
{    "errors": {        "message": "agent with mentioned role already in room (Marketing)"    },    "status": 400}
Copy

3. Hide Handover request pop-up

You can hide handover request pop-up from appearing on the Inbox page by following these steps.

Go to Setting and select Agents Management,

Click Other Agents Inbox Setting and enable Hide handover request dialogue from bot to agent toggle.

Last updated on Mar 21, 2025

Was this page helpful?