Get Started with the Service Connector API

The Connector API is the interface between your Contact Center as a Service (CCaaS) or telephony system and your Salesforce org. This API allows you to pass information to Salesforce and receive events back from Salesforce.

The Connector API is for partners who are implementing Bring Your Own Channel for CCaaS or Salesforce Voice with Partner Telephony.

Important

The Basics

To use the Connector API, you must call initializeConnector() (imported from Github) as the first step during the window load process. This function is part of the Base Connector API and ensures that Salesforce can reliably establish two-way communication with the connector without any timing issues.

The initializeConnector() function takes your Connector API interface implementation as a parameter. Salesforce holds onto the connector implementation object during the entire session and this object must implement the required Connector API Methods. If the connector requires loading any resources, we recommend that you do this outside of the connector object, so that they can be loaded asynchronously without delaying the call to initializeConnector(). After you call initializeConnector(), Salesforce calls the init() method on the Connector API interface with call center configuration information. This method returns a promise and can asynchronously load any resources before resolving the promise.

1<!-- Sample connector HTML -->
2<html>
3  <body>
4    <div id="iframe" style="display: none;"></div>
5  </body>
6  <script type="module" src="connectordemo.js"></script>
7</html>

1import { initializeConnector } from "scv-connector-base";
2import { Sdk } from "./vendor-sdk";
3
4const connector = new PartnerConnectorInterfaceImplementation();
5
6// Calling the Connector API Base
7window.addEventListener("load", () => {
8  /**
9   * initializeConnector should be called as early as possible
10   * to allow Salesforce to reliably establish communication
11   * with the connector
12   */
13
14  initializeConnector(connector);
15});
16
17// Connector API interface implementation
18export class PartnerConnectorInterfaceImplementation {
19  constructor(state) {
20    this.sdk = new Sdk(state);
21  }
22
23  /**
24   * Called by Salesforce to initialize the connector
25   * @param {object} callCenterConfig - SFDC Contact Center Settings
26   */
27  init(callCenterConfig) {
28    return new Promise((resolve, reject) => {
29      this.sdk.performSSO(callCenterConfig).then((success) => {
30        if (success) resolve(new InitResult({}));
31        else reject("Failed to perform SSO");
32      });
33    });
34  }
35}

Best Practices

Returning JavaScript promises in the connector greatly reduces the need to produce events or errors. Instead, the connector simply returns a resolved or rejected promise. A Connector API interface implementation must return a promise that resolves to a value of a specific type.

Here are some sample promises along with type checking.

1// Base connector
2try {
3    const result = await vendorConnector.setAgentStatus(agentStatus);
4
5    // Validate result is of type GenericResult else throw error
6    dispatchEvent(constants.EVENT_TYPE.SET_AGENT_STATUS_RESULT, { success });
7} catch (e) {
8    dispatchError(constants.ERROR_TYPE.CAN_NOT_SET_AGENT_STATUS, e);
9}
10
11// Connector
12setAgentStatus(agentStatus) {
13   return this.sdk.setAgentStatus(agentStatus).then((success) => {
14        return new GenericResult({success});
15   });
16}
17
18// Vendor
19setAgentStaus(agentStatus) {
20    return new Promise((resolve, reject) => {
21        // Perform backend operations
22        if (success) {
23            resolve();
24        } else {
25            reject();
26        }
27    });
28}

For telephony systems, if you’re using callbacks, you can convert them to promises as shown here:

1// Callback
2function setAgentStatus(agentStatus) {
3  getAgent().setAgentStatus(agentStatus, {
4    success: (success) => {
5      getTelephonyEventEmitter().emit(Constants.EVENT_TYPE.SET_AGENT_STATUS_RESULT, { success });
6    },
7    failure: (response) => {
8      getTelephonyEventEmitter().emit(Constants.EVENT_TYPE.SET_AGENT_STATUS_RESULT, {
9        success: false,
10      });
11    },
12  });
13}
14
15// Promise
16function setAgentStatus(agentStatus) {
17  return new Promise((resolve, reject) => {
18    getAgent().setAgentStatus(agentStatus, {
19      success: (success) => {
20        resolve({ success });
21      },
22      failure: (response) => {
23        reject();
24      },
25    });
26  });
27}

See Also