Skip to main content

Bot Agent Connector—API

  • Chat

Updated ~ minute read

Introduction

The Bot Agent Connector uses a Direct Line Connector to allow Live Assist for Microsoft Dynamics 365 to communicate with your Bot.  The Bot Agent Connector allows information and controls to pass between Live Assist.

Prerequisites

This article assumes you are familiar with:

Message Types

The Direct Line Connector sends messages as JSON to your bot.  The message type allows you to perform a suitable behaviour.  Typically, this article uses javascript nomenclature, to refer to JSON attributes; if you are developing a C# bot you are likely using Data Objects to access the same attributes.

Live Assist maintains the order it receives messages it sends to bots.  Live Assist waits for acknowledgement of a message before sending a bot the next message. If there is no acknowledgement, Live Assist will attempt to resend the message.

When a bot receives a message, the Direct Line Message Type (or session.message.sourceEvent.type) informs the bot what event to handle.

Important: The message Type and corresponding Source Event are not mandatory, therefore bots must handle the situation if they are not present.

The message types for Live Assist are one of the following:

Attribute Information
visitorMessage A message from the visitor
systemMessage A message sent from the Live Assist system, usually these are automatic prompts, or pre-defined messages, such as: "We will be with you shortly."
otherAgentMessage

A message from another agent. Typically this will be a supervisor.
Messages of this type may also specify:

  • sourceEvent.isInternal
    True if the message is an internal message between agents which is not displayed to the visitor.
transferFailed A notification that a transfer attempted by the bot has failed. Messages of this type will also include:
  • sourceEvent.agent OR sourceEvent.skill
    The agent or skill name that the transfer request was targeting.
  • sourceEvent.reason
    A String describing the reason for the transfer failure
visitorContextData Data about the visitor, including Authenticated Data when applicable.
visitorContextData lets you send information about the visitor to your chat bot.
Although it is likely to arrive at the start of a chat, a number of messages construct the complete visitorContextData; it can take time to receive all the messages. Bots do not wait for visitorContextData to complete; if your bots rely on this data, they must wait for it to arrive before processing.
 
  • chatActivityId(may arrive after the first message)
  • sourceEvent.language
  • sourceEvent.isAuthenticated
  • sourceEvent.type
  • sourceEvent.id
  • sourceEvent.lastName(only populates in Authenticated Chats)
  • sourceEvent.firstName(only populates in Authenticated Chats)
  • sourceEvent.email(only populates in Authenticated Chats)
  • sourceEvent.ipAddress
  • sourceEvent.pageHistory - An array of pages including:
    • page.url
    • page.startTime
    • page.timeOnPage
    • page.title
  • sourceEvent.device
  • sourceEvent.ISP
  • sourceEvent.city
  • sourceEvent.country
  • sourceEvent.operatingSystem
  • sourceEvent.sourceUrl
  • sourceEvent.browserUserAgent
  • sourceEvent.browserVersion
  • sourceEvent.browserType

You bots may use additional data present on some messages, but these are beyond the scope of this article.

Transfer to another Agent or Skill Group

Transfer depends on the Microsoft Bot Framework implementation, whether it is C# or Javascript.  The API can transfer in the following ways:

  • To an Agent by Name
  • To an Agent by ID
  • To an Agent by Skill Group

In Javascript:

  • Transfer By Agent Name:
    let msg = new builder.Message(session).sourceEvent({directline: {type: "transfer", agent: "agentName"}});
  • Transfer By Skill Group
    let msg = new builder.Message(session).sourceEvent({directline: {type: "transfer", skill: "skillName"}});
  • Transfer by Agent ID
    let msg = new builder.Message(session).sourceEvent({directline: {type: "transfer", agentId: "agentID"}});

In C#:

  1. Create a reply object on your Context Activity.
  2. Add a DataChannel JSON object specifying the transfer type, for example:
    reply.ChannelData = new LiveAssistChannelData()
    {
       Type = "transfer",
   Skill = "SkillGroup"
    };
  3. Send the reply to the Direct Line Connector.

Important: Transfer from bots to agent or skill groups is case-sensitive. If the bot transfers to the incorrect agent a transferFailed message contains an error "Agent not found".

If the agent-bot transfers a visitor to a nonexistent destination, the bot receives an error message.  This allows the bot to try an alternative destination, or inform the visitor of the error. If the transfer is successful, the engagement uses its configuration to manage the chat; maybe the engagement queues the chat.  There are no further callbacks into the bot.

An agent-bot performing a transfer is identical to a human agent performing a transfer.  The queue sends automatic messages to the visitor if they are queuing.  If you must queue your visitor, consider using the bot to let the visitor know prior to initiating the transfer. If the visitor does not wish to queue, collect as much information about the visitor as possible.

If you add reply text to a message containing transfer Channel Data, Live Assist processes the transfer and does not send a reply to the visitor. Send two replies to inform your visitor then perform the transfer.

Handling Sleeping Bots

Depending on your hosting options some providers may put inactive bots to sleep.  This is troublesome when a visitor starts a new chat because it takes some time to wake your bot back up again. Live Assist attempts to resend any messages that a sleeping bot rejects. There is no guarantee that sleeping bots wake up quickly, Live Assist cannot retry indefinitely, but in most cases the bots wake up and can begin processing messages as you expect.

Internal Messages

Only Agents and Bots can see Internal messages. Visitors do not see Internal Messages. Mark A message as internal by adding an isInternal flag with the value of true to a Direct Line sourceEvent on the message.

For example, in Javascript:

let msg = new builder.Message(session);
msg.sourceEvent({directline: {isInternal:"true"}});
msg.text("Agents, including bots and supervisors, can see this message, visitors can not.");

Chat Survey Data

Chat survey data is not available to Bots Agent Connectors.

Using Bot Builder SDK

The Microsoft Bot Builder SDK provide UX-elements for bots to send on to visitors using their supported channels.  Live Assist engagements do not support Microsoft Bot Builder SDK UX-elements. Agents or Visitors must send messages using the Bot Agent Connector in plain-text or be compatible with Live Assist Canned-Messages. Bots sending HTML to visitors render in the Live Assist visitor chat window.

Learning Path

See: Bot as an Agent—Learning Path

Related articles