This playground page explains how to use the Communication Panel Control (CPC) helper library to embed Sinch Contact Pro Communication Panel into your web application.

This page also provides examples of how your application can interact with Communication Panel, by listening to events and sending commands.

The purpose of the CPC helper library is to help implement client-side integrations between Sinch Contact Pro and your HTML-based host application. The goal is to reduce time and effort needed to fully integrate Communication Panel.

CPC provides an easy-to-consume, functional, async API, including all capabilities of the underlying standard Communication Panel Extension Interface (CPExtInterface). Using CPC helps reduce development time compared to using CPExtInterface directly. In some very detailed integration cases it may still make sense to use CPExtInterface directly.

Some information about CPC for developers:

• CPC.js is an open-source (MIT licensed) project maintained by the Sinch Contact Pro developer team.
• We welcome all feedback, improvement ideas, and all comments in GitHub.
• Code style and documentation aim for easy auditing. Code is not minified/uglified to allow easy auditing at any time.
• When needed, our customers and partners can freely copy the source code, edit it, and host it on their own server.
• CPC runs in context of the host application, and is essentially a third party script. As with any open-source code, organizations should audit code before including the script in their application.
• CPC does not use transpilers or polyfills - ES6/ES2015 capable browser is required.
• CPC.js is plain JavaScript, standalone with zero dependencies.
• CPC API documentation

Before continuing with CPC, please ensure you have:

• A working Sinch Contact Pro system. CPC works with both cloud and on-premise versions of Contact Pro.
• A user account that:
  • Has the rights and settings needed for using Communication Panel as an agent.
  • The user settings template assigned for the user has Salesforce integration enabled.
    • CPC takes advantage of some parts of Communication Panel's native integration with Salesforce.
    • This requirement is likely to change in the future, as we continue to evolve Communication Panel.
• Ensured Contact Pro ECF Web Server CORS settings allow embedding Communication Panel:
  • If you are using Contact Pro cloud, please create a service request and include the domain of your host application.
  • If you are using an on-premise installation, check CORS settings using the Infrastructure Administrator (IA) tool.
• Considered using single sign-on (SSO):
  • We recommend implementing SSO to avoid users needing to log into Communication Panel separately.
  • In Contact Pro cloud, we recommend implementing SAML federation: Setting Up Single Sign-On (SSO)
  • For cases where SAML is not an option, we also support OAuth directly via CPC.authenticate_token.
  • This requires adding your OAuth Issuer to the list of trusted OAuth Accepted Issuers: ECF Web Server Variables.
    If you are a Sinch Contact Pro cloud customer, please contact Sinch support.
  • The CPC library can be extended to help with SSO-related procedures.
  • To enable SSO, add a client certificate for each Contact Pro user: Defining Client Certificates

The correct way to include CPC.js depends on the host application's architecture. This playground page does it simply like this:

Content Security Policy (CSP) of the host web application's HTTP server might need changes to allow loading of CPC.js.

Once loaded, function window.CPC becomes available. It provides namespacing and encapsulation to prevent any collisions with existing code. In case your application already happens to have window.CPC, it is not overwritten. In such case, use the backup namespace window.CommunicationPanelControl instead.

On this playground page, you can open the browser console and type CPC to see available functions. For full API documentation, see CPC API JSDoc.

CPC requires the host application to provide a container element into which Communication Panel is loaded. The host application is in charge of container placement, dimensions, and visibility.

On this page, on the right you see an example container which has element ID commPanelContainer. You can drag and resize the example container so that it's easy to try out embedded Communication Panel in different heights and widths.

There are a few important design considerations regarding the container element:

• If the container element reloads or closes, possibly ongoing conversations in Communication Panel (such as a phone call) are interrupted or even disconnected.
• In a Single-Page App (SPA), it's best practice to embed Communication Panel at the top level of the application and to keep Communication Panel available throughout the application.
• Communication Panel may exist only once within a browser tab.

Note: Depending on user settings, and when given limited screen space, Communication Panel may responsively switch to a limited My Conversations view and launch a separate Communication Panel instance in a pop-out window. This allows the user to access all functions of Communication Panel via the pop-out window, while the embedded instance still continues to handle integration with the host application.

Let's try embedding Communication Panel into this playground page.

1. Below you'll see some example code. Click on the code to copy it.
2. Paste the code into the browser's console and edit:

   • The base URL of the Sinch Contact Pro Standard Demo system

     Replace the tenantBaseUrl with the corresponding base URL of your own system before running the script. You can also request access to the Standard Demo system.

   • The authentication property, which illustrates the use of basic authentication

     When using basic authentication, be sure to keep your and your users' credentials safe. In production use, SSO is always recommended instead of basic authentication.

