Passing Metadata From a Bot

Overview

When a seeker hits a queue in Chime to start a conversation, their first message activity will be unwrapped to create the chat session and collect metadata about the seeker.

The raw data that is collected for a session can be seen in the Metadata tab of the session details pop-out window.

Example Code to Construct an Initial Activity

In the code sample below is an example of how to construct a Message activity for the initial message to a Chime queue containing user metadata included in the activity.channelData property.

The Chime "email" and "skillTags" properties will be set by supplying a dictionary containing key/value pairs with those specific keys and the values for the user.

Example Code

public static Microsoft.Bot.Connector.DirectLine.Activity CreateActivity(
    string username, 
    string userId, 
    string messageText, 
    string email, 
    string problemTag, 
    string locale)
{
    var activity = (Activity)Activity.CreateMessageActivity();
    activity.From = new ChannelAccount(userId, username);
    activity.Text = messageText;
    activity.ChannelData = new Dictionary<string, string> {
        ["email"] = email,
        ["skillTags"] = problemTag
    };
    activity.Locale = locale;
    return activity;
}

###Example Usage

CreateActivity("Bob Bolts", 
               "9f6a6350-1cce-4045-a761-aabb9b103e08", 
               "Can't open my mail", 
               "bbolts@example.com", 
               "Outlook", 
               "en-us"
);

Example Output

{
  "type": "message",
  "from": {
    "id": "9f6a6350-1cce-4045-a761-aabb9b103e08",
    "name": "Bob Bolts"
  },
  "locale": "en-us",
  "text": "Can't open my mail",
  "channelData": {
    "email": "bbolts@example.com",
    "skillTags": "Outlook"
  }
}

Details

If there is a bot in front of Chime, it will connect to the queue over the Direct-Line channel. The first message type activity that the bot sends via direct-line to the queue will initiate the session, and be used to harvest seeker metadata.

Example Message Activity

{
  "type": "message",
  "id": "JfePDqtSF829wLDDFUOilf-6|0000000",
  "timestamp": "2020-11-11T18:55:47.4829151+00:00",
  "serviceUrl": "https://directline.botframework.com/",
  "channelId": "directline",
  "from": {
    "id": "2352352352",
    "name": "Bob Bolts"
  },
  "conversation": {
    "id": "JfePDqtSF829wLDDFUOilf-6"
  },
  "recipient": {
    "id": "eric_team_bot@FCIhnRu0OiQ",
    "name": "Eric Teams Bot"
  },
  "locale": "en-us",
  "text": "I am looking for help with Outlook",
  "channelData": {
    "email": "bbolts@example.com",
    "skillTags" : "Outlook",
    "customValue" : "abc123"
  }
}

From this activity, the following values for the Chime seeker metadata will be extracted:

Values extracted from the Activity

Activity Field	Chime Seeker Field	Value From Example Activity	Note
"text"	"question"	I am looking for help with Outlook	Recorded as the seeker question
"from.name"	"SeekerDN"	Bob Bolts	Full name of the seeker
"from.id"	"sip"	2352352352	internal use
"recipient.id"	"entryPoint"	eric_team_bot@FCIhnRu0OiQ	Records the Chime queue bot endpoint that the seeker entered via
"locale"	"locale"	en-us	Language locale of the seeker, used for text analytics
"channelId"	"webVisitor"	true	Direct-Line chats are treated as web client chats for reporting, vs Teams Client chats
"conversation.id"	"sessionGuid"	JfePDqtSF829wLDDFUOilf-6	Used by Chime as an identifier to tie the Bot Framework session to the Chime chat session

Additionally, any key/value pairs provided as part of the "channelData" object will be added to the metadata for the chat session.

When these properties match named keys that have special meaning in Chime, they will be applied and available in text resources and other locations as normal. Values that do not match named Chime keys are still available in text resources through the @Model.Custom.keyName syntax.

Values harvested from channelData

Activity Field	Chime Seeker Field	Value From Example Activity	Note
"channelData.email"	"email"	bbolts@example.com	Seeker email
"channelData.skillTags"	"skillTags"	Outlook	Skill Tag for the chat
"channelData.customValue"		abc123	Accessible in text resources through @Model.Custom.customValue

Special Handling of Seeker Email and activity.from.id

For historical reasons, if the from.id field that is present as part of the message activity is an email address, this will replace any other value that has been sent as an email value.

Therefore, given this message activity:

{
  "type": "message",
  "id": "JfePDqtSF829wLDDFUOilf-6|0000000",
  "timestamp": "2020-11-11T18:55:47.4829151+00:00",
  "serviceUrl": "https://directline.botframework.com/",
  "channelId": "directline",
  "from": {
    "id": "foo@bar.com",
    "name": "Bob Bolts"
  },
  "conversation": {
    "id": "JfePDqtSF829wLDDFUOilf-6"
  },
  "recipient": {
    "id": "eric_team_bot@FCIhnRu0OiQ",
    "name": "Eric Teams Bot"
  },
  "locale": "en-us",
  "text": "I am looking for help with Outlook",
  "channelData": {
    "email": "bbolts@example.com",
  }
}

The seeker email value that is ultimately recorded for a chat initiated with this message activity would be "foo@bar.com" and NOT "bbolts@example.com"

Named Chime Seeker Data Key Names

fghazi