Introduction

This site begins to set-out how to add SendBird SDK into Salesforce in order to allow real time communications between Salesforce’s agent interface and with a client side application. If you don’t have a Salesforce account check out signing up for a developer org here.

Integration Map

A map of how SendBird can integrate with Salesforce.

Agent chat interface

In this document we provide insight on how to add an agent chat window into a Salesforce Case. The agent chat window is housed in Salesforce and is connected to Salesforce. Also, it can communicate to SendBird in real time to provide a live chatting experience.

Customer creates a new Salesforce case and SendBird group channel

We guide you through a possible flow for creating a new Salesforce Case and SendBird group channel with the use of a client application and a server to handle API requests to Salesforce, and Platform API requests to SendBird.

Step 1: Create a Salesforce Case + 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 web-server.

• From the user’s device call to the web-server and create a new Salesforce Case.
• In the Case creation callback use the returned Case id and call Sendbird to create a new group channel (invite the customer + channel url = Case id).
• The web-server returns a Sendbird Channel to the customer to chat in.
• Below is an example Node web-server (gist).
• When the server is set up call the end point /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 end point /createticket from Postman and check in Salesforce and in your Sendbird Dashboard if the server is creating both Salesforce Cases, and Sendbird channels with a user invited.

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 web-server

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

• The user completes a form then requests to the ticket creation end point which returns a channel url.

Step 2: Add Sendbird UIKit to Salesforce as a Utilities Bar Widget

This section describes the implementation of a Salesforce Lightning Container containing Sendbird’s JavaScript SDK 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” displayed within Salesforce’s utilities bar at the bottom.

Lightning Container:

The iframed HTML and JavaScript 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

The aim of this step is to upload a barebones Lightning Container to check everything works. This same resource is used later to upload the UIKit code.

1. create a simple index.html file.
2. rchive the index.html into one .zip file (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.
• The saved resource name is used by Salesforce, not the name of the .zip file.
• 100% of the code and assets you use in a Lightning Component will need to be all 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 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 has 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 codesandbox click 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: As for writing (March 8th 2021) there is a bug in Parcel Bundler version 1.12.4 before downloading from codesandbox check Parcel Bundler version is 1.12.3

2:7 Grant permissions for 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 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. Upload .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 should be invited to the Case’s corresponding Sendbird channel. A Salesforce’s Trigger listens for the Case Owner ship 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.F
• rom 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 is a different agent 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 changes to not 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 assignment via Salesforce Omni Channel (Recommended)

Salesforce’s Omni channel 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 within the Omni Channel interface.
• When the agent clicks accept or decline the AgentWork Trigger hears the event.
• If the Agent accepted the Case Call to the Salesforce Callout to join the agent to 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 Call outs 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 Sendbird’s Platform API endpoints.

• The Salesforce Callout Class contains two methods which are called when a 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