Features
Solutions
Docs
Resources
Enterprise
GPTBots Docs > TUTORIAL > Bot > Human Service
GPTBots Docs > TUTORIAL > Bot > Human Service
Human handoff
Last updated：2024-06-01

Human handoff

The Human handoff feature allows Bot developers to integrate third-party Human customer handoff systems to respond to Bot users' requests for Human assistance. Currently, integration with the Intercom、Webhook system is supported, and integration with other Human handoff systems (e.g., livechat, WhatsApp, Slack, DingTalk, QiYu, WeChat Work, etc.) will soon be supported.

How to Enable Human handoff

  1. In Bot Settings - Human handoff, click the "Enable" button to activate the Human handoff.
  2. Select the required customer service system, supporting intercom, webhook, etc.
  3. Complete the authentication configuration of the selected third-party customer service system to ensure successful message communication.
  4. Adjust the settings related to Human handoff according to the actual situation of the enterprise's Human handoff support.
  5. Initiate a Human handoff request in the Bot conversation window to normally call the Human handoff.

Configure Human handoff Authentication

Intercom Authentication

Complete tutorial guide for providing Human handoff through Intercom

  1. Create APPS
    First, register at Intercom and follow the guide to complete the workspace creation. Access the Developer Hub page through "Account Avatar - Settings - APPS & INTEGRATIONS". Click "New app" in the Developer Hub to create an application. If the app is already created, directly select the target app to enter its settings page. alt text
  2. Obtain AccessToken and fill it in GPTBots
  • Select the "Authentication" menu item and copy the Access token information. intercom Access token
  • Fill the token information into the Access token input box under "Human handoff - Intercom Authentication". alt text
  • Fill in the Human handoff message receiving address in Intercom Copy the URL address in "GPTBots Message Receiving Address" and fill this URL address into the Endpoint URL in the Webhooks menu item. alt text
  • Subscribe to key business events in Intercom In the Topics function area of the Webhooks menu item, use "Select a topic..." to select 4 subscription events, and click the "save" button to save the configuration.
    • conversation.admin.closed
    • conversation.admin.replied
    • conversation.admin.snoozed
    • conversation.read

At this point, the Intercom configuration is complete. You can request Human handoff in the Bot conversation window. When the Bot successfully initiates a Human handoff request, Intercom's Help Desk will receive the user's message. When you reply to this message, the Human handoff connection is officially established.

Webhook Authentication

Complete Tutorial Guide for Providing Human handoff Services via Webhook

  1. First, developers need to build a Webhook receiving service in their server environment, providing the following three interfaces to receive human service requests initiated by the Bot and to receive messages. For details, see Human Service Webhook.

    • Create Session: /conversation/establish
    • Chat: /chat
    • Close Session: /conversation/close

  2. Then, developers need to configure the URL address, username, and password of the Webhook receiving service in the Bot - Human Service configuration, so that the Bot can send messages to the Webhook receiving service. alt text

    URL Address: Required, used to receive messages sent by users on the bot side
    Username: Optional, determined by the webhook service built by the developer Password: Optional, determined by the webhook service built by the developer

  3. Finally, enable the API function in "Bot-Integration-API", and configure the GPTBots message reception address as the Webhook's message sending URL address, used to send human reply message content to the Bot chat window. For details, see Human Service Webhook.
    alt text At this point, the Webhook authentication configuration is complete. You can now request human services in the Bot chat window. When the Bot successfully initiates a human service request, the Webhook receiving service will receive the user's message.

livechat Authentication

  1. Developers need to create their own livechat account to get the organization_id. Create livechat account image-20241022201522994

  2. The developer needs to create APP, add Blocks, select App Authorization, and set it as a server-side app. On this page, it is possible to get the clientId.[Create APP](https://platform.text.com/console/apps/xf4PhOgNR/ monitor) image-20241022201629843

image-20241022201639199 image-20241022201648672

  1. Add Blocks, select APP webhook, and fill in the GPTBots message receiving address on the portal side as the webhook url. image-20241022201729792

  2. Add Bolcks, select Chat webhook and fill in the GPTBots message receiving address on the portal side as the webhook url. Select incoming_event and chat_deactiveted image-20241022201849040 image-20241022201857586

  3. Click on Private Installation to go to the page, Install APP image-20241022202514528

  4. Enter the organization_id and liveChatClientId from the previous preparation into the card and click OK to complete the configuration.At this point, livechat configuration is complete. image-20241022202903285

Configure Human handoff

Human handoff

alt text Service Status: Displays the availability of the third-party Human handoff system

  • Not Configured: When the third-party Human handoff system's authentication information has never been filled in
  • Service Available: When the authentication information is filled in and verified successfully
  • Service Unavailable: When the already filled authentication information fails/invalidates during the call Trigger Timing: Supports custom trigger timing descriptions to help LLM correctly determine when to call Human handoff

Timeout Mechanism

Timeout Waiting: Default 60 S,The maximum waiting time after a user initiates a request for human handoff. If the time is exceeded, the user will be prompted to end the current request or continue waiting.

Session Timeout: Default 180 S,After the last message from the human agent, if there is no user response within N seconds, the system will automatically exit the human service.

Human handoff Period

alt text

Supports custom settings for up to 10 Human service time periods

  • Weekly: In this mode, you can select Monday to Sunday and set the Human service time period, which will be executed weekly
  • Custom: In this mode, you must select an absolute date and set the Human service time period, which will be executed only once

When there are multiple Human service time periods：

  • First, filter out all "Human service time period" rules for the natural day based on the natural day dimension
  • Calculate all overlapping time rules parameters based on the widest time window rule. If they do not overlap, they will not participate in the calculation.
  • If there are multiple non-overlapping widest time windows, there will be multiple effective Human service time periods for that natural day.

    For example, on December 12, 2024, there are 4 effective Human service time rules: 09:00 ~ 12:00, 10:00 ~ 12:00, 13:00 ~ 18:00, 15:00 ~ 17:00.
    The system's effective service time window will be: 09:00 ~ 12:00, 13:00 ~ 18:00

Reply Outside Service Period

When the current Human service is in the "non-Human service time period," calling Human service will automatically reply with "preset text."

Transfer Conversation Content

When successfully calling the third-party service system, submit N rounds of chat records + user's latest question to the Human handoff system to help

Initiate a Human handoff Request in the Conversation Window

  1. User initiates a Human handoff request
    When the user wants to obtain Human handoff, LLM will determine whether to wake up the Human handoff. If LLM decides to wake up the Human handoff, it will call the Human handoff tools and ask the user to provide an email address. If the system already has the user's email information, the "input email" step will be skipped, and the Human handoff request process will be directly initiated. alt text
    • When the user is logged in and the account is verified by email, the system has the user's email information.
    • When the developer sets the user's email through the window.ChatBot.setEmail("somebody@mail.com") command in the bubble component scenario, the system has the user's email information.
    • When the developer sets the user's email through iframe_url + ?email=somebody@mail.com in the iframe scenario, the system has the user's email information.
  2. When the third-party Human handoff system receives the user's message and replies to the user's first message, the Human handoff session officially begins.
  3. The user can send unlimited messages with the Human handoff system. Both the user and the Human customer handoff personnel can actively close the current Human handoff conversation.

Connect to any third-party customer service systems such as Intercom, Webhook, LiveChat, etc. All the above-mentioned functions are applicable.