3. Run the code in the console. See the example container on the right to preview how Communication Panel will look.

Full documentation: CPC.load

const myEventHandler = (event) => {
    console.log('Event from Communication Panel: ' + JSON.stringify(event, null, '\t'));
    // ...Add code here...
};

const config = {
    // Base URL of Sinch Contact Pro Standard Demo system - Replace URL according to your Contact Pro cloud tenant or on-premise installation.
    tenantBaseUrl: "https://login-eu-c1.cc.sinch.com/standarddemo",

    // Provide authentication object for automatic login. Note: Protect user credentials - Prefer SSO over basic authentication.
    authentication: { basic: {userName:'john.doe', password:'sMFKDSkmwe4mfmklsdmkf'}},

    // Provide reference to the parent/container element, or element id. On this playground page it's "commPanelContainer".
    parentElement: "commPanelContainer",

    // Provide an event handler function, if you want to recieve events from Communication Panel.
    eventHandler: myEventHandler,

    // Set to true for troubleshooting only.
    enableDebugLog: false,

    // Configuration specific to "My Conversation" and pop-out window features. These are the default values.
    denyPopout: false,
    minWidth: 500,
    minHeight: 400,

    // Set to true to enable CPC to forward 'channel_status' updates, e.g. when call muted or put on hold.
    enableChannelStatusUpdates: false,
};

// Embed Communication Panel:
const loaded = await CPC.load(config);
if (!loaded) {
    console.warn('Communication Panel could not be embedded');
}

The authentication object accepts the following values.
For basic authentication:

{
    basic: {
        userName: 'my.username',
        password: 'my-very-strong-password'
    }
}

For OAuth (See section 3 for more information):

{
    oAuth: {
        token: 'my-unique-oAuth-token'
    }
}

Note: If your host application requires you to work with Web Components, here's an example of a wrapper web component and a separate test page for trying it out.

Here are just a few examples of available commands.

See the full list of commands in the CPC API documentation.

// Start a phone call:
const call = await CPC.callOut('+15551234567');

// Start an SMS chat:
const sms = await CPC.sendSMS({
    to: "+1-555-123456",
    direct: false
    });

// Send email:
const email = await CPC.sendEmail({
    to: ["john.doe@example.com"],
    subject: "This is a prefilled email subject",
    content: "Some prefilled email content here",
    direct: false
    });

In step 5, we used a very simple event handler which merely logged each received event. In most cases, your application will want to react to certain types of events, and maybe ignore some others.

const myEventHandler = (event) => {
    switch (event.type) {
        case "status":
            // Agent switched Communication Panel to Ready state:
            if (event.payload.attribute === "work_status" && event.payload.value === "ready") {
                //Do something...
            }
            break;
        case "state":
            // Agent accepted an incoming contact from Queue:
            if (event.payload.attribute === "status" && event.payload.value === "accepted") {
                //Do something...
            }
            break; 
    }
};

Above we see just a few examples of how to react to certain events. To learn more, see the full JSON schema in the Communication Panel Third-Party Extension Messaging API documentation.

CPC relies on the Communication Panel Extension Interface (CPExtInterface) to provide most of the needed capabilities for client-side integrations.

For more advanced use cases, CPC additionally provides a generic helper CPC.RI.request for accessing Contact Pro's restful interfaces (RI). For more information, see our API documentation.

When accessing restful interfaces with CPC, an API call is made using the credentials of the currently logged-on user. This means that the user must be authenticated and logged in before RIs can be accessed. Also, available actions and data depends on the user account's rights.

Important: CPC.RI.request should not be used in a resource-exhaustive manner. Also carefully consider if you should use a server-to-server API call instead.

// Example: Get current user's Queues list from the Restful Configuration Interface (RCI)
console.log( await CPC.RI.request('RCI', 'GET', '/queues') );

Note: Some of the functions of window.CPC use window.CPC.RI in the background. For this reason, some UI state-changing functions, such as CPC.setProfile, have a small delay. There may be a 1-3 second delay until the UI reacts, even if CPC has already returned a value.

Examples:

// Set user's presence profile. Expect a small delay until profile changes within Communication Panel:
await CPC.setProfile("Away"); // Provide profile id or exact name.

// Set user's Ready state. Expect a small delay until profile changes within Communication Panel:
await CPC.setReady(true);

To deauthenticate and log out the currently logged-in user, simply run await window.CPC.unload();. Additionally, this command removes the Commmunication Panel iframe but keeps window.CPC. Therefore, it's possible to call CPC.load again to log in another user.

See CPC API documentation.