Bot Message Routing (component) [Typescript]

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.

(TODO) Possible use cases

• Routing messages between users/bots
  • See Chatbots as Middlemen blog post
• Customer service scenarios where (in tricky cases) the customer requires a human customer service agent
  • See Intermediator Bot Sample
• Keeping track of users the bot interacts with
• Sending notifications
  • For more information see this blog post and this sample

This is a Typescript solution, but don't worry if you prefer the C# SDK; in that case check out this sample!

Implementation

(TODO) Terminology

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.

(TODO) Interfaces

IRoutingDataManager

An interface for managing the parties (users/bot), aggregation channel details, the list of connected parties and pending requests.

(TODO) Classes

MessageRouterManager class

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.

Properties

• 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.

Methods

• 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.

(TODO) Other classes

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.

Contributing

This is a community project and all contributions are more than welcome!

If you want to contribute, please consider the following:

• Use the development branch for the base of your changes
• Remember to update documentation (comments in code)
• Run the tests to ensure your changes do not break existing functionality
  • Having an Azure Storage to test is highly recommended
  • Update/write new tests when needed
• Pull requests should be first merged into the development branch

Please do not hesitate to report ideas, bugs etc. under issues!

Acknowledgements

Special thanks to the contributors (in alphabetical order):

• João Almeida
• Christopher Harrison
• Eunji Kim
• Alejandro Magencio
• Nafis Zaman

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.