Get Started With Version 4

Now you’re ready to start using your Einstein Bots API. Your bot uses the Einstein Bots API to have conversations with customers. Each bot session is a new conversation. The customer interacts through a service client (a custom chat client), such as a chat window or text messenger, with the bot and determines when the session begins and ends. If the session isn’t closed by the customer, the bot’s runtime automatically ends the session after three days of inactivity.

To view the endpoints, see the API Reference.

First, retrieve the Einstein Bots API endpoint needed for requesting calls. Use the host URL that you retrieved in the Get Started with Einstein Bots API section.

Here is an example endpoint.

Then send the message request. This command demonstrates how to do that with cURL. YOUR_REQUEST_BODY.json is the payload in JSON format and contains the message type and content.

The required request headers are:

X-Org-Id: The 18 character org ID of the Salesforce org associated with the bot. To get the org ID, Find your Salesforce Organization ID and then convert it from the 15 to 18 character version.
X-Request-Id: The unique UUID in string format to help with request tracking. You need to create the UUID.

You can find the Einstein Bots API specification, such as the payload and response body schemas for the different message types, using this endpoint:

The customer needs to initiate a new session. For a new bot session, the Einstein Bots API expects a single init message in the messages array in the payload. This payload has the InitMessage schema.

Here is an example payload of a customer starting a new session by typing “Hello”.

The required request body parameters are:

botId: The Einstein Bot ID that interacts with the Einstein Bots API. You can find this ID in the URL of the Bot Overview Page.
messages: An array of message objects with these required fields.
- sequenceId: The message number generated by the service client. It increases with every message in a session.
- type: The type of message, which is init for a new session.
forceConfig:
- endpoint: The instance URL of your Salesforce org. See View instance information for your Salesforce Organization.

Here is additional information:

externalSessionKey: Optional. A unique UUID in string format for the conversation. You can use externalSessionKey to trace conversations in your bot’s event logs.
messages:
- variables: Optional. For Einstein Bots API, including the integration name and type for the init message object are optional but are recommended.
  - IntegrationName: The value contains the integration name that you entered when adding the connected app to your bot. See Get Started with Einstein Bots API. If this is left blank, the service finds and uses the first integration name that you created. If you manually add the integration name and the validation fails, you get an HTTP 403 Unauthorized error.
  - IntegrationType: The value contains the integration type, which is API. Any other values are rejected with an HTTP 403 Unauthorized error

This example shows the response to a new session request in JSON format. This has the TextResponseMessage schema.

Here is information about some response fields:

sessionId: The unique bot session ID used in all requests tied to the same bot session. A new ID is generated automatically by the Einstein Bots API on every request with an init message type. This ID is stored for up to 3 days.
botVersion: The version of the bot at the time the request is sent.
messages: The bot’s output.

After the session is established and you have a unique sessionId, your bot can receive subsequent chat messages from the customer. If you already started the conversation, you can enter the previous chat response ID in inReplyToMessageId. The messages array in the payload has the TextMessage schema and text message type.

This example shows the customer sending “Great.”

Now let’s get the bot to respond to the customer with a question. A bot can send questions with a selection of answers to choose from, and the customer can select the answer using choices buttons or type the answer. This bot response has the choices message type in the messages array of the payload with the ChoicesResponseMessage schema.

In this example, the bot asks what language (English, Spanish, or Japanese) the customer wants to communicate in.

Let’s say the customer answers by clicking the “Spanish” button. The request has the ChoiceMessage schema for the messages array in this payload.

When the customer answers by clicking a button, the request contains the choiceId for the answer.

If the customer types an answer, use the TextRequestMessage schema for the messages array in the payload. If a valid answer is not provided to the choice question, the bot sends the question again Here’s an example of a customer that types “Español” as their answer.

The bot sends an escalation message when the bot is unable to answer the end-customer’s request, or when the bot encounters an error during runtime. During the bot configuration, you or your bot admin can define a dialog rule to transfer the bot session to another bot, skill, or queue.

Let’s say that you or your bot admin configures a bot with the Bot Builder to manage and display order statuses only but the customer asks about changing the order delivery address. In the active session, the bot API sends an escalation response back to the service client. This is where the API hands off the escalation to the service client. You then program the service client to perform the next steps, such as opening a ticket or transferring to an agent queue. It’s up to you to define what third-party channels you want to integrate with the service client and how the service client responds to this escalation message.

If the bot encounters an error at runtime, the bot moves to the Error Handler dialog. By default, this dialog sends an escalation message to the service client. However, you can modify the dialog or send the bot to a different dialog instead.

Here’s an example of a customer being transferred to an agent queue. At runtime, the bot sends a response with the escalate message type and EscalateResponseMessage schema in the messages array of the payload.

Following an escalation message, configure the service client to send a successful transfer or failed message.

Here’s an example where the service client sends a transfer success message to the bot. The messages object in the payload has the transferSucceeded type and TransferSucceededRequestMessage schema.

If the bot sends an escalation message but isn’t able to transfer the customer to the directed source, configure the service client to send a transfer failed message to the bot.

For example, if the Transfer to Agent bot action fails, the bot moves to the No Agent dialog automatically. See Set Up a Dialog Rule Step. After that, you can configure this dialog to route the customer to a different transfer target, a different dialogue, or present the customer with other options as you like. See Understanding System Bot Dialogs. You still need to configure the client to send a transfer failed message back to the bot.

Here’s an example of a transfer failed message. The messages object in the payload has the transferFailed type and TransferFailedRequestMessage schema.

If the bot has no more actions to take, the customer can end the session. This request uses the EndSessionMessage schema for the messages object in the payload and the endSession message type. If the endSession message isn’t sent, the session stays open for 3 days and then times out.

Here’s an example of the session ending because the customer is transferred to another source.

Then the bot responds with a session-ended message. Here, the messages object in the response body has the SessionEndedResponseMessage schema and sessionEnded message type.

Now that the bot session has ended, you can clean up any resources allocated to the service client and reuse the sessionId for a new bot session.