Einstein Bots is a conversational chatbot solution that is powered by Salesforce’s Einstein AI Platform. Its job is to interact with customers and provide them with the information they need quickly without human intervention. It can also handles simple, repetitive tasks, freeing up agents to manage more complex cases.

In Spring ‘22, we released the Einstein Bots Platform API (Beta) to help customers leverage power of Einstein Bots on any digital channel. In Summer ’22, we have made the Java SDK and open-source Channel Connector available to simplify the bot developer experience. This gives 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 this post, we’ll look at how you can use the Einstein Bots Platform API, and we’ll also cover how to use the SDK and its benefits. Check out this previous blog post to get even more familiar with the Einstein Bots Platform API.

Using the Einstein Bots Platform API

The Einstein Bots Platform API is a REST API, and you can use it without the SDK. The Einstein Bots Platform API Client Guide provides instructions on how to integrate Einstein Bots with your channel using CURL or Postman. Let’s look at the actual Java code required to work with the Einstein Bots Platform API.

1. Create the JSON Web Token (JWT)

Einstein Bots require requests to be authenticated using OAuth. Any OAuth flows can be used to get the access token. Since this is a service-to-service integration, we will use the JWT bearer OAuth flow to mint the JWT and get the OAuth access token. Use your private key that you created in your connected app setup to create the algorithm for signing the JWT.

Then, create the JWT with appropriate values.

2. Get the OAuth access token

Send an HTTP post request to the https://login.salesforce.com/services/oauth2/token endpoint with jwt in the request body and using the appropriate HTTP headers.

Then, parse the response to get the access_token:

Now, we have the token required for authentication and are ready to make requests to the Einstein Bots Platform API.

3. Send a start chat session request

Send an HTTP post request to the https://<RUNTIME_BASE_URL>/v5.0.0/bots/{botId}/sessions endpoint with the authentication token and orgId in the HTTP headers. The RUNTIME_BASE_URL can be obtained from the Bot Overview page documented in the client guide.

You can parse the response to show the bot’s message to the user depending on the channel. For this example, we will just output to console which will look like this:

Next, we will need to extract the sessionId from the response to continue sending messages to the same session.

As you can see, there is a lot of boilerplate code required to use Einstein Bots Platform API directly. To simplify the integration and reduce much of the boilerplate code, we created an Einstein Bots SDK for Java.

Using the Java SDK to simplify an Einstein Bots integration

The SDK is a wrapper around the Einstein Bots Platform API that simplifies the integration by providing added features, such as authorization support and session management. Let’s look at some code for implementing the same example using the Einstein Bots SDK.

1. Add a POM dependency

Find the latest einstein-bot-sdk-java version from Maven Central and add this dependency to your pom.xml.

2. Create a chatbot client

The chatbot client provides JwtBearerFlow for OAuth, so create AuthMechanism with appropriate parameters. Then, create BasicChatbotClient with the auth mechanism and basePath of the Bot runtime URL.

3. Send start chat session request

First, create a RequestConfig with your botId, orgId, and forceConfigEndPoint. You can refer to the client guide to find these values. Typically, you want to create a config once per bot in your org and reuse it for every request.

Then, create a BotSendMessageRequest with TextMessage.

Use the startChatSession method to start a session.

Parse the response envelope and display the message to the user depending on the channel. The SDK will automatically deserialize the JSON to a Java model to make it easier. The code below shows how to parse the response as text for TextResponseMessage and ChoiceResponseMessage types. For all supported types and code, refer to the schema.

The output will look like this:

We have different Einstein Bots Platform API endpoints for continuing an existing session and ending a chat session. For completeness, let’s look at code examples for them.

4. Send a message to an existing chat session

The example code shows how to use the sendMessage method to send a message to an existing open chat session.

We used TextMessage in this example, but you can also send other types (e.g., ChoiceMessage) supported by the Einstein Bot Runtime Open API Schema.

5. End a chat session

Finally, here is example code for ending the session using the endChatSession method.

Benefits of using the Einstein Bots SDK

The Einstein Bots SDK provides lots of great features that can save developers time.

• It abstracts out the details of loading private key and minting JWT.
• It abstracts out token exchange to get OAuth access token.
• It provides model classes with strict type checking.
  • You don’t have to use convoluted JSON string serializing/deserializing of request/response bodies.
  • We used TextMessage in this example. Similarly, model classes are available for all schema objects defined in Bot Runtime Open API Schema.
• The code is more readable due to the dsl-like methods.
• If you use BasicChatbotClient demonstrated in the blog, you will need to keep track of sessions and call startChatSession or sendMessage method appropriately. Instead, use SessionManagedChatbotClient, which eliminates the startChatSession method. It will automatically create a new session based on the user-provided ExternalSessionId. We will publish a follow-up blog post on using SessionManagedChatbotClient.

And there’s more: the Channel Connector framework

In addition to the Einstein Bots SDK, we also released the Einstein Bots Channel Connector framework to simplify building a channel connector service using Spring Boot. It auto-configures Spring beans for foundational services, such as caching, authentication, and metrics, and makes it ready to use out of the box.

The Channel Connector framework includes a working example application and a maven archetype for creating a new bot channel connector application.

The image below summarizes the tools that we are releasing and the benefits that they provide.

Where to go from here?

• Find the full code example for using the SDK in the GitHub repo
• Refer to the SDK and Channel Connector user guides for documentation
• Learn more from the GitHub README and source code:
  • GitHub repo for the SDK
  • GitHub repo for the Channel Connector Framework

About the author

Rajasekar Elango is a Principal Software Engineer at Salesforce working on the Einstein Bots Platform. You can follow him on LinkedIn or Twitter.