Einstein Bots Runtime - Java SDK
Also refer to Einstein Bot SDK public documentation
Java SDK to interact with Einstein Bots Runtime. This SDK is a wrapper around the Einstein Bots Runtime API that provides a few added features out of the box:
- Auth support
- Session management
Auth Support
Einstein Bots Runtime requires requests to be authenticated using OAuth. This SDK supports the JWT Bearer OAuth Flow.
Additional auth mechanisms can be added by implementing the AuthMechanism interface.
Session Management
A session ID is generated by Einstein Bots Runtime for every new session. This needs to be included in future requests sent to the service.
This SDK provides session management capabilities, caching Einstein Bots Runtime's session ID based on an external session ID.
An external session ID is the unique ID used to identify a session on the channel that is sending messages to Einstein Bots Runtime. Using Slack as an example,
the external session ID could be a combination of Slack app ID, Slack user ID and Slack channel ID (if present).
Redis
is supported out of the box. There is an InMemoryCache
included that is meant for testing purposes only. Additional caching methods can be used by implementing the Cache interface.
Usage
Add POM dependency
<dependency>
<groupId>com.salesforce.einsteinbot</groupId>
<artifactId>einstein-bot-sdk-java</artifactId>
<version>${einstein-bot-sdk-java-version}</version>
</dependency>
1. Create Redis Cache
Cache redis = new RedisCache();
Cache redis = new RedisCache(ttlSeconds, redisUrl);
2. Setup OAuth
private final String pvtKeyFile = "<your pvt key file>";
private final String loginEndpoint = "<your login endpoint>";
private final String connectedAppId = "<your connected app id>";
private final String secret = "<your connected app secret>";
private final String userId = "<userId associated with certificate used for connected app>";
JwtBearerOAuth oAuth = JwtBearerOAuth.with()
.privateKeyFilePath(pvtKeyFile)
.loginEndpoint(loginEndpoint)
.connectedAppId(connectedAppId)
.connectedAppSecret(secret)
.userId(userId)
.cache(cache)
.build();
You are also able to use a different constructor and pass in a java.security.PrivateKey
instead of a private key file.
JwtBearerOAuth.with()
.privateKey(privateKey)
.loginEndpoint(loginEndpoint)
...
3. Setup Chatbot Client
Follow step 3A to use BasicChatbotClient
if you want to track sessions yourself or
follow step 3B to use SessionManagedChatbotClient
for sessions to be managed by SDK.
3A. Setup Basic Chatbot Client
ChatbotClient client = ChatbotClients.basic()
.basePath(basePath)
.authMechanism(oAuth)
.build();
3B. Setup Session Managed Chatbot Client
SessionManagedChatbotClient client = ChatbotClients
.sessionManaged()
.basicClient(BasicChatbotClient.builder()
.basePath(basePath)
.authMechanism(oAuth)
.build())
.cache(cache)
.integrationName(integrationName)
.build();
4. Sending a Message
private void sendUsingBasicClient(){
RequestConfig config = createRequestConfig();
BotSendMessageRequest botSendInitMessageRequest = BotRequest
.withMessage(buildTextMessage("Initial Message"))
.build();
BotResponse resp = client
.startChatSession(config, externalSessionKey, botSendInitMessageRequest);
System.out.println("Init Message Response :" + resp);
String sessionId = resp.getResponseEnvelope().getSessionId();
BotSendMessageRequest botSendMessageRequest = BotRequest
.withMessage(buildTextMessage("Order Status"))
.build();
BotResponse textMsgResponse = client
.sendMessage(config, new RuntimeSessionId(sessionId), botSendMessageRequest);
System.out.println("Text Message Response :" + textMsgResponse);
BotEndSessionRequest botEndSessionRequest = BotRequest
.withEndSession(EndSessionReason.USERREQUEST)
.build();
BotResponse endSessionResponse = client
.endChatSession(config, new RuntimeSessionId(sessionId), botEndSessionRequest);
System.out.println("End Session Response :" + endSessionResponse);
}
private void sendUsingSessionManagedClient() {
RequestConfig config = createRequestConfig();
BotSendMessageRequest botSendFirstMessageRequest = BotRequest
.withMessage(buildTextMessage("Initial Message"))
.build();
BotResponse firstMsgResp = client
.sendMessage(config, externalSessionKey, botSendFirstMessageRequest);
System.out.println("First Message Response: " + firstMsgResp);
BotSendMessageRequest botSendSecondMessageRequest = BotRequest
.withMessage(buildTextMessage("Order Status"))
.build();
BotResponse secondMsgResp = client.sendMessage(config, externalSessionKey, botSendSecondMessageRequest);
System.out.println("Second Message Response: " + secondMsgResp);
BotEndSessionRequest botEndSessionRequest = BotRequest
.withEndSession(EndSessionReason.USERREQUEST)
.build();
BotResponse endSessionResponse = client
.endChatSession(config, externalSessionKey, botEndSessionRequest);
System.out.println("End Session Response :" + convertObjectToJson(endSessionResponse));
}
public static AnyRequestMessage buildTextMessage(String msg) {
return new TextMessage()
.text(msg)
.type(TextMessage.TypeEnum.TEXT)
.sequenceId(System.currentTimeMillis());
}
public static RequestConfig createRequestConfig(){
return RequestConfig.with()
.botId(botId)
.orgId(orgId)
.forceConfigEndpoint(forceConfigEndPoint)
.build()
}
5. Getting Health Status
private void getHealthStatus() {
System.out.println(client.getHealthStatus());
}
Tips and Tricks
- If you use your own ObjectMapper instance in your application. Check how ObjectMapper is created in UtilFunctions.getMapper() to make sure to configure it correctly.
Otherwise, you may run into issues with serializing/deserializing JSON.
Full code examples
See ChatbotClientExamples for full code sample sending messages to Einstein Bots Runtime.
See OAuthExamples for using OAuth.
Developer Guide
Code Style
The project uses the Google Java Style Guide.
Format settings definition files for importing into IDEs are available for Eclipse
and IntelliJ IDEA.
Publishing to Maven Central
Publish Release Versions
Go to actions tab and select Maven Release action. Click Run workflow , provide good description and hit Run workflow button.
Publish Snapshot Versions
Go to actions tab and select Maven Publish Snapshot action. Click Run workflow , provide good description and hit Run workflow button.
Choosing Release Versions
The version of the artifact released is same as version defined in pom.xml with -SNAPSHOT
removed.
After the release pom.xml will be automatically updated with next patch snapshot version.
For eg. if pom.xml
has version 2.0.1-SNAPSHOT
, then version 2.0.1
will be released and the pom.xml will be updated with version 2.0.2-SNAPSHOT
If you want to release a minor or major version, just update version in pom.xml, For eg, if you want to release 3.0.0
, then set version as 3.0.0-SNAPSHOT
in pom.xml.
Version Numbering
The minor and patch versions will be incremented for minor features and bug fixes.
The major version will be incremented for
- Major changes made to SDK OR
- New Runtime API version support is added.
Here is the SDK version and corresponding Runtime API version supported by it.
SDK Version | Supported Runtime API |
---|
1.x.x | /v4.0.0 |
2.0.x | /v5.0.0 |
2.1.x | /v5.1.0 |
2.2.x | /v5.2.0 |
2.3.x | /v5.3.0 |
Note: The support for rich links has been removed from API V5.1.0, please upgrade from SDK V2.1.0 to V2.1.1 or later.
Branching model to support development of multiple API versions
We will maintain the SDK code for each Runtime API version separately in individual branches.
We will cut off release branch for each Runtime API version.
For eg, Currently, the master branch is used to develop for Runtime API Version 5.1.0.
The releases/api-4.x branch is used to maintain support for API 4.0.0.
So to make change for SDK 1.x.x that supports API v4.0.0, it should be committed to releases/api-4.x
branch.
Also, choose releases/api-4.x
when running Release action workflow.