How to integrate Sendbird Chat with Salesforce

Introduction

This tutorial shows how to integrate the Sendbird SDK into Salesforce and enable real-time communication between a Salesforce Agent interface and a client application. If you don’t have a Salesforce account, sign-up for a developer org here.

Integration Map

Below is a map to integrate Sendbird into Salesforce.

Agent chat interface

This document provides insights into adding an Agent chat window into a Salesforce case. The Agent chat window is housed in Salesforce and connected to Salesforce. It can communicate with Sendbird in real-time, enabling a live chat experience.

The customer creates a new Salesforce case and a Sendbird Group Channel

Let us guide you through a possible flow to create a new Salesforce case and a Sendbird Group Channel. We will use a client application, a server to handle API requests to Salesforce, and the Platform API for requests to Sendbird.

Step 1. Create a Salesforce Case and the corresponding Sendbird Group Channel

A customer accesses a client-side application and creates a Salesforce case with a corresponding Sendbird Group Channel (a ticket) using a webserver.

• The user’s device calls the web server and creates a new Salesforce Case.
• The case creation callback returns the Case ID and calls the Sendbird platform to create a new group channel (customer invite + channel URL = Case ID).
• The web server returns a Sendbird Channel to the customer to chat in.
• Below is an example Node webserver.

• When the server is set up, call the endpoint /createticket.
  • Check in Salesforce that a case is created.
  • Check in the Sendbird dashboard for the channel and with an invited user.

When set up, call the endpoint /createticket from Postman and check in Salesforce and in your Sendbird dashboard that the server is creating both a Salesforce Case and a Sendbird Channel with a user.

1.1. Receive and process a create ticket request from the user’s device.

1.2. Fetch an access token from Salesforce (SF_TOKEN explained).

1.3. Create a Salesforce Case.

1.4. Create a channel in Sendbird using the Salesforce Case ID as the channel URL. Also, invite the user using their Sendbird user_id

1.5. Create a client-side application to call to the above webserver

There is a basic client-side application here, that uses the Sendbird UIKit message view.

• The user completes a form and requests the ticket creation to the endpoint, returning a channel URL.

Step 2. Add the Sendbird UIKit to Salesforce as a Utilities Bar widget

This section describes the implementation of a Salesforce Lightning Container containing the Sendbird JavaScript UIKit, to create a Utilities Bar widget. For a high-level overview of a Salesforce Lightning Component, try this blog post and this guide for Salesforce Lightning Containers. Here is an example video.

Glossary:

Utilities Bar Widget:

A Salesforce “Lightning Component” is displayed in the Salesforce’s utilities bar at the bottom.

Lightning Container:

The iframe HTML and JavaScript code are loaded as a static resource into Salesforce and compiled as a view within the Utilities Bar Widget.

2.1. Create an empty Utilities Bar Widget house a Lightning Container

1. In Salesforce Developer Console
2. File → New → Lightning Component.
3. Name = “sendbird_utilities_bar”.
4. Ignore the Component Configurations
5. Click → “submit”.

2.2. Add Utilities Bar Widget code

Set aura:component as a utility bar and provide an aura:id

sendbird_utilities_bar.cmp

2.3. Upload a barebones Lightning Container

This step aims at uploading a barebones Lightning Container to check everything works. We will use the same resource, later, to upload the UIKit code.

1. Create a simple index.html file.

2. Archive the index.html into one .zip file (the name is not important).

3. In Salesforce’s static resources create a new resource called “sendbird_bar”.

4. Upload the .zip file and set “Cache Control” to “Public”

5. Click “Save”

Notes:

• Index.html should always be at the root level of the .zip file
• Be sure to click “save” after uploading your file.
• Salesforce saves the resource name, not the name of the .zip file.
• 100% of the code and assets you use in a Lightning Component will need to be included in the .zip file. Any external code dependencies will not work even if they are whitelisted in the CSP trusted sites list.

2.4. Reference the static resource “sendbird_bar” in the Utilities Bar widget

1. Add a lightning:container tag to the Utilities Bar widget. The aura:id should be “SendBird_Bar”.
2. Reference the static resource.”!$Resource.sendbird_bar + ‘/index.html’}” . Note that sendbird_bar is the saved “static resource”, not the name of the uploaded .zip file.

sendbird_utilities_bar.cmp

2.5. Add the Utilities Bar Widget to display in Salesforce

In Salesforce click “Setup” and search for “App Manager” to set where the Utilities Bar widget will appear. Here “Service Console” is used to show the Utilities Bar Widget

Click “▾” and “Edit” in the App called Service Console

1. In App Setting, click “Utility Items (Desktop Only)”
2. Click “Add Utility Item”
3. Under “Custom”, select the “sendbird_utilities_bar”
4. Set the width 900 height 500
5. Set the icon to “chat”
6. IMPORTANT “Start automatically” should be checked
7. Click → “Save”
8. Navigate to the service you set the Utilities Bar widget to appear in (Services Console). There should be a clickable Utilities Bar widget. These instructions assume that the users logging into Salesforce have the needed permissions to see the widget.

2.6. Download a sample UIKit for the Lightning Container

There is an annotated sample Sendbird UIKit Lightning Container here.

1. In the code sandbox, click the file “Export to zip”.
2. Open the files in your favorite JS code editor and run npm install (root directory).
3. Run npm start in the root directory to open and the sample in a browser. It is possible to send and receive messages and make modifications before building a production build for Salesforce.

Note: (March 8th, 2021), there is a bug in Parcel Bundler version 1.12.4. Before downloading from the code sandbox, check the Parcel Bundler version is 1.12.3

2.7. Grant permissions to Sendbird to operate within Salesforce

Update the Salesforce CSP files to include the URLs below (choose your own names). Also, after adding the UIKit Lightning Container (seen later), check the Salesforce browser developer console for connection errors.

