Skip to main contentIBM watsonx Assistant web chat

Salesforce

Integrating with Salesforce

Overview

web chat comes with support for communicating with a human agent by using the Salesforce Chat APIs. Refer to the watsonx Assistant Integrating with Salesforce documentation for enabling the integration with web chat.

This documentation focuses on the web chat APIs to provide advanced customizations of the integration.

Providing pre-chat details

web chat supports providing extra details to include in the Salesforce when a chat starts. Specifically, web chat supports setting values for the prechatDetails and prechatEntities properties as part of the ChasitorInit call.

Use the agent:pre:startChat event to assign values. Assign the event.preStartChatPayload.preChat.details or event.preStartChatPayload.preChat.entities properties to the array of objects that you want to send to Salesforce. Refer to the following example.

Example
instance.on({
  type: 'agent:pre:startChat',
  handler: event => {
    event.preStartChatPayload = {
      preChat: {
        details: [
          {
            label: 'name',
            value: 'Customer Name',
            transcriptFields: ['name__c'],
            displayToAgent: true,
          },
        ],
        entities: [
          {
            entityName: 'LiveChatTranscript',
            showOnCreate: true,
            linkToEntityName: 'Case',
            linkToEntityField: 'CaseId',
            saveToTranscript: 'CaseId',
            entityFieldsMaps: [
              {
                fieldName: 'name__c',
                label: 'name',
              },
            ],
          },
        ],
      },
    };
  },
});

Messages from watsonx Assistant can also provide this information by setting the values in the context under integrations.salesforce.pre_chat.

Note: In the agent:pre:startChat event, the property's name is preChat, but in context, the property's name is pre_chat. Refer to the following example.

Example
{
  "output": {
    "generic": [
      {
        "response_type": "connect_to_agent",
        "transfer_info": {
          "target": {}
        },
        "agent_available": {
          "message": "Yes! We're ready to help. Just ask."
        },
        "agent_unavailable": {
          "message": "Sorry! We're not available."
        },
        "message_to_human_agent": "Help this super-customer!"
      }
    ]
  },
  "context": {
    "integrations": {
      "salesforce": {
        "pre_chat": {
          "details": [
            {
              "label": "name",
              "value": "Customer Name",
              "transcriptFields": ["name__c"],
              "displayToAgent": true
            }
          ],
          "entities": [
            {
              "entityName": "LiveChatTranscript",
              "showOnCreate": "",
              "linkToEntityName": "Case",
              "linkToEntityField": "CaseId",
              "saveToTranscript": "CaseId",
              "entityFieldsMaps": [
                {
                  "fieldName": "name__c",
                  "label": "name"
                }
              ]
            }
          ]
        }
      }
    }
  }
}

Routing information

By default, web chat uses the routing information from the button and deployment code that web chat provides in the live agent settings. Messages that are returned from watsonx Assistant can override the information to route a specific agent request to a different agent or org.

Use the JSON editor on a message in watsonx Assistant to set the transfer_info.target.salesforce.additional_routing_info property with the alternative routing information for that message. The additional_routing_info property is an array of RoutingInfo objects. Web chat connects the user to an agent by using the first information in the array. If the connection fails because no agents are available, all agents decline, or agents go offline, web chat continues to the next routing information in the array.

Each RoutingInfo object contains the following properties. All of these properties are optional. If the value for any property is not included, web chat falls back to the appropriate value from the web chat settings. Refer to the following table and example.

Property Type Description
button_id String The button ID to route to. If this value is not provided, web chat looks for a routing override in the message that can be set in the settings for the action or dialog node.
button_overrides Array (of Strings) The value for buttonOverrides to pass to Salesforce. See the Salesforce ChasitorInit docs for more information.
org_id String The ID of the org to connect to.
deployment_id String The ID of the deployment to connect to.
deployment_url String The hostname of the Salesforce server to connect to. Example: d.la4-c2-ia2.salesforceliveagent.com.
Example
{
  "output": {
    "generic": [
      {
        "response_type": "connect_to_agent",
        "transfer_info": {
          "target": {
            "salesforce": {
              "button_id": "your default button id",
              "additional_routing_info": [
                {
                  "org_id": "an org id",
                  "button_id": "a button id",
                  "button_overrides": [
                    "an additional button id"
                  ],
                  "deployment_id": "a deployment id",
                  "deployment_url": "a deployment hostname"
                }
              ]
            }
          }
        },
        "agent_available": {
          "message": "Yes! We're ready to help. Just ask."
        },
        "agent_unavailable": {
          "message": "Sorry! We're not available."
        },
        "message_to_human_agent": "Help this super-customer!"
      }
    ]
  }
}