This project is a message routing component for chatbots built with Microsoft Bot Framework Node SDK. It enables routing messages between users on different channels. In addition, it can be used in advanced customer service scenarios where the normal routines are handled by a bot, but in case the need arises, the customer can be connected with a human customer service agent.
For an example on how to take this code into use, see botframework-handoff.
This is a Typescript solution, but don't worry if you prefer the C# SDK; in that case check out this sample!
| Term | Description |
|---|---|
| Aggregation (channel) | Only applies if aggregation approach is used! A channel where the chat requests are sent. The users in the aggregation channel can accept the requests. |
| Connection | Is created when a request is accepted - the acceptor and the one accepted form a connection (1:1 chat where the bot relays the messages between the users). |
| Party | A user/bot in a specific conversation or can represent a channel (e.g. specific conversation channel in Slack) itself. |
| Conversation client | A reqular user e.g. a customer. |
| Conversation owner | E.g. a customer service agent. |
An interface for managing the parties (users/bot), aggregation channel details, the list of connected parties and pending requests.
MessageRouterManager is the main
class of the project. It manages the routing data (using the provided IRoutingDataManager
implementation) and executes the actual message mediation between the parties connected in a
conversation.
RoutingDataManager: The implementation of the IRoutingDataManager interface in use. This
property is set by passing the instance to the constructor of the MessageRouterManager class.
This project provides two implementations of this interface: LocalRoutingDataManager for testing
and AzureTableStorageRoutingDataManager. You can implement your own routing data management by
using the IRoutingDataManager interface as the base or deriving from
AbstractRoutingDataManager.HandleActivityAsync: In very simple cases this is the only method you need to call (in
addition to Diconnect). It will track the users (stores their information), forward messages
between users connected in a conversation automatically. The return value (MessageRouterResult)
will indicate whether the message routing logic consumed the activity or not. If the activity was
ignored by the message routing logic, you can e.g. forward it to your dialog.SendMessageToPartyByBotAsync: Utility method to make the bot send a given message to a given user.MakeSurePartiesAreTracked: A convenient method for adding parties. The given parties are added,
if they are new. This method is called by HandleActivityAsync so you don't need to bother
calling this explicitly yourself unless your bot code is a bit more complex.RemoveParty: Removes all the instances related to the given party from the routing data (since
there can be multiple - one for each conversation). Will also remove any pending requests of the
party in question as well as end all conversations of this specific user.RequestConnection: Creates a request on behalf of the given party/sender of the activity.RejectPendingRequest: Removes the pending request of the given user.ConnectAsync: Establishes a connection between the given parties. This method should be called
when a chat request is accepted (given that requests are necessary).Disconnect: Ends the conversation and severs the connection between the users so that the
messages are no longer relayed.RouteMessageIfSenderIsConnectedAsync: Relays the messages between connected parties.AbstractRoutingDataManager
implements the IRoutingDataManager interface partially and is the base class for both
LocalRoutingDataManager and AzureTableStorageRoutingDataManager. It contains the main logic for
routing data management while leaving the storage specific operation implementations
(add, remove, etc.) for the subclasses.
AzureTableStorageRoutingDataManager
implements the IRoutingDataManager interface. The constructor takes the connection string to your
Azure Storage.
LocalRoutingDataManager
implements the IRoutingDataManager interface. Note that this class is meant for testing and
provides only an in-memory solution. Do not use this class in production!
Party holds the details of specific user/bot in a specific
conversation. One can think of Party as a full address the bot needs in order to send a message to
the user in a conversation. The Party instances are stored in the routing data.
MessageRouterResult is the return
value for more complex operations of the MessageRouterManager class and methods of the
IRoutingDataManager implementation. You are responsible to handle these in your bot code.
For classes not mentioned here, see the documentation in the code files.
This is a community project and all contributions are more than welcome!
If you want to contribute, please consider the following:
Please do not hesitate to report ideas, bugs etc. under issues!
Special thanks to the contributors (in alphabetical order):
Note that you may not find all contributions in the change history of this project, because all of the code including this core functionality used to reside in the botframework-handoff project.