• Salesforce → Setup → Search → “CSP Trusted sites”
• Add “New Trusted Sites” (allow all CSP Directives):
  • https://sendbird.com
  • https://{your region code or the letters “api”}.sendbird.com
    • e.g., https://eu-1.sendbird.com or https://api.sendbird.com
• https://{your region code or the letters “api”}-p.sendbird.com
  • e.g., https://eu-1-p.sendbird.com or https://api-p.sendbird.com
• wss://sendbird.com
• wss://ws.sendbird.com
• https://api-{YOUR_APP_ID}.sendbird.com
• wss://ws-{YOUR_APP_ID}.sendbird.com

• Salesforce → Setup → Search → “CORS”
  • Add “New” Allowed Origins List, and add https://*.sendbird.com

2.8. Prepare Utilities Bar Widget to initialize the UIKit Lightning Container

The Lightning Container needs to communicate readiness to the Utilities Bar Widget.

• In the Lightning container, send an LLC message (NPM LLC library) to the Utilities Bar Widget when the UIKit Lightning Container has loaded.
• Loading is asynchronous so include LLC message retry logic.
• The Utilities Bar Widget should respond with the Salesforce Agent’s id.
• The Lightning Container hears the response and render’s UIKit.

Send a message to the Utilities Bar Widget and Include retry logic. Clear the retry interval in messageHandler when the Utilities Bar Widget returns a Salesforce Agent’s user_id.

lightningContainer.Index.js

The Utilities Bar Widget onMessage handler calls handleMessage

sendbird_utilities_bar.cmp

TheUtilities Bar Widget’s handleMessage() method listens for all messages from the Lightning Container. Therefore, conditionally process the “READY” message.

sendbird_utilities_barController.js

helper.initUIKit() in the Utilities Bar Widget sends a message to the Lightning Container.

“Sendbird_Bar” = lightning:container’s aura:id

sendbird_utilities_barHelper.js

The Lightning Container receives the message from the Utilities Bar Widget in the LLC.addMessageHandler()

Stop the retry logic and render the UIKit.

lightningContainer.Index.js

2.9 Load the Lightning Container to Salesforce

1. npm run build

2. The build will output to the dist folder.

3. Compress index.html , .js and .css together into one .zip file.

4. Unload .zip to the static resource created in the barebones example above.

5. Open the Utilities Bar Widget. The Sendbird UIKit should connect to Sendbird using the Salesforce Agent’s ID, assuming you created the Salesforce Agent as a user in Sendbird.

2.10 Optional but important extras

• Signal a new incoming Sendbird message in Salesforce – link.
• Open a Case from Utilities Bar Widget based on a Sendbird Channel – link.

Step 3. Listen for Salesforce Case assignment and set Sendbird group Channel members

Once a case has been created, a Salesforce Agent will take ownership of the Case and be invited to the corresponding Sendbird Channel. A Salesforce’s Trigger listens for the Case Ownership change and calls a Salesforce Apex Callout.

3.1. Listen for manual Case assignment.

• When the case owner changes, an Apex Trigger hears the ownership change.
• From the Apex Case Change Trigger call the Apex Callout.
• Remove the old Agent from the Sendbird Channel.
• Add the new Agent to the Sendbird Channel.

• The case owner changes to be an Agent.
  • If the case owner ID is prefixed with `005` (005 always prefixes agent’s IDs)
  • Use the Salesforce Callout to invite the Agent to the Sendbird Channel.

• If the new Case Agent is different than the current logged-in Agent:
  • Use the Salesforce Callout to remove the previous Case owner Agent from the Sendbird Group Channel.
  • Use a Salesforce Callout to invite the Agent to the Sendbird Channel.

• If the case owner decides not to be an agent, such as moving to a queue.

• Use the Salesforce Callout to remove the previous Case owner agent from the Sendbird Group Channel. If the Case owner ID is prefixed with `005` (005 always prefixes Agent’s IDs)
• Salesforce Developer console –> New –> Apex Trigger –> Name = “AssignAgent” & sObject = “Case”

AssignAgent.apxt

3.2. Listen for automatic case assignments via the Salesforce Omni Channel (Recommended)

Salesforce’s omnichannel can indicate to an agent when they have a new Case that they should process:

• Omni Channel detects a Case assignment, then Salesforce automatically creates an AgentWork object.
• The AgentWork object gets assigned to an Agent
• The Agent chooses to accept or decline in the Omni Channel interface.
• When the Agent clicks accept or decline, the AgentWork Trigger hears the event.
• If the Agent accepted the Case Call of the Salesforce Callout to join the Sendbird Group Channel associated with the Case.
• For setting up Omni Channel routing. There is a step-by-step guide here.

Salesforce Developer console –> New –> Apex Trigger –> Name = “AgentOmniChannel” & sObject = “AgentWork”

AgentOmniChanne..apxt

3.3. Salesforce Callouts to assign Sendbird Channel membership

The Salesforce Callout below acts as a type of backend web server built into Salesforce. Because Callouts operate in Salesforce’s backend, it is safe to call to the Sendbird Platform API endpoints.

• The Salesforce Callout Class contains two methods which are called when the Salesforce Triggers mentioned previously run.
  • Invite a user to a Sendbird Group Channel
  • Remove a user from a Sendbird Group Channel.

Salesforce Developer console –> New –> Apex Class –> Name = “SendbirdCallOuts”

SendbirdCallOuts.apxc

Conclusion

Congratulations! You’ve just added Sendbird Chat to your web or mobile application so that your users can engage in real-time communication with a Salesforce Agent. They will be delighted with this new and engaging support experience! Next, check out our voice and video Sendbird Calls product and bring your support to the next level with voice and video. In the meantime, happy support building!