Side-loaded Bot

Overview

In this scenario, users interact with the Chime queue first, then are directed to a custom chatbot as part of the chat workflow. The custom chatbot can then deflect and end the user's chat, direct it to an agent in the same queue, or transfer the chat to another queue.

graph TD A[User] -->|Starts chat with Queue| B(Chime Queue) B --> |Chime connects over Direct-Line| C(External Chatbot) C -->|Chatbot handles request successfully| D[Deflects and Ends Chat] C -->|Route to Agent in same Queue| E(Chime Queue) C -->|Transfer Request to different Queue| F[Other Chime Queue]

Examples

C# Example using Bot Framework V4

Configuration

Configuring External Chatbots in Chime

External chat bots that are invoked by a Chime queue need to first be registered in the Chime Admin area.

To register a bot, you will need information collected from the Azure Portal for the chatbot.

  • Bot Name - This should be the same as the Bot handle in the Azure Portal for the bot.

  • Bot ID - This should be the Microsoft App ID in the Azure Portal for the bot.

  • Bot Direct-Line Secret - This should be one of the Secret Keys for the Direct Line Channel enabled for the bot in the Azure Portal

Configuring a Registered Chatbot for a Queue

Once a chatbot has been registered in the Admin section of Chime, it can be added to a queue. This is done in the Queue Settings section for the queue, in the Integration tab.

There are several settings that fine-tune the behavior of how the chat bot is invoked from the queue here:

  • When to invoke bot This determines whether the bot is invoked and surfaced to the user before or after they receive the Initial Welcome Message text resource from the queue.
  • Bot Inactivity Timeout This is a timeout that can be configured to set the limit for how many seconds the Chime queue should hold a chat open with the chatbot if neither the chatbot or the user have sent any messages. In the event that either party stops responding, when this timeout elapses, the action specified by the Bot Inactivity Timeout Action will be executed.
  • Bot Inactivity Timeout Action In the event of an inactivity timeout, the connection to the external chatbot will be closed and one of the following actions will be taken by the Chime queue:
    • Route to Agent - The chat will be directed to route to an agent in the queue.
    • Deflect Chat - The chat will be ended and marked as deflected by the chatbot.
    • Transfer to Queue - The chat will be redirected to a different Chime queue.

Configuring a Chatbot as an Interview Action

Chatbots can also be integrated into a Chime queue as part of an interview flow.

This is the appropriate path to pursue if you have multiple chatbots or Q&A chatbots that cover different scenarios and want to use them in the same queue.

NOTE: Chatbots configured as part of an interview will use the same bot inactivity timeout settings that are configured on the Integration tab of the queue's settings.

Implementations Details for Chatbots Intended to be Invoked by Chime Queues

Direct Line Channel Required

A chatbot that is intended to be invoked by Chime must have the Direct Line channel enabled. Currently, this is not enabled by default when creating a Bot Channels Registration for a chatbot in the Azure Portal, so it is necessary to add this Channel.

If the chatbot is doing any kind of filtering based on the Bot Framework Activity.channelId value in message activities that it receives, then it must allow and handle activities with the "directline" channelId. This is less common with V4 of the Bot Framework SDK, but may be an issue if still using the older or lower-level versions of the SDKs.

Handling User Information Sent by Chime

When Chime invokes the external chatbot and creates a Direct Line channel session with the chatbot, your chatbot should receive three "conversationUpdate" type activities from Bot Framework.

  • The first two conversationUpdate activities are automatically sent as part of creating the direct line conversation to the bot, and can be disregarded unless otherwise needed.
  • The third conversationUpdate activity should have a filled-out channelData property which will contain information collected by Chime about the end-user that is making the chat request to the queue.

An example of this third conversationUpdate activity is shown below:

{
  "type": "conversationUpdate",
  "from": {
    "id": "33ff7812-ca1c-4f32-b151-eb428e6c77f6",
    "name": "Bob Bolts"
  },
  "membersAdded": [
    {
      "id": "33ff7812-ca1c-4f32-b151-eb428e6c77f6",
      "name": "Bob Bolts"
    }
  ],
  "channelData": {
    "Email": "bboltss@example.com",
    "OriginalChannelId": "msteams",
    "id": "29:1HWq37SazBUW19j9e5ok0wadgasdgw_ypK5I8rMfLHbygy2RQpicvOQUf8dY5aobQ2qwr1g6N448wHo1EzK2g",
    "name": "Bob Bolts",
    "locale": "en-US"
  }
}

In the Bot Framework v4 SDK, this activity type is typically handled by overriding the ActivityHandler.OnMembersAddedAsync method in your derived Bot class.

Chime ChannelData fields

  • Email - The email address of the end-user, as collected by Chime
  • OriginalChannelId - This field captures the channelId of the channel that the original end-user used to contact the Chime queue (e.g. msteams, slack). This can be useful if the external chatbox wants to provide different experiences based upon the platform that the user is using, because otherwise the channelId of activities that the external chatbot receives will always be "directline".
  • id - This field captures the original end-user Bot Framework ID property. Note that this is often different from the value populated for the activity from.id field.
  • name - This field captures the original end-user Bot Framework name property. Note that this is often different from the value populated for the activity from.name field.
  • locale - This field captures the original end-user locale.

Special Slash Command Messages Recognized by Chime

Chime supports a selection of special commands that can be used by chatbots to manage the chat conversation and the flow of chat routing. We call these slash-commands, because they all begin with a forward slash (/).

  • /end - Ends the chat conversation with the end-user, and marks the chat session as deflected by the bot in Chime. Example: await turnContext.SendActivityAsync("/end");
  • /transfer - Instructs Chime to transfer the chat from the current queue to the queue with the specified Queue ID. Example: await turnContext.SendActivityAsync("/transfer 4");
  • /agent - Disengages the chatbox and instructs Chime to route the chat to a helpdesk agent in the current queue. Example: await turnContext.SendActivityAsync("/agent");
  • /agent / - Instructs Chime to route the chat to an agent in the current queue, and to also apply the specified skill/problem-tag to the chat session. Example: await turnContext.SendActivityAsync("/agent /VPN");

Examples of using these commands is provided in fuller context in the Chime_Bot_QueueCommands sample.

EndOfConversation Event

When Chime terminates a Direct Line conversation to the external chatbot, it will send a final Bot Framework activity of the type "endOfConversation".

Example:

{
  "type": "endOfConversation",
  "from": {
    "id": "33ff7812-ca1c-4f32-b151-eb428e6c77f6"
  }
}

In the Bot Framework v4 SDK, this activity type is typically handled by overriding the ActivityHandler.OnEndOfConversationActivityAsync method in your derived Bot class.

Adaptive Card Support

Chime should support Adaptive Cards up to the 1.2 specification. You may encounter issues if your bot tries to send Adaptive Cards using elements and properties introduced in later versions of the specification.

fghazi