The Einstein Bots Platform API is a new REST API that allows you to interact with your Einstein Bots from any client. We’ve also created an open-source Java SDK and Channel Connector to give you the tools you need to easily integrate Einstein Bots into any of your conversational channels on top of the existing digital engagement channels that are supported by Service Cloud.
In the previous post, we showed how to use a basic bot client with the Java SDK to connect your channel to the Einstein Bot. In this post, we will look at the SDK’s session-managed client and its features. You’ll learn how to simplify your implementation by automatically managing sessions for your conversation channel. Additionally, you’ll learn to how to use the included cache, or provide a custom cache implementation, with the session-managed client.
Recap of the basic bot client
Before looking at a session-managed client, let’s do a quick recap. Here are the high-level steps to using the basic bot client. You can find code examples in our previous post.
- Create a basic chatbot client
- Call the
startChatSession()method to start a session using your
RuntimeSessionIdfrom the bot’s response
- Call the
RuntimeSessionIdto send a message to the active session
- Call the
endChatSession()method to end the session when the conversation ends
BasicChatbotClient interface for your reference.
When should a new session start?
The challenge is that you must know when you have to start a new session (versus send a message to an existing session) and call methods
sendMessage() appropriately. In some cases, the channel doesn’t have clear boundaries between sessions to be able to tell when a new conversation session begins.
For example, let’s say a bot is listening on a Slack channel and a user posts a message. You must start a new session when the user posts a message for the first time (or after a long time, based on session time-out). Alternatively, if the user is already in active conversation, you can just send a message to the existing session.
To send a message to the existing session, you have to track the active sessions of users along with
RuntimeSessionId. The good news is that the session-managed client already provides this functionality, so you don’t have to implement it.
Introducing the session-managed client
Let’s first look at the
SessionManagedChatbotClient interface to see the difference between it and the
BasicChatbotClient noted above.
Notice two differences from the
- There’s no
startChatSessionmethod, but only
- The methods accept only
The benefit of using a session-managed client is that you don’t have to call the
startChatSession() method explicitly, and you don’t have to know about
RuntimeSessionId. The session-managed client will take care of the entire session management for you, and your application code can remain stateless. All the heavy lifting of maintaining the mapping between
RuntimeSessionId, along with determining when to start a new session, is taken care of by the session-managed client.
Using a session-managed client
Enough theory — let’s write some code for using a session-managed client. In this section, you’ll learn how to implement a full conversation life cycle, such as initiating a chat session, sending a message to the current session, and ending a chat session.
1. Add a POM dependency
Find the latest
einstein-bot-sdk-java version from Maven Central and add this dependency to your
2. Create a session-managed client
JwtBearerFlow for OAuth, and it adds session management capabilities on top of the
BasicChatbotClient. The next step is to pass
BasicChatbotClient as parameters for
We’ll discuss the
cache parameter later in this post.
3. Create a request config
RequestConfig with your
forceConfigEndPoint. To find these values, refer to the Einstein Bots API Developer Guide. Typically, you want to create a config one time per bot in your org and reuse it for every request.
4. Send a message
First, create an
ExternalSessionId to uniquely identify a session in your channel. For example, it could be “userId” for Slack, or “twitter thread” for Twitter. Then, create a
BotSendMessageRequest and call the
sendMessage method to send.
5. End the bot session
The code is the same as with the
BasicChatbotClient except that you pass an
ExternalSessionId instead of the bot’s internal session ID.
How the session-managed client tracks sessions
You’ve now learned to use the session-managed client provided by the SDK, but session tracking logic will depend on your channel, and you might need to customize it for your use case. So, it’s useful to understand how the session-managed client works.
The session-managed client tracks sessions based on a combination of
OrgId. If the client sends a message request with a new combination of those IDs, it automatically calls
startChatSession to start the chat session. It retrieves the
startChatSession and adds mapping between active sessions and
RuntimeSessionId in a
Cache. If the combination of
OrgId already exists in
Cache, it will
sendMessage to the existing session using the cached
Cache can now be customized for your needs.
Customizing the cache used by the session-managed client
You are almost done! In this last section, you will learn how to customize the cache for your needs because the cache
is an important layer that is specific to your application architecture.
Choosing a cache library
We have included
RedisCache out of the box.
InMemoryCache helps you easily run in a development environment. It isn’t recommended for use in a production org.
You can use
RedisCache to easily deploy and run it in a cloud infrastructure. If you can’t use Redis, you can provide your own cache implementation.
Providing your own cache implementation
If you want to use any other distributed cache service (for example, Memcached), we’ve provided a cache abstraction. You can implement this cache interface according to your cache system and pass it to
.cache method of the session-managed client builder.
To recap, you have learned how to simplify your Einstein Bots integration using the session-managed client and how to customize it for your needs. This saves you time because:
- The session-managed client simplifies connecting to Einstein Bots by automatically managing sessions
- You don’t need to explicitly start a session or track runtime session IDs
- You can use the provided
RedisCacheor provide your own cache implementation for tracking sessions
To learn more, refer to Einstein Bot SDK user guide.