Begin a Session

Here you learn how to start a new bot session.

To view the endpoints, see the API Reference.

To begin a session, the service client sends a request to the bot with this endpoint. The <HOST_URL> is the Runtime Base URL field found in the Add Connection dialog when you add the connected app to the bot. See Get Started with Einstein Bots API.

This example shows you how to initiate a bot session with this endpoint. Here the host URL is https://runtime-api-na-west.prod.chatbots.sfdc.sh.

The required path parameter is:

  • botId: Required. The ID of the Einstein Bot that you want to interact with using the Einstein Bots API. You can find this ID in the URL of the Bot Overview Page.

The required request headers are:

  • X-Org-Id: Required. The 18-character org ID of the Salesforce org associated with the bot. To get the org ID:
    1. Find your Salesforce Organization ID (15 characters long).
    2. Then convert it from the 15 to 18 character version. You can find Salesforce org ID converters using any search engine.
  • X-Request-Id: Required. The unique UUID in string format to help with request tracking. You must create the UUID.

YOUR_REQUEST_BODY.json is the request body or payload in JSON format with the chat content.

Here are the minimum request body parameters you require to begin a session.

Here are the required request body parameters.

  • forceConfig: Required.
    • endpoint: Required. The instance URL of your Salesforce org. You can find the value in the ForceConfig Endpoint field of the Add Connection dialog when you add the connected app to the bot. See Get Started with Einstein Bots API.
  • externalSessionKey: A unique UUID in string format for the conversation. You can use externalSessionKey to trace the conversation in your bot’s event logs.

Here’s a more complex example of a request body that begins a session. This request includes:

  • A customer starts a new session by typing “Hello”
  • The timezone where the customer is in
  • Bot variables initialized with a value
  • Extra information included in the response payload
  • The type of rich content the bot response supports (available in v5.0 only)

Here are the optional request body parameters used in this example.

  • message: An object containing the message from the customer to the bot.
    • text: The message from the customer.
  • tz: Optional. The time zone of where the customer is initiating the chat.
  • variables: Pass custom and context variables to the bot when initiating a chat session. See What’s a Variable?.
    • name: Required. The API name of a variable defined in the bot definition. For example, a bot admin can declare a variable “First Name” with the corresponding API name firstName in the Bot Builder page.
    • type: Required. The variable type, for example, the type is text for API name firstName. You can find the available variable types in the reference documentation.
    • value: Required. The value of the variable, for example, Test.
  • responseOptions: Configuration values for the response payload.
    • variables: Configure what variables are returned in the response.
      • include: Required. A boolean that indicates whether the response contains variables.
      • filter: An array of string variables names to limit the returned variables. If missing, null, or empty, no filtering is applied.
      • onlyChanged: Required. A boolean that indicates whether the response contains only changed variables.
    • metrics: A boolean that indicates whether to include metrics in the response.
    • intents: A boolean that indicates whether to include all intents that were detected when processing the current request.
    • entities: A boolean that indicates whether to include all entities that were detected when processing the current request.
  • richContentCapabilities: The configuration of rich content types supported by the client. See the Receive a File From the Bot for an example of how to use this parameter. Available in v5.0 only.
    • messageTypes: An array of message types supporting rich content.
      • messageType: The message type. Only StaticContentMessage is supported. It represents static or non-interactive content, such as links and attachments.
      • formatTypes: An array of format types.
        • formatType: The message format that is supported by the message type. For example, the Attachments format type shows the attachment as a downloadable file (rich content). If your client doesn’t support rich content, use the Text format type to show the file as a URL.

Here’s an example of passing optional custom and context variables to the bot when initiating a chat session. See What’s a Variable?.

In this example, the variables firstName, lastName, and emailId are custom variables defined by the pre-chat embedded form of the bot. The client passes these variables with values to the bot.

The IntegrationName and IntegrationType are context variables of the connection between the connected app and the bot. See Get Started with Einstein Bots API. For Einstein Bots API, including the integration name and type are optional but recommended.

This example shows the response to a new session request in JSON format. It uses the TextResponseMessage schema in the API reference doc.

Here are the response body parameters that you see in this example.

  • sessionId: The unique bot session ID that you must use as a path parameter on all subsequent chat messages in a conversation. 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 messages to the customer. The bot can send one or more messages.
  • processedSequenceIds: The sequence IDs of messages that the bot processed. The requests require a sequenceId except for the initial one to start the session.
  • intents: An array of the intents detected by the bot when processing the request. For a bot, "intent" refers to the goal the customer has in mind when typing in a question or comment. See Use Intents to Understand Your Customers.
    • label: The name or ID of the intent.
    • confidenceScore: The probability number that the AI assigns to this intent.
    • intentSource: The prediction system that detects the intent. The possible values are:
      • DIRECT: Utterance search or an exact match
      • CORE_NLP: Third-party Natural Language Processing (NLP)
      • EINSTEIN_NLP: Einstein NLP
  • entities: An array of all entities detected by the bot when processing this request. For a bot, "Entities" refer to the modifiers the customer uses to describe their issue and intent is what they really mean.
    • confidenceScore: The probability number that the AI assigns to this entity.
    • value: The value of the entity that the customer enters.
    • type: The entity type, for example, MONEY, LOCATION, or EMAIL. See the API reference for the full list.
  • _links: List of Einstein Bots API endpoints for HATEOS compliancy.
    • self: The endpoint of this request.
    • session: The endpoint to End a Session.
    • messages: The endpoint to Continue a Session, in other words, to send subsequent messages in an active session.