In our blog series on the Einstein Bots Platform API, we’ve been doing a deep dive into different aspects of using the API to help you get the most out of it in your digital channels. In this fourth post in the series, we’ll focus on how to use the Einstein Bots Channel Connector Framework with Twitter, so you can use Einstein Bots to monitor and respond to tweets.
Let’s do a brief recap of our series so far. The first blog introduced the fundamentals of Einstein Platform Bots API including authorization, authentication, and session management. In the second blog, we covered the details of using a session-managed bot client and cache management. The Channel Connector framework was introduced in the third blog, which provides a set of tools to simplify building external channel connectors for an Einstein Bot. It’s a Spring Boot Starter that can define a connection to a pre-configured bot with a few configuration parameters.
The code repository for the Channel Connector contains an examples folder with sample connectors for Twitter, Microsoft Teams, Slack, and text messages. These examples can be built upon and can be used on their own or they can be referenced to develop new custom connectors. Let’s get started looking at the Twitter connector.
Introducing the Einstein Bot Channel Connector with Twitter
With the Einstein Bots Channel Connector Framework, Einstein Bots can extend their reach to Twitter. You can configure them to monitor conversations, respond to direct queries, and connect customers to agents 24 hours a day, 7 days a week.
In this article, we’ll walk through the implementation of a channel connector that uses the Twitter API to monitor a set of keywords or mentions. Then, the Channel Connector framework forwards these tweets to an Einstein Bot. The complete code for this demo is available in the examples folder in this repo. The project requires certain configurations to connect it to your Twitter developer account and Einstein Bots. We’ll explain these parameters, and how to obtain them, in the next section.
Prerequisites
For those who are new to Einstein Bots, Salesforce provides rich documentation and Trailhead modules that cover bot design. For this example, we’ll start with an Einstein Bot that has already been designed. To access the bot through the API, we must create a new connected app and connect it to your Einstein Bot. After this step, you’ll have the orgId, botId, runtime-base url, and ForceConfig endpoints for your bot, which we’ll use later in the application.properties file during app configuration.
A Twitter developer account is also required to be able to use the Twitter API. After you have set up the developer account, create a project and generate two sets of keys and tokens. The first set of keys is the OAuth Consumer Key and Secret, which can be created by following these instructions. The second set of keys is the Access Token and Secret. To create the Access Token and Secret:
- Turn on user authentication in settings→OAuth1.0a settings and configure the permissions. The Twitter app must have both READ and WRITE permissions.
- Install twurl and run it using your consumer key and secret generated earlier:
twurl authorize --consumer-key "your_key" --consumer-secret "your_secret". Then, follow the onscreen instructions:- Visit the link output by the above command, which allows you to authorize the app.
- After it’s authorized, it generates a PIN that must be entered into the terminal.
twurl stores the Access Token and Access Token Secret in ~/.twurlrc.
Creating a Java Spring application
Our demo is built using Java Spring, which is an open-source framework used to create enterprise applications. We’ll Apache Maven for build automation and dependency management. A Maven archetype is provided in the project directory to create a new project.
This demo connector will be a standalone application that will monitor tweets using the Twitter API using a set of defined rules. Once a tweet matching the required criteria is found, it is sent to a connected Einstein Bot using the Einstein Bots API, and the response from the bot is sent back to the author of the tweet.
The newly created project has the skeleton code and all the dependencies for Einstein Bots connectivity predefined. Next, we’ll add the corresponding dependencies for the Twitter API as detailed in the next section.
Project dependencies
The project dependencies are defined in pom.xml and the newly created project includes all the dependencies required by the Channel Connector framework by default. As such, it only requires the dependencies for the Twitter API that have been added as follows in the dependencies section of pom.xml.
At the time of writing, the library versions were twitter-sdk-version=1.1.1 and okhttp-version=4.9.2. Setting up the bot connection involves the definition of a small set of configuration parameters discussed in the next section. With the dependencies taken care of, we can now implement our Twitter connector.
Code design
The design of the web application consists of two main services:
EinsteinBotService: a service that uses theSessionManagedChatbotClientprovided by the Einstein Bots SDK to send and receive messages to the target botTwitterStreamService: a service that continuously connects to the filtered Twitter stream and searches for mentions of handles defined intwitter.user.nameearlier
The TwitterStreamService connects to a filtered stream and receives tweets matching a defined set of rules. These rules are configurable and defined by the parameter twitter.rule.ids discussed in the next section. If there’s a failure or error, the service waits for a preconfigured short interval and retries to connect to the filtered stream. When a matching tweet is received, its text contents are sent to the Einstein Bot.
The Einstein Bot can be configured to answer frequently asked questions, log these tweets to Salesforce, directly engage the end user, or forward the tweets to an agent. After a response is received from the bot, the EinsteinBotService creates a response tweet and publishes it using the Twitter API.
The rest of the code deals with establishing secure communication with Einstein Bots and the Twitter API. The configuration parameters, created in the prerequisites, must be set in your project’s application.properties as described in the next section.
Configuration parameters
The project is fully configurable and designed to get its Twitter and bot-specific configurations from application.properties. Details for the configuration parameters are available at the code repo.
These parameters are sufficient to allow the newly generated project to successfully connect to your Einstein Bot and to your Twitter account. As such, the configuration parameters can be broadly categorized into two groups. The first set of parameters contains specifics for the Einstein Bot and the org to which it belongs. It also contains OAuth-related information, which would allow it to securely communicate with the Einstein Bot.
The second set of configuration parameters includes such things as the Twitter handle, rules to filter Twitter streams to identify Tweets, and authentication detail for the Twitter API. Note that Twitter API access will be restricted behind a paid tier after February 09, 2023.
Once the parameters are set based on the given instructions, the app is ready to monitor and send selected tweets to the Einstein Bot, and send the bot response back to the end user. In its current form, the Twitter connector is built to work with only one Einstein Bot and Twitter handle. However, it can easily be extended to monitor multiple handles and exchange messages with multiple Einstein Bots.
Conclusion
The Twitter connector is just one end-to-end example developed using the Einstein Bots Channel Connector Framework, and it allows Einstein Bots to monitor and respond to tweets. The Channel Connector framework provides a set of tools to simplify and accelerate the integration of many custom channels to Einstein Bots. The framework comes packaged with a comprehensive set of examples, including sample connectors for Slack, Twitter, Microsoft Teams, and even text messages using third-party providers. You can use these sample solutions on their own, or as a reference to develop custom connectivity solutions for your Einstein Bots.
About the authors
Asif Ali is a Principal Software Engineer at Salesforce working on Einstein Bots. Follow him on LinkedIn.
Atul Kshirsagar is Software Architect at Salesforce working in Einstein Bots. Follow him on LinkedIn and Twitter @atulckshirsagar.