In this article, I’ll share a simple toolkit to create a bot you can deploy inside Salesforce. Installation should be about 3 minutes.

Bots provide a new way to interact with information. Instead of having to navigate through menus or switch between applications to get the information you need, they allow you to ask questions formulated in natural language using either your voice or text you type in an instant messaging-like interface. It’s like chatting with a smart friend: you ask questions and you get answers, without switching context.

Siri, Alexa, Facebook Messenger and Slack bots have made this new way of accessing information popular. Because the Salesforce platform is API first, it’s easy to make these bots work with Salesforce data. There are plenty of examples out there, including some that I have shared in recent months (see the resources section at the bottom of this article).

The same type of conversational interaction can also be useful inside a large application like Salesforce to provide quick access to information without leaving the task you are currently performing. The new Utility Bar in Spring ’17 offers the ideal opportunity for a bot-like component as components hosted in the Utility Bar are always at your fingertips.

Watch the video below to see the bot in action:

How Does It Work?

The Bot Toolkit is made of:

  • A collection of Apex classes that orchestrate bot requests and facilitate the creation of bot request handlers
  • A Lightning Component that you can deploy in the Utility Bar and that provides the instant messaging-like interface to communicate with the bot

Let’s explore how it all works in more detail.

Bot Commands

The Bot Toolkit uses a custom object (Bot_Command) to store bot commands. A bot command represents a mapping between a regular expression (that provides a pattern for a user question) and an Apex handler class (that provides the logic to generate the response).

For example, a Bot_Command record may look like this:

Pattern Apex Class
(?i).*contact ([A-Za-z0-9]*) HandlerFindContact

With that command in place, a user can ask a question like “Find contact Lisa“, “Search contact Lisa“, or simply “Contact Lisa” (all matching the regular expression), and the Bot Toolkit will pass that request to the HandlerFindContact handler, providing “Lisa” as a parameter.

The Bot Toolkit comes with a series of standard bot commands and their corresponding Apex handler classes. You can add your own bot commands by adding records to the Bot_Command object and providing mappings between regular expressions and your own Apex handlers.

Note: Some of the Apex handlers are provided for demo purposes only and have hardcoded values or images.

Apex Classes

The Bot Toolkit comes with a series of Apex Classes. The BotController class is orchestrating the conversation. It exposes the submit() method that the Bot component calls to submit a question. The submit() method is where the BotController will try to match what the user typed to a regular expression defined in one of the bot commands. If a match is found, the bot controller calls the handle() method in the corresponding handler class. Handler classes implement the BotHandler interface. A handler class uses a series of utility classes to format the response that is sent to the user: BotResponse, BotMessage, BotMessageButton, BotItem, BotRecord, BotField.

Stateful Conversations

In addition to straight question/answer interactions, the Bot Toolkit also supports stateful conversations using a session object that represents the state of the conversation and that is passed back and forth between the server and the client. Take a look at the HandlerAddTwoNumbers and HandlerTravelApproval classes for examples of stateful conversations.

Message Formatting

The handle() method of a handler class returns a BotResponse object. A BotResponse is made of one or several BotMessage objects and an optional session object. A BotMessage can contain a plain text message, a list of items, a list of records, a list of postback buttons, or an image. The Bot component formats messages in different ways to best represent the content of each message. The table below provides a few examples:

Plain text message
Message with list of items
Message with list of records
Message with postback buttons
Message with image

Installation Instructions

Follow the instructions below to install the Bot Toolkit in your org:

  1. Ensure your org is ready for Lightning Components (Enable Lightning Experience, set up My Domain, and deploy to all users).
  2. Click this link to install the Bot Toolkit unmanaged package in your org, and select Install for All Users.
  3. Make a copy of the bot_commands.csv file on your file system
  4. In Setup, click Data > Data Import Wizard and Launch Wizard. Click Custom Object, select Bot Commands, Add New Records and import bot_commands.csv
  5. In Lightning, open the Bot Toolkit application, click the Bot Commands tab and familiarize yourself with the list of standard commands.
  6. Click Bot in the Utility Bar, and type commands for example:
    • help
    • account united
    • contact jo
    • help lightning
    • my cost center
    • my employee Id
    • my open cases
    • my pipeline
    • my quarter
    • SELECT Id, Name from Contact LIMIT 5
    • top 3 opportunities
    • travel approval
    • what should I do next?

You can also install the component in any other Lightning Application, for example the Sales application.


Bots allow you to quickly access information using natural language and without switching context. The Bot Toolkit shared in this article is provided as an example of an interesting Lightning Component powered by a small Apex framework. While this is not an official Salesforce project, you can get the source code from this repository. Feel free to contribute, or comment below.


Get the latest Salesforce Developer blog posts and podcast episodes via Slack or RSS.

Add to Slack Subscribe to RSS