Salesforce Service Cloud: Integrate Live Chat Handover



The Salesforce Service Cloud enables the forwarding of a chat conversation to a Salesforce service agent in order to provide detailed expertise information to the user. This tutorial will explain how to integrate an organization's Salesforce instance to a Cognigy.AI virtual agent and finally hand over a bot conversation to the Salesforce Agent Chat.

   Watch Cognigy Showcase "Customer Service with Salesforce Live Agent handover"

Table of Contents

  1. Native Handover Provider
  2. Install the Salesforce Service Cloud Extension
  3. Setup a Salesforce Chat Agent
  4. Create a Salesforce Connection
  5. Create a Handover Flow
  6. Establish Persistent Messaging

Native Handover Provider

With Cognigy.AI version 4.16.0, the Salesforce Service Cloud handover is provided natively within the Endpoint configuration. Watch the following to learn how it works:

DEPRECATED Install the Salesforce Service Cloud Extension

Before the Cognigy.AI virtual agent is able to forward a chat to Salesforce, the required integration needs to be installed. In this case, a so-called Extension is uploaded to Cognigy.AI. First, navigate to the Extensions Marketplace inside of the Virtual Agent and add the Salesforce Service Cloud Extension by clicking on the Install button. Now follow this installation guide and upload the Extension to Cognigy, where it will be displayed as the following:


Congrats! The installation of the Extension is finished!

Setup a Salesforce Chat Agent

If the Service Cloud is already in use, the required information might be available. Please check if the following credentials are provided in the Salesforce instance:

Salesforce ...

If it is the case, that no Chat Deployment is available in Salesforce at the moment, please follow these guides:

Finally, one will find a created Chat Deployment in the Salesforce Setup, such as:


The information/credentials that are required for the next step can be found in the detailed view of the new Chat Deployment (in this case "First Agent"):


In the above figure, this information is hidden. However, one can extract the Deployment ID, Organization ID, and Live Agent URL from the HTML code that can be found in the Deployment Code section:

liveagent.init('Live Agent URL', 'Deployment ID', 'Organization ID');

The missing Live Chat Button ID can be found in the Setup as well:


By clicking on the created button and then scrolling down to the bottom, similar HTML information such as the Chat Deployment's one can be found:


While the sensitive information is hidden again, the Live Chat Button ID can be extracted:

liveagent.showWhenOffline('Live Chat Button ID', document.getElementById('liveagent_button_offline_...h'));

Create a Salesforce Connection

Since the previous chapter discussed how to set up the Salesforce side, one can now continue editing the Cognigy.AI virtual agent. In this step, a so-called Connection will be created. If one, in Cognigy.AI, clicks on the previously uploaded Extension, the following details can be observed:


The red-marked part in the above figure shows, that there is a Connection required. Therefore, it needs to be created and filled with the Salesforce Chat Deployment information. In order to do so, one initial Salesforce Flow node needs to be added to a Flow:

  1. Create a new Flow in Cognigy.AI
  2. Inside of the Flow Chart, click on + and navigate to the Salesforce Extension:


  3. For example, add the Check Live Agent Availability Flow Node by clicking on it:


  4. In order to edit the Flow Node and create the Connection, please click on it. An Edit Node menu will be opened on the right side of the screen:


  5. Right next to the Connection field (the first one at the top), one needs to click on the + button. The Connection menu will be opened at the center of the screen:

  6. Insert the related Salesforce Chat Deployment credentials/information to the fields.
    1. IMPORTANT! Please make sure that you remove the last "/rest/chat/" path from the Live Agent URL -- if not already. Otherwise, it will not work.
  7. Click on the Create button

Create a Handover Flow

From now on, it is possible to create a conversational integration with Salesforce and thus let the dialog expand its capabilities. Because of the fact that a Cognigy.AI conversation consists of different Flows, one should create a specific Handover Flow.

Basic Concept

As soon as the user has the intention to talk to a human, this Flow should be executed. The first step is to check if an agent is available at the moment. If this is the case, the live chat should be started. Otherwise, the virtual agent notifies the user that there is no agent available and tries to help with another solution.

Example in Cognigy.AI


Such as described in the Extension, the Check Live Agent Availability Node returns a Yes/No value that can be checked. In this example, the used IF Node includes the following condition:


With this functionality, the virtual agent can inform the user about the current status.

Example in Salesforce Service Cloud Console


If the availability check was positive, the Start Live Chat Node is executed which causes the incoming request in the Salesforce Service Console.

Advanced Concept

In order to provide some information about the previous bot conversation to the human agent, the transcript should be sent. In addition to that, the bot should let the user know that they are now talking to a connected human agent and, if it happens, that the human agent ended the live chat.


For the transcript of the conversation, one can use the Odata Analytics Endpoint and store it in the Context object -- the results can be filtered in the query. As a "one-click" solution, the Cognigy Extension could be downloaded, which contains the Get Conversation Flow Node. For the transcript, one needs to have the global Admin role in Cognigy.AI.

Handle Salesforce Events

Salesforce sends different events to the Cognigy.AI virtual agent that could be handled and be used for further actions. The two interesting events in this case are:

  • Chat Established
  • Chat Ended

Since the information is sent to Cognigy.AI in an incoming message from Salesforce, a Lookup Node can be used in order to check the current case:


Inside of the Lookup Node's configuration, it says

so that it looks up the current type of the incoming Salesforce message. Therefore, one could now add a SAY or GO TO Node, for example, in order to react to these events.

Establish persistent Messaging

While following the tutorial, one may notice that the chat messages are not sent to Salesforce and vice versa. The first reason is that Cognigy directly forgets that there is a handover and does not send the messages to Salesforce but to Cognigy.AI again. The second reason for this is the missing messaging service that is required for Salesforce Handovers. 

Cognigy Salesforce Transformer

In order to provide a persistent handover, the user messages must be directed to the Salesforce Service Cloud to be displayed to the human agent. For this, a so-called Transformer has to be used in the Endpoint (e.g. Webchat).

Example Webchat Endpoint

Inside the Webchat Endpoint in Cognigy.AI, the following code can be used as Transformer Function. Without going into too much detail, one can simply copy the below code and only change the first line. In this line, it says LIVE_AGENT_URL, while one needs to use their own Salesforce Live Chat URL:

const LIVE_AGENT_URL = "https://<your-value>";


    handleInput: async ({ payload, endpoint }) => {

        const sessionStorage = await getSessionStorage(payload.userId, payload.sessionId);

        let liveAgentSessionKey = sessionStorage?.liveAgentSessionKey;
        let liveAgentAffinity = sessionStorage?.liveAgentAffinity;
        let isHandover = sessionStorage && sessionStorage.isHandover;

        if (isHandover) {
                try {

                    await httpRequest({
                        uri:  `${LIVE_AGENT_URL}Chasitor/ChatMessage`,
                        method: "POST",
                        headers: {
                            "X-LIVEAGENT-SESSION-KEY": liveAgentSessionKey,
                            "X-LIVEAGENT-AFFINITY": liveAgentAffinity,
                            "X-LIVEAGENT-API-VERSION": "34",
                        body: {
                            text: payload.text
                        json: true
                } catch (error) {
                    return null;
        } else {
            return {
                userId: payload.userId,
                sessionId: payload.sessionId,
                text: payload.text,
    handleOutput: async ({ processedOutput, output, endpoint, userId, sessionId }) => {
        let sessionStorage = await getSessionStorage(userId, sessionId);

        if (sessionStorage) {
            if (processedOutput?.data?.liveAgentSessionKey ) {
                sessionStorage.liveAgentSessionKey =;

            if (processedOutput?.data?.liveAgentAffinity) {
                sessionStorage.liveAgentAffinity =;

            if (processedOutput?.data?.isHandover) {
                sessionStorage.isHandover = true;
        return processedOutput;

With this Transformer function, all user messages are redirected to Salesforce during the time of the handover. However, the Transformer needs to get notified that there is a handover at the moment. For this, the Flow needs to send a so-called DATA_ONLY message to the Transformer function and provide the necessary information.

The SAY Node configuration looks similar to this:



    "liveAgentSessionKey": "{{context.liveChat.session.key}}",
    "liveAgentAffinity": "{{context.liveChat.session.affinityToken}}",
    "isHandover": true

As soon as a new live chat session was started successfully, the Session Key and Affinity Token are provided. Please make sure, that the Start Live Chat Flow Node stores the information to the Context as the data above uses this Context object. Salesforce needs this information in order to identify the current live chat session and route the chat messages to the right Salesforce chat.

Perfect! With this setup, the messages are now sent to the Salesforce service agent.

Agent Messages Function

At the moment, the Salesforce Service Cloud requires a separate messaging service that retrieves new Salesforce service agent messages and forwards them to the Cognigy.AI virtual agent. This connection can be established by using Cognigy Functions:

Salesforce Function

This function is used within the Salesforce Service Cloud integration and should be used together with the related Salesforce Extension.

Within a Flow, the Trigger Function Node can be used.

Inside the Parameters JSON field, additional information can be provided:

    "liveAgentUrl": "",
    "headers": {
        "X-LIVEAGENT-SESSION-KEY": "{{context.liveChat.session.key}}",
        "X-LIVEAGENT-AFFINITY": "{{context.liveChat.session.affinityToken}}",

As soon as the function instance is running, three different events will be injected to the chat conversation (Flow):

  1. ChatEnded
  2. ChatEstablished
  3. ChatMessage

They can be used, e.g. inside of a Lookup Node, by using CognigyScript: {{}}. In the case of the ChatMessage, one can simply use a Say Node in order to output the Agent's text message to the user:

Text: {{}}



Article is closed for comments.

Was this article helpful?
0 out of 0 found this helpful