Integration API Developer Guide

b+s Connects for Salesforce CCE/CCX Edition offers an Integration API to customers to extend the default functionality of the b+s Connects product.

The Integration API allows interaction between the b+s Connects Agent Gadget and Custom Components.

These Custom Components can be placed anywhere in Salesforce (e.g. as Console Components) or also in reserved Custom Toolbar sections inside the b+s Connects Agent Gadget. Please refer to the compatibility matrix below for additional details.

info

Custom Toolbar section inside b+s Connects Agent Gadget only supports Visualforce pages and external web pages.

	LWC / Aura Component	Visualforce Page	Visualforce Page with LMS	Salesforce Console API
Custom Toolbar section	✗	✓	✓	✗
Component in Lightning Page	✓	✗	✓	✗
Utility Item	✓	✗	✓	✓

Custom Components can be Visualforce pages, Lightning Aura components or external web pages. The Integration API is only available in Visualforce pages, Lightning Aura components and Lightning Web components.

There are two types of interactions available, depending on the direction of the data flow:

• Events: Gadget -> Custom Component
• Requests: Custom Component -> Gadget

b+s Connects for Salesforce CCE/CCX Edition also supports using the Salesforce Interaction Logs.

Custom Toolbars

See Custom Toolbars in Configuration for CRM Admins page.

Integration Settings

If your Custom Component needs configuration values, the Integration API offers a way to read a configuration string specific to your Custom Component from the b+s Configuration.

The settings can be edited in the b+s Configuration in the Integrations section. You can only add up to five different Integration Settings.

Integrations Section "Integration Settings"

Identifier

The Integration setting identifier.

Example: Component1

Default: none

Settings

The string containing the settings that is returned when the integration requests its custom settings.

Example: property1=true;property2=1

Default: none

Using Salesforce Console Integration Toolkit (SCIT)

In order to use the Salesforce Console Integration Toolkit functions in a custom toolbar in Salesforce Classic Console, the flag ENABLE_SCIT has to be set. The Flags field can be found in the Additional Settings section in the Global block of the b+s Configuration.

info

This key is only functional in Salesforce Classic Console. It is not supported in Lightning Console.

For further information about the Flags field, please refer to the section Flags

Start Using the Connects Integration API

The b+s Connects for Cisco Contact Center package contains several resources that you need to know if you want to use the Connects Integration API. This chapter will tell you which resources you need, depending on the environment in which your custom component is running.

First there is a JavaScript file named ConnectsIntegrationAPI.min.js which contains the functions and handlers that you need to send requests to and receive events from within the b+s Connects Agent Gadget.

Depending on the environment, there are different ways of loading the Connects Integration API into your custom component and enabling it for usage.

info

If you are going to use your Integration inside of Salesforce Lighting you need to set the "Enable Integration API in Lightning" toggle inside the b+s Configurations "Integrations" section to "Yes".

Integrations Section "Enable Integration API in Lightning" toggle

Load and Set Up the Connects Integration API

Visualforce inside Classic Console

In order to use the Connects Integration API, a Visualforce page in Classic Console needs to…

• … include the integration.js from Salesforce (Not required if the page is only used as a Custom Toolbar in the b+s Connects Agent Gadget)

<apex:includeScript value="/support/console/60.0/integration.js"/>

• … include the ConnectsIntegrationAPI.min.js static resource JavaScript file

<apex:includeScript value="{!URLFOR($Resource.cnx__CnxSfdcResources, 'js/ConnectsIntegrationAPI.min.js')}"/>

Visualforce inside Lightning

In order to use Connects Integration API, a Visualforce page in Salesforce Lightning Experience and Lightning Console needs to…

• … include the ConnectsIntegrationAPI.min.js static resource JavaScript file

<apex:includeScript value="{!URLFOR($Resource.cnx__CnxSfdcResources, 'js/ConnectsIntegrationAPI.min.js')}"/>

• …integrate the Lightning Message Channel and set the Lightning Message Service environment on the Connects Integration API

var messageChannel = "{!$MessageChannel.cnx__ConnectsIntegrationAPI__c}";
ConnectsIntegrationAPI.setLMSEnvironment({
    mode: "Visualforce",
    channel: messageChannel
});

Lightning Aura Component

In order to use the Connects Integration API, a Lightning Aura Component needs to…

• … include the Connects Integration API Component in the component

<cnx:ConnectsIntegrationAPI aura:id="cnxIntegrationAPI"/>

• … have a handler for the waitReady Lightning Aura Component Event in the component

<aura:handler name="waitReady" event="cnx:ConnectsIntegrationAPIEvent" action="{!c.waitReady}"/>

• … obtain the Connects Integration API reference after the waitReady Lightning Aura Component event has been triggered

waitReady: function (component, event, helper) {
    var cnxIntegrationAPI = component.find('cnxIntegrationAPI')
        .get('v.noConflictConnectsIntegrationAPI');
}

Lightning Web Component

In order to import the Connects Integration API library into a Lightning Web Component you will need to manually create a "Service Component" that acts as an intermediary between the Connects Integration API library and your custom solutions. This action is required to be performed only once. The Service Component can be re-used across all your custom solutions.

• …create a new Lightning Web Component, name it "connectsIntegrationApiSvc"
• …Insert the following code in the connectsIntegrationApiSvc.js file:

import CNX_RESOURCE_LINK from '@salesforce/resourceUrl/cnx__CnxSfdcResources';
import { loadScript } from 'lightning/platformResourceLoader';
import { subscribe, publish, APPLICATION_SCOPE, createMessageContext } from 'lightning/messageService';
import cnxmc from '@salesforce/messageChannel/cnx__ConnectsIntegrationAPI__c';

export default function getIntegrationApi(lwc, cb) {
    Promise.all([
        // Load Integration API from static resource
        loadScript(lwc, CNX_RESOURCE_LINK + '/js/ConnectsIntegrationAPI.min.js')
    ])
        .then(() => {
            const messageContext = createMessageContext();
            const iAPIInstance = ConnectsIntegrationAPI.noConflict();
            iAPIInstance.setLMSEnvironment({
                mode: 'LWC',
                publishMethod: function (message) {
                    publish(messageContext, cnxmc, message);
                },
                subscribeMethod: function (handler) {
                    subscribe(messageContext, cnxmc, handler, { scope: APPLICATION_SCOPE });
                }
            });
            // Return the Integration API object when it is ready
            iAPIInstance.waitReady(() => {
                return cb(iAPIInstance);
            });
        })
        .catch(error => {
            cb(null, error);
        });
}

• …Insert the following code in the connectsIntegrationApiSvc.js-meta.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>60.0</apiVersion>
    <description>Connects Integration Api Service</description>
    <masterLabel>Connects Integration Api Service</masterLabel>
    <isExposed>false</isExposed>
</LightningComponentBundle>

caution

Set the "Enable Integration API in Lightning" toggle inside the b+s Configurations "Integrations" section to "Yes".

At this point you are ready to include the Connects Integration API into your custom solutions. Please refer to the "Basic Event and Request Sample Code" section of this documentation for a ready-to-code example (direct link).

Next Steps

After you performed the required steps to add the Connects Integration API reference to your code you can go ahead and set callbacks for the different events or send the requests with the functions that the Connects Integration API provides.

Integration API changes with version 5.1

With b+s Connects for Salesforce version 5.1 the initialization of the Integration API has been redesigned.

Before sending requests or a registration call to events from the Integration API, the waitReady event has to be executed. All other interactions with the Integration API can only happen in the callback of the waitReady event handler. This affects Visualforce, JavaScript and LMS integrations.

Here’s an example using the writeLogDebug function.

ConnectsIntegrationAPI.waitReady(function () {
    ConnectsIntegrationAPI.writeLogDebug('Connects Integration API' +
        'Successfully loaded from Custom Toolbar Visualforce Page.');
});

In order to use the Integration API with b+s Connects for Salesforce version 5.1 or higher all Visualforce pages, Aura Components and other sites that use the Integration API need to wait for the waitReady event before interacting with the Integration API. The best way to do that is by changing all integrations before updating the b+s Connects for Salesforce package.

Integration API Specification

Enumeration Values

Some parameters in requests or events from the CRM Gadget use enumeration values. The definition of these enumeration values can be found here.

GENERAL.TOOLBAR_POSITION

This enumerator represents the available custom toolbar positions.

Possible Values

Value	Description
TOP	The first toolbar position on top of the gadget
BOTTOM	The first toolbar position on the bottom of the gadget
AUTO	Automatically use the current position of the toolbar

CHANNEL.TYPE

This enumerator represents the different kind of channel types.

Possible Values

Value	Description
OVERALL	Represents all channels
VOICE	Represents the voice channel
TICKET	Represents the ticket channel
CHAT	Represents the chat channel

CHANNEL.STATE

This enumerator represents the different states for the channels.

Possible Values

Value	Description
NOT_READY	The agent is not ready to receive incoming calls.
READY	The agent is ready to receive incoming calls.
TALKING	The agent is in an active call *.
ACTIVE	The agent has an active task **.
WORK	The agent is in after-call-wrap-up *.
WORK_READY	The agent is in after-call-wrap-up and will be in state READY afterwards*.
LOGOUT	The channel is logged out.

* Only used for voice channel

** Only used for media channels in External Routing MRI 2.0 deployments.

ONBEFOREDIALCALLTYPE

This enumerator represents the various call types that the onBeforeDial event is triggered for.

Possible Values

Value	Description
OUTBOUND	Normal call such as outbound or Click-to-Dial
CONSULT	Beginning of a consultation call
BLINDTRANSFER	Beginning of a direct transfer

WORKITEM.TYPE

This enumerator represents the different kind of work item types.

Possible Values

Value	Description
VOICE	Represents the voice channel
TICKET	Represents the ticket channel
CHAT	Represents the chat channel

WORKITEM.STATE

This enumerator represents the different states for the work items.

Possible Values

Value	Description
OFFERED	The work item is offered (voice call ringing)
ACTIVE	The work item is active (voice call answered)
WRAPUP	The work item is in Wrap-Up
PAUSED	The work item is paused (voice call on hold)
ENDED	The work item has ended

SUBSCRIPTION.STATE

This enumerator represents the different states for subscriptions.

Possible Values

Value	Description
ENABLED	The subscription was successfully created
DISABLED	The subscription was successfully deleted
UPDATED	Data was updated for a subscription
ADDED	Data was added for a subscription
DELETED	Data was deleted for a subscription
FAILED	The subscription could not be created

REASON.TYPE

This enumerator represents the different states for reason types.

Possible Values

Value	Description
NOTREADY	Reasons for Not ready state
WRAPUP	Reasons for Wrap-Up state
LOGOUT	Reasons for Logout state

Events (Gadget Custom Component)

These events are triggered by the b+s Connects Agent Gadget. You can use the Connects Integration API to register custom code that is executed as a callback when any of these events get triggered.

info

Work items in the events below can be either calls (item.Channel = "VOICE"), tickets (item.Channel = "TICKET"), or chats (item.Channel = "CHAT"). Be aware that these events are sent for any types of work item: incoming and outgoing calls, routed and direct calls, consultation calls, reservation calls, routed tickets, routed chats, etc. Use the fields "item.Channel", "item.Direction", and "item.CallType" to filter the relevant events.

onClientInterfaceConnectionLost(event)

This callback function is called when a connection to a service is lost after a failover or recovery is triggered.

info

This event is currently only triggered for channels that are connected to Finesse.

Event Attributes

eventType (String)
OnClientInterfaceConnectionLost

affectedChannels (Array of Strings)
An array with the channel names with which the client interface lost its connection. Can contain VOICE, TICKET and CHAT.

Sample Code

The following sample code writes the affected channels into a log message.

Visualforce:

ConnectsIntegrationAPI.onClientInterfaceConnectionLost = function (event) {
    ConnectsIntegrationAPI.writeLogDebug("Lost client interface connection for channels " +
        event.affectedChannels);
};

Lightning Aura/Web Component:

cnxIntegrationAPI.onClientInterfaceConnectionLost = function (event) {
    cnxIntegrationAPI.writeLogDebug("Lost client interface connection for channels " +
        event.affectedChannels);
};

onClientInterfaceConnectionEstablished(event)

This callback function is called when a connection to a service is established after a failover or recovery.

info

This event is currently only triggered for channels that are connected to Finesse.

Event Attributes

eventType (String)
OnClientInterfaceConnectionLost

affectedChannels (Array of Strings)
An array with the channel names to which the client interface (re-)established its connection. Can contain VOICE, TICKET and CHAT.

Sample Code

The following sample code writes the affected channels into a log message.

Visualforce:

ConnectsIntegrationAPI.onClientInterfaceConnectionEstablished = function (event) {
    ConnectsIntegrationAPI.writeLogDebug("Established client interface connection for channels " +
        event.affectedChannels);
};

Lightning Aura/Web Component:

cnxIntegrationAPI.onClientInterfaceConnectionEstablished = function (event) {
    cnxIntegrationAPI.writeLogDebug("Established client interface connection for channels " +
        event.affectedChannels);
};

onBeforeDial(event)

This callback function is called when a MakeCall, Consult or DirectTransfer request is about to be sent to Finesse.

For example, you can use this event to prevent dialing numbers that are on a "do not dial" list, to manipulate the dialed number or to automatically put a shared record ID into one of the call variables.

danger

When registering a callback for this event, the default call behavior is disabled and only the callback function is executed. If you want the number to be dialed, you need to call the makeCall function.
If not implemented carefully an infinite loop is created and no call will be made!

tip

We recommend loading the customization which implements the onBeforeDial event as a custom toolbar component so it does not get unloaded by accident.

Event Attributes

eventType (String)
OnBeforeDial

callType (String)
The call's call type. Possible values are inside the ONBEFOREDIALCALLTYPE enumeration.

dialedNumber (String)
The number that is about to be dialed, with formatting and dialing rules already applied.

callVariables (Object)
The object with all call variables that will be sent to Finesse to attach to the item (See section itemVarObject Structure for a detailed description.)

info

This property is only set on an OUTBOUND call type. Keep in mind that the properties of the itemVarObject type are optional, meaning not all fields have to be present in this event parameter.

workItemId (String)
The call's workItemId to be transferred.

info

This property is only set on a BLINDTRANSFER call type.

relatedObject (Object)
The object containing the related Salesforce object's information concerning whether the call was initialized by a Click-to-Dial action.
(See section relatedObject Structure for a detailed description.)

Sample Code

The following sample code writes a log message when a new call appears.

Visualforce:

ConnectsIntegrationAPI.onBeforeDial = function (event) {
    if (event.callType === ConnectsIntegrationAPI.ONBEFOREDIALCALLTYPE.OUTBOUND) {
        ConnectsIntegrationAPI.makeCall(event.dialedNumber, event.callVariables, true);
    } else if (event.callType === ConnectsIntegrationAPI.ONBEFOREDIALCALLTYPE.CONSULT) {
        ConnectsIntegrationAPI.makeCall(event.dialedNumber, {}, true);
    } else if (event.callType === ConnectsIntegrationAPI.ONBEFOREDIALCALLTYPE.BLINDTRANSFER) {
        ConnectsIntegrationAPI.blindTransferCall(event.workItemId, event.dialedNumber, true);
    }
};

Lightning Aura/Web Component:

cnxIntegrationAPI.onBeforeDial = function (event) {
    if (event.callType === cnxIntegrationAPI.ONBEFOREDIALCALLTYPE.OUTBOUND) {
        cnxIntegrationAPI.makeCall(event.dialedNumber, event.callVariables, true);
    } else if (event.callType === cnxIntegrationAPI.ONBEFOREDIALCALLTYPE.CONSULT) {
        cnxIntegrationAPI.makeCall(event.dialedNumber, {}, true);
    } else if (event.callType === cnxIntegrationAPI.ONBEFOREDIALCALLTYPE.BLINDTRANSFER) {
        cnxIntegrationAPI.blindTransferCall(event.workItemId, event.dialedNumber, true);
    }
};

onWorkItemCreate(event)

This callback function is called when a new work item in the b+s Connects Agent Gadget appears and is alerting.

It will also be called if the agent logs in while a call is on the phone.

Event Attributes

eventType (String)
OnWorkItemCreate

item (Object)
The object with all available work item data (See section Workitem Structure for a detailed description.)

Sample Code

The following sample code writes a log message when a new call appears.

Visualforce:

ConnectsIntegrationAPI.onWorkItemCreate = function (event) {
    if (event.item.Channel == "VOICE") {
        ConnectsIntegrationAPI.writeLogDebug("Call from " + event.item.Sender + " to " +
            event.item.Destination + " is ringing.");
    }
};

Lightning Aura/Web Component:

cnxIntegrationAPI.onWorkItemCreate = function (event) {
    if (event.item.Channel == "VOICE") {
        cnxIntegrationAPI.writeLogDebug("Call from " + event.item.Sender + " to " +
            event.item.Destination + " is ringing.");
    }
};

onSearchAndScreenPopResult(event)

This callback function is called when the search and screen pop returned a result.

info

This event will only be fired once in the lifetime of a work item.

Event Attributes

eventType (String)
OnSearchAndScreenPopResult

item (Object)
The object with all available call data (See section Workitem Structure for a detailed description.)

Sample Code

The following sample code logs the content of the search and screen pop result. If nothing was found by the search parameters the return value of the CRM search is an empty object.

Visualforce:

ConnectsIntegrationAPI.onSearchAndScreenPopResult = function (event) {
    if (event.item.CrmData.SearchResult && event.item.CrmData.SearchResult.success) {
        ConnectsIntegrationAPI.writeLogDebug("Search and screen pop found " +
            JSON.stringify(event.item.CrmData.SearchResult.returnValue));
    } else {
        ConnectsIntegrationAPI.writeLogDebug("Search and screen pop did not find any records.");
    }
};

Lightning Aura/Web Component:

cnxIntegrationAPI.onSearchAndScreenPopResult = function (event) {
    if (event.item.CrmData.SearchResult && event.item.CrmData.SearchResult.success) {
        cnxIntegrationAPI.writeLogDebug("Search and screen pop found " +
            JSON.stringify(event.item.CrmData.SearchResult.returnValue));
    } else {
        cnxIntegrationAPI.writeLogDebug("Search and screen pop did not find any records.");
    }
};

onWorkItemOODataReceived(event)

This callback function is called as soon as the Outbound Option Campaign data is presented for the first time on the call.

The campaign data BACampaign, BAStatus, BAResponse, BAAccountNumber, BADialedListID, BATimeZone and BABuddyName is stored in the named variables on the item object.

Event Attributes

eventType (String)
OnWorkItemOODataReceived

item (Object)
The object with all available work item data (See section Workitem Structure for a detailed description.)

Sample Code

The following sample code writes a log message when a new call appears.

Visualforce:

ConnectsIntegrationAPI.onWorkItemOODataReceived = function (event) {
    if (event.item.Channel == "VOICE") {
        ConnectsIntegrationAPI.writeLogDebug("Outbound Option data received for " +
            event.item.Id + ".");
    }
};

Lightning Aura/Web Component:

cnxIntegrationAPI.onWorkItemOODataReceived = function (event) {
    if (event.item.Channel == "VOICE") {
        cnxIntegrationAPI.writeLogDebug("Outbound Option data received for " +
            event.item.Id + ".");
    }
};

onWorkItemConnect(event)

This callback function is called when a work item is accepted.

It will also be called if the agent logs in while an already established call is on the phone.

Event Attributes

eventType (String)
OnWorkItemConnect

item (Object)
The object with all available call data (See section Workitem Structure for a detailed description.)

Sample Code

The following sample code writes a log message when a call is answered.

Visualforce:

ConnectsIntegrationAPI.onWorkItemConnect = function (event) {
    if (event.item.Channel == "VOICE") {
        ConnectsIntegrationAPI.writeLogDebug("Call from " + event.item.Sender + " to " +
            event.item.Destination + " is connected.");
    }
};

Lightning Aura/Web Component:

cnxIntegrationAPI.onWorkItemConnect = function (event) {
    if (event.item.Channel == "VOICE") {
        cnxIntegrationAPI.writeLogDebug("Call from " + event.item.Sender + " to " +
            event.item.Destination + " is connected.");
    }
};

onWorkItemPause(event)

This callback function is called when a work item is paused (set on hold for calls). It will also be called if the agent logs in while a call is held on the phone.

Event Attributes

eventType (String)
OnWorkItemPause

item (Object)
The object with all available call data (See section Workitem Structure for a detailed description.)

Sample Code

The following sample code writes a log message when a call is placed on hold.

Visualforce:

ConnectsIntegrationAPI.onWorkItemPause = function (event) {
    if (event.item.Channel == "VOICE") {
        ConnectsIntegrationAPI.writeLogDebug("Call from " + event.item.Sender + " to " +
            event.item.Destination + " is on hold.");
    }
};

Lightning Aura/Web Component:

cnxIntegrationAPI.onWorkItemPause = function (event) {
    if (event.item.Channel == "VOICE") {
        cnxIntegrationAPI.writeLogDebug("Call from " + event.item.Sender + " to " +
            event.item.Destination + " is on hold.");
    }
};

onWorkItemResume(event)

This callback function is called when a work item is resumed (taken off-hold or retrieved for calls).

Event Attributes

eventType (String)
OnWorkItemResume

item (Object)
The object with all available call data (See section Workitem Structure for a detailed description.)

Sample Code

The following sample code writes a log message when a call is retrieved.

Visualforce:

ConnectsIntegrationAPI.onWorkItemResume = function (event) {
    if (event.item.Channel == "VOICE") {
        ConnectsIntegrationAPI.writeLogDebug("Call from " + event.item.Sender + " to " +
            event.item.Destination + " is retrieved.");
    }
};

Lightning Aura/Web Component:

cnxIntegrationAPI.onWorkItemResume = function (event) {
    if (event.item.Channel == "VOICE") {
        cnxIntegrationAPI.writeLogDebug("Call from " + event.item.Sender + " to " +
            event.item.Destination + " is retrieved.");
    }
};

onWorkItemWrapup(event)

This callback function is called when a work item in the b+s Connects Agent Gadget changes the state to Wrap-Up. It will also be called if the agent logs in while a call in the Wrap-Up state is available.

Event Attributes

eventType (String)
OnWorkItemWrapup

item (Object)
The object with all available call data (See section Workitem Structure for a detailed description.)

Sample Code

The following sample code writes a log message when a call is disconnected and enters Wrap-Up.

Visualforce:

ConnectsIntegrationAPI.onWorkItemWrapup = function (event) {
    if (event.item.Channel == "VOICE") {
        ConnectsIntegrationAPI.writeLogDebug("Call from " + event.item.Sender + " to " +
            event.item.Destination + " is in Wrap-Up.");
    }
};

Lightning Aura/Web Component:

cnxIntegrationAPI.onWorkItemWrapup = function (event) {
    if (event.item.Channel == "VOICE") {
        cnxIntegrationAPI.writeLogDebug("Call from " + event.item.Sender + " to " +
            event.item.Destination + " is in Wrap-Up.");
    }
};

onWorkItemEnd(event)

This callback function is called when a work item disappears from the agent gadget. If Wrap-Up is enabled, this event is sent when Wrap-Up for the call ended. If Wrap-Up is not enabled, the event is sent immediately after hang-up.

Event Attributes

eventType (String)
OnWorkItemEnd

item (Object)
The object with all available call data (See section Workitem Structure for a detailed description.)

Sample Code

The following sample code writes a log message when a call is completely ended (when Wrap-Up for the call is enabled, the call ends when Wrap-Up ends).

Visualforce:

ConnectsIntegrationAPI.onWorkItemEnd = function (event) {
    if (event.item.Channel == "VOICE") {
        ConnectsIntegrationAPI.writeLogDebug("Call from " + event.item.Sender + " to " +
            event.item.Destination + " is ended.");
    }
};

Lightning Aura/Web Component:

cnxIntegrationAPI.onWorkItemEnd = function (event) {
    if (event.item.Channel == "VOICE") {
        cnxIntegrationAPI.writeLogDebug("Call from " + event.item.Sender + " to " +
            event.item.Destination + " is ended.");
    }
};

onCallVariableChanged(event)

This callback function is called when a call variable has changed (PerVars, NamedVariables and LocalVariables).

Event Attributes

eventType (String)
OnCallVariableChanged

item (Object)
The object with all available call data (See section Workitem Structure for a detailed description.)

Sample Code

The following sample code writes a log message when a Call Variable changes.

Visualforce:

ConnectsIntegrationAPI.onCallVariableChanged = function (event) {
    if (event.item.Channel == "VOICE") {
        ConnectsIntegrationAPI.writeLogDebug("A Call Variable has changed.");
    }
};

Lightning Aura/Web Component:

cnxIntegrationAPI.onCallVariableChanged = function (event) {
    if (event.item.Channel == "VOICE") {
        cnxIntegrationAPI.writeLogDebug("A Call Variable has changed.");
    }
};

onWrapUpDataChanged(event)

This callback function is called when a Wrap-Up reason is set or removed.
In case of a Media Item with Wrap-Up reason enabled (ref), this function is called on Item end if a Wrap-Up reason is selected by the Agent.

Event Attributes

eventType (String)
OnWrapUpDataChanged

item (Object)
The object with all available call data (See section Workitem Structure for a detailed description.)

Sample Code

The following sample code writes a log message when a Wrap-Up reason is set or removed.

Visualforce:

ConnectsIntegrationAPI.onWrapUpDataChanged = function (event) {
    if (event.item.Channel == "VOICE") {
        ConnectsIntegrationAPI.writeLogDebug("The Wrap-Up reason has changed.");
    }
};

Lightning Aura/Web Component:

cnxIntegrationAPI.onWrapUpDataChanged = function (event) {
    if (event.item.Channel == "VOICE") {
        cnxIntegrationAPI.writeLogDebug("The Wrap-Up reason has changed.");
    }
};

onBAResponseChanged(event)

This callback function is called when the BAResponse Named Variable has changed. This Variable is received as part of the Outbound Option Campaign data and stored in the named variables on the item object.

Event Attributes

eventType (String)
OnBAResponseChanged

item (Object)
The object with all available call data (See section Workitem Structure for a detailed description.)

Sample Code

The following sample code writes a log message when the BAResponse Named Variable has changed.

Visualforce:

ConnectsIntegrationAPI.onBAResponseChanged = function (event) {
    if (event.item.Channel == "VOICE") {
        ConnectsIntegrationAPI.writeLogDebug("The BAResponse Named Variable has changed.");
    }
};

Lightning Aura/Web Component:

cnxIntegrationAPI.onBAResponseChanged = function (event) {
    if (event.item.Channel == "VOICE") {
        cnxIntegrationAPI.writeLogDebug("The BAResponse Named Variable has changed.");
    }
};

onActivitySave(event)

This callback function is called when a call activity was created or updated by the b+s Connects Agent Gadget or when the activity was saved by Salesforce Interaction Log.

It is possible to update the created activity record with additional data from CTI when you receive this event.

Event Attributes

eventType (String)
OnActivitySave

recordId (String)
The Salesforce record id of the created call activity record

item (Object)
The object with all available call data (See section Workitem Structure for a detailed description.)

created (Boolean)
True, if the activity was created by the gadget False, if the activity was updated by the gadget If the activity record was created or updated by Salesforce Interaction Log feature, this parameter is not available in the event!

Sample Code

The following sample code adds a comment with data out of the item into the just created activity record.

Visualforce:

<apex:includeScript value="/soap/ajax/60.0/connection.js" />

ConnectsIntegrationAPI.onActivitySave = function (event) {
    try {
        if (event.created) {
            sforce.connection.sessionId = "{!$Api.Session_ID}";
            var task = sforce.connection.retrieve("Description", "Task", [event.recordId])[0];
            task.Description = "Comment added in onActivitySave event handler: Call from " +
                event.item.Sender + " to " + event.item.Destination;
            sforce.connection.update([task]);
        }
    } catch (ex) {
        ConnectsIntegrationAPI.showError("USER", "Update problem",
            "Could not update activity record, exception: " + ex);
    }
};

Lightning Aura/Web Component:

cnxIntegrationAPI.onActivitySave = function (event) {
    cnxIntegrationAPI.writeLogDebug("onActivitySave triggered for " + event.recordId);
};

onShareRecord(event)

This callback function is called when the agent presses the "ShareRecord" button to share the currently active record with the other agent.

info

When registering for this event, the default handling of the "share record" button is automatically disabled and only the callback function is executed. If the default behavior is desired, call the function "shareRecord" in the callback function.

Event Attributes

eventType (String)
OnShareRecord

pageInfo (Object)
The Salesforce page info as got from the Open CTI getPageInfo function.

Description from the SFDC Open CTI Developers Guide:

Returns the URL of the current page as an object, and includes any applicable object ID, object name, and object type.

For example: {"url":"http://<my-domain>.lightning.force.com/001x0000003DGQR", "recordId":"001x0000003DGQR", "recordName":"Acme", "objectType":"Account"}

item (Object)
The object with all available call data (See section Workitem Structure for a detailed description.)

Sample Code

The following sample calls the request function "shareRecord" with the objectId retrieved from the event but with recordType set to "Campaign" to always display the campaign icon on the link to open the record.

Visualforce:

ConnectsIntegrationAPI.onShareRecord = function (event) {
    if (event.pageInfo.recordId != "") {
        ConnectsIntegrationAPI.shareRecord(event.pageInfo.objectType, event.pageInfo.recordId);
    } else {
        ConnectsIntegrationAPI.showError("USER", "Invalid page", "This page cannot be shared.");
    }
};

Lightning Aura/Web Component:

cnxIntegrationAPI.onShareRecord = function (event) {
    if (event.pageInfo.recordId != "") {
        cnxIntegrationAPI.shareRecord(event.pageInfo.objectType, event.pageInfo.recordId);
    } else {
        cnxIntegrationAPI.showError("USER", "Invalid page", "This page cannot be shared.");
    }
};

onTeamDataUpdate(event)

This is a real time statistic event. It is fired when an agent in the team of the current agent changed his state.

These events are only fired when the current agent is logged in to voice channel. If registering the callback function here before the agent is logged in, events will appear as soon as the agent logs in.

The first event (with dataState = ENABLED) contains a list of all agents in the team.

The following events (with dataState = UPDATED) contain the data of one single updated agent.

As soon as the agent logs out, an event with an empty list (with dataState = DISABLED) will appear.

When the agent later logs in again, the event sequence described above starts again.

Event Attributes

eventType (String)
OnTeamDataUpdate

dataState (SUBSCRIPTION.STATE)
The state describing the received event data Can be ENABLED, DISABLED, UPDATED, or FAILED

teamName (String)
A string containing the name of the team, if the data state is ENABLED For all other data states, this argument is not available

teamId (String)
A string containing the ID of the team.

agentData (Array of Objects)
If the data state is ENABLED, the array contains a list of all agents in the team If the data state is DISABLED or FAILED, the array is empty If the data state is UPDATED, the array contains one entry with the updated agent The array contains 0, 1 or N objects of type realTimeAgentObject (see section realTimeAgentObject Structure for a detailed description)

error (String)
A string containing an error message if the data state is FAILED For all other data states, this argument is not available.

Sample Code

The following sample code logs the received events.

Visualforce:

ConnectsIntegrationAPI.onTeamDataUpdate = function (event) {
    if (event.dataState == ConnectsIntegrationAPI.SUBSCRIPTION.STATE.ENABLED) {
        ConnectsIntegrationAPI.writeLogDebug("Team data for " + event.teamName + " is available");
    } else if (event.dataState == ConnectsIntegrationAPI.SUBSCRIPTION.STATE.UPDATED) {
        ConnectsIntegrationAPI.writeLogDebug("The agent " + event.agentData[0].Agent +
            " is now in state " + event.agentData[0].State);
    } else if (event.dataState == ConnectsIntegrationAPI.SUBSCRIPTION.STATE.DISABLED) {
        ConnectsIntegrationAPI.writeLogDebug("Team data is no longer available.");
    } else if (event.dataState == ConnectsIntegrationAPI.SUBSCRIPTION.STATE.FAILED) {
        ConnectsIntegrationAPI.writeLogError("Could not subscribe to team data: " + event.error);
    }
};

Lightning Aura/Web Component:

cnxIntegrationAPI.onTeamDataUpdate = function (event) {
    if (event.dataState == cnxIntegrationAPI.SUBSCRIPTION.STATE.ENABLED) {
        cnxIntegrationAPI.writeLogDebug("Team data for " + event.teamName + " is available");
    } else if (event.dataState == cnxIntegrationAPI.SUBSCRIPTION.STATE.UPDATED) {
        cnxIntegrationAPI.writeLogDebug("The agent " + event.agentData[0].Agent +
            " is now in state " + event.agentData[0].State);
    } else if (event.dataState == cnxIntegrationAPI.SUBSCRIPTION.STATE.DISABLED) {
        cnxIntegrationAPI.writeLogDebug("Team data is no longer available.");
    } else if (event.dataState == cnxIntegrationAPI.SUBSCRIPTION.STATE.FAILED) {
        cnxIntegrationAPI.writeLogError("Could not subscribe to team data: " + event.error);
    }
};

onQueueDataUpdate(event)

This is a real time statistic event. It is fired when agent queue counters change. Finesse calculates and checks the counters for changes every 10 seconds.

These events are only fired when the current agent is logged in to voice channel. If registering the callback function here before the agent is logged in, events will appear as soon as agents log in.

The first event (with dataState = ENABLED) contains a list of all queues of the agent.

The following events (with dataState = UPDATED) contain the data of one single updated queue.

As soon as the agent logs out, an event with an empty list (with dataState = DISABLED) appears.

When the agent later logs in again, the event sequence described above starts again.

info

Please note that these events for queue statistics are not available in Cisco CCX.

Event Attributes

eventType (String)
OnQueueDataUpdate

dataState (SUBSCRIPTION.STATE)
The state describing the received event data Can be ENABLED, DISABLED, UPDATED, ADDED, DELETED, or FAILED

queueData (Array of Objects)

• If the data state is ENABLED the array contains a list of all queues of the currently signed in agent.
• If the data state is DISABLED or FAILED, the array is empty If the data state is ADDED or UPDATED, the array contains one entry with the updated queue.
• If the data state is DELETED, the array contains one entry with the deleted queue. In this case the realTimeQueueObject will only contain the Id property.

The array contains 0, 1 or N objects of type realTimeQueueObject (See section realTimeQueueObject Structure for a detailed description.)

error (String)
A string containing an error message if the data state is FAILED For all other data states, this argument is not available.

Sample Code

The following sample code logs the received events.

Visualforce:

ConnectsIntegrationAPI.onQueueDataUpdate = function (event) {
    if (event.dataState == ConnectsIntegrationAPI.SUBSCRIPTION.STATE.ENABLED) {
        ConnectsIntegrationAPI.writeLogDebug("Queue data is available.");
    } else if (event.dataState == ConnectsIntegrationAPI.SUBSCRIPTION.STATE.UPDATED) {
        ConnectsIntegrationAPI.writeLogDebug("The queue " + event.queueData[0].Name +
            " was updated.");
    } else if (event.dataState == ConnectsIntegrationAPI.SUBSCRIPTION.STATE.ADDED) {
        ConnectsIntegrationAPI.writeLogDebug("The queue " + event.queueData[0].Name +
            " was added.");
    } else if (event.dataState == ConnectsIntegrationAPI.SUBSCRIPTION.STATE.DELETED) {
        ConnectsIntegrationAPI.writeLogDebug("The queue with ID " + event.queueData[0].Id +
            " was deleted.");
    } else if (event.dataState == ConnectsIntegrationAPI.SUBSCRIPTION.STATE.DISABLED) {
        ConnectsIntegrationAPI.writeLogDebug("Queue data no longer available.");
    } else if (event.dataState == ConnectsIntegrationAPI.SUBSCRIPTION.STATE.FAILED) {
        ConnectsIntegrationAPI.writeLogError("Could not subscribe to queue data: " + event.error);
    }
};

Lightning Aura/Web Component:

cnxIntegrationAPI.onQueueDataUpdate = function (event) {
    if (event.dataState == cnxIntegrationAPI.SUBSCRIPTION.STATE.ENABLED) {
        cnxIntegrationAPI.writeLogDebug("Queue data is available.");
    } else if (event.dataState == cnxIntegrationAPI.SUBSCRIPTION.STATE.UPDATED) {
        cnxIntegrationAPI.writeLogDebug("The queue " + event.queueData[0].Name +
            " was updated.");
    } else if (event.dataState == cnxIntegrationAPI.SUBSCRIPTION.STATE.ADDED) {
        cnxIntegrationAPI.writeLogDebug("The queue " + event.queueData[0].Name +
            " was added.");
    } else if (event.dataState == cnxIntegrationAPI.SUBSCRIPTION.STATE.DELETED) {
        cnxIntegrationAPI.writeLogDebug("The queue with ID " + event.queueData[0].Id +
            " was deleted.");
    } else if (event.dataState == cnxIntegrationAPI.SUBSCRIPTION.STATE.DISABLED) {
        cnxIntegrationAPI.writeLogDebug("Queue data no longer available.");
    } else if (event.dataState == cnxIntegrationAPI.SUBSCRIPTION.STATE.FAILED) {
        cnxIntegrationAPI.writeLogError("Could not subscribe to queue data: " + event.error);
    }
};

onAgentStateChange(event)

This callback function is called when the state or reason code in a channel changed.

It is also called if a work item appears or disappears without changing the state field. This can happen on an incoming direct call in NOTREADY state.

info

The reported states for media channels differ between the MRI (MCAL) media deployment and the Finesse media deployment.

For media channels using the External Routing MRI (MCAL) deployment the state does not change (remains READY or NOTREADY) when a work item appears or disappears.

For media channels using the External Routing MRI 2.0 deployment the state changes to ACTIVE as soon as the agent receives a work item and stays ACTIVE while that work item is active. After the agent stops working on that work item, their state changes back to the original state or any state that the agent might have requested while working on the work item.

Event Attributes

eventType (String)
OnAgentStateChange

channelType (CHANNEL.TYPE)
The channel where the agent state changed Can be VOICE, TICKET or CHAT

newState (Object)
The object contains the following properties:

• State (CHANNEL.STATE)
• ReasonCode (String)
• ReasonCodeLabel (String)
• StateChangeTime (String)
• WorkItemCount (Number)

oldState (Object)
The object contains the following properties:

• State (CHANNEL.STATE)
• ReasonCode (String)
• ReasonCodeLabel (String)
• StateChangeTime (String)
• WorkItemCount (Number)

Sample Code

Visualforce:

ConnectsIntegrationAPI.onAgentStateChange = function (event) {
    ConnectsIntegrationAPI.writeLogDebug("New state in channel '" + event.channelType + "': " +
        event.newState.State + " (" + event.newState.ReasonCode + ")");
};

Lightning Aura/Web Component:

cnxIntegrationAPI.onAgentStateChange = function (event) {
    cnxIntegrationAPI.writeLogDebug("New state in channel '" + event.channelType + "': " +
        event.newState.State + " (" + event.newState.ReasonCode + ")");
};

onTranscriptUtteranceReceived(event)

This callback function is called when a transcript utterance is received from Cisco WCCAI service.

info

The transcript utterances are received from the moment the event is subscribed. Utterances generated before subscribing to the event will not trigger an event and can not be retrieved.

Return Value

eventType (String)
OnTranscriptUtteranceReceived

utterance (Object)
An utterance object (see section Utterance Structure for a detailed description).

Sample Code

Visualforce:

ConnectsIntegrationAPI.onTranscriptUtteranceReceived = function (event) {
    ConnectsIntegrationAPI.writeLogDebug("New utterance received: " + event.utterance.transcript);
};

Lightning Aura/Web Component:

cnxIntegrationAPI.onTranscriptUtteranceReceived = function (event) {
    cnxIntegrationAPI.writeLogDebug("New utterance received: " + event.utterance.transcript);
};

onAgentAnswersReceived(event)

This callback function is called when Agent Answers are received from Cisco WCCAI service.

info

The Agent Answers are received from the moment the event is subscribed. Agent Answers generated before subscribing to the event will not trigger an event and can not be retrieved.

Return Value

eventType (String)
OnAgentAnswersReceived

agentAnswers (Object)
An agentAnswers object (see section Agent Answers Structure for a detailed description).

Sample Code

Visualforce:

ConnectsIntegrationAPI.onAgentAnswersReceived = function (event) {
    ConnectsIntegrationAPI.writeLogDebug("New agent answers received: " + JSON.stringify(event.agentAnswers));
};

Lightning Aura/Web Component:

cnxIntegrationAPI.onAgentAnswersReceived = function (event) {
    cnxIntegrationAPI.writeLogDebug("New agent answers received: " +  JSON.stringify(event.agentAnswers));
};

Event Scenarios

Incoming Call without Wrap-Up

Incoming Call with Wrap-Up

Outgoing Call

Pause / Resume Call

Not Answered Call

Assign Call / Update Activity Comment

Transfer Call (Warm / Consultative Transfer)

Transfer Call (Cold / Blind Transfer)

Conference

Outbound Option Progressive / Predictive Mode

Outbound Option Preview / Direct Preview Mode (with Reservation Call)

Incoming Task

Pause / Resume Task

Requests (Custom Component Gadget)

These request functions are available in the b+s Connects Integration API. They forward the request to the b+s Connects Agent Gadget, receive the response and then fire the provided callback function with the result or return the result directly.

setLMSEnvironment(settings)

This function lets you set the variables that are required by the Connects Integration API to work with the Lightning Message Service.

info

This function is only needed if you use the Connects Integration API inside of Salesforce Lightning from a Visualforce Page.

Argument(s)

settings (Object)
An object that specifies the mode that the Connects Integration API should use. Depending on this mode there are various required attributes to be set. Mode Visualforce:

• channel: the id for the Message Channel

Return Value

None

Sample Code

Visualforce:

var messageChannel = "{!$MessageChannel.cnx__ConnectsIntegrationAPI__c}";
ConnectsIntegrationAPI.setLMSEnvironment({
    mode: "Visualforce",
    channel: messageChannel
});

Lightning Aura/Web Component:

Not needed as this is already done internally inside the ConnectsIntegrationAPI Lightning Aura/Web Component.

waitReady(callback)

Visualforce:

The waitReady function starts the initialization of the message channel used by the b+s Connects Integration API. How this depends on the Salesforce environment.

You cannot perform any requests before the Connects Integration API is fully initialized and the b+s Connects Agent Gadget has loaded and recovered all Channels.

Using the waitReady function allows you to also register a callback which is executed without any arguments once all these requirements are met. This ensures that the Connects Integration API is ready to respond to requests and events.

This function can be subscribed after the API is initialized, getting the callback executed immediately.

info

In Visualforce you are required to call the waitReady function before sending other requests. Before that there will be no events triggered.

Lightning Aura Component:

waitReady is an event triggered when the Connects Integration API is ready to be used. It contains the Connects Integration API as a parameter and you need to save it to a local variable in order to do further interactions with the Connects Integration API.

info

In a Lightning Aura Component you are required to handle the waitReady event in order to receive a reference to the b+s Connects Integration API. Without this reference you are not able to interact with the API.

Lightning Web Component

info

In Lightning Web Component the waitReady event is already handled by the intermediary service component, which returns the Connects Integration API object only when the API is ready to be used.

Argument(s)

callback (Function)
A callback function that is called after the b+s Connects Agent Gadget has started up and recovered all channels.

Return Value

None

Sample Code

Visualforce:

ConnectsIntegrationAPI.waitReady(function () {
    //here your code that is executed when the gadget is ready.
});

Or

function finishedInitialization () {
    //here your code that is executed when the gadget is ready.
};

ConnectsIntegrationAPI.waitReady(finishedInitialization);

Lightning Aura Component:

Event handler:

<aura:handler name="waitReady" event="cnx:ConnectsIntegrationAPIEvent" action="{!c.waitReady}"/>

Inside the Controller, as waitReady event handler:

waitReady: function (component, event, helper) {
    var cnxIntegrationAPI = component.find('cnxIntegrationAPI').get('v.noConflictConnectsIntegrationAPI');
}

Lightning Web Component:

Not needed as the waitReady() request is already handled in the intermediary service.

writeLogDebug(logMessage)

This function can be called to write a debug message into the log4javascript window.

Argument(s)

logMessage (String)
The message that will be logged into the log4javascript window

Return Value

None

Sample Code

Visualforce:

ConnectsIntegrationAPI.writeLogDebug("Hello world!");

Lightning Aura Component:

cnxIntegrationAPI.writeLogDebug("Hello world!");

writeLogError(logMessage)

This function can be called to write an error message into the log4javascript window.

Argument(s)

logMessage (String)
The message that will be logged into the log4javascript window

Return Value

None

Sample Code

Visualforce:

ConnectsIntegrationAPI.writeLogError("Houston, we have a problem!");

Lightning Aura Component:

cnxIntegrationAPI.writeLogError("Houston, we have a problem!");

getCustomSettings(identifier, callback)

This function can be called to read the configuration string of your Custom Component.

Argument(s)

identifier (String)
The Custom Component identifier. This identifier must be configured in the b+s Configuration in one of the Identifier fields

callback (Function)
A callback function that is executed when the request is completed It is called with a response object as parameter

The response object available in callback function contains the following fields:

success (Boolean)
true if the action was successful, false otherwise

data (String)
The value configured

error (String)
A string containing an error message if the action was not successful

Return Value

None

Sample Code

Visualforce:

ConnectsIntegrationAPI.getCustomSettings("MyComponent", function (response) {
    if (!response.success) {
        ConnectsIntegrationAPI.showError("USER", "getCustomSettings failed",response.error);
    }
});

Lightning Aura/Web Component:

cnxIntegrationAPI.getCustomSettings("MyComponent", function (response) {
    if (!response.success) {
        cnxIntegrationAPI.showError("USER", "getCustomSettings failed", response.error);
    }
});

showError(type, title, text [, callback])

This function can be called to show an error message to the agent on the bottom of the b+s Connects Agent Gadget.

Argument(s)

type (String)
The type of the error. This string will be shown on top of the error, before the title

title (String)
The title of the error message

text (String)
The description of the error message

callback (Function)
A callback function that is executed when the request is completed It is called with a response object as parameter

The response object available in callback function contains the following fields:

success (Boolean)
true if the action was successful, otherwise false

error (String)
A string containing an error message if the action was not successful

Return Value

None

Sample Code

Visualforce:

ConnectsIntegrationAPI.showError("USER", "Invalid record", "This record cannot be shared");

Lightning Aura/Web Component:

cnxIntegrationAPI.showError("USER", "Invalid record", "This record cannot be shared");

getFinesseVersion()

This function can be called to retrieve the Finesse server version information. If called while the agent is not logged in, it will return success "false" and the Finesse Version object with all the values assigned to zero.

Argument(s)

callback (Function)
A callback function that is executed when the request is completed It is called with a response object as parameter

The response object contains the following fields:

success (Boolean)
true if the action was successful, otherwise false

data (Object)
The Finesse Version object. (See section Finesse Version Structure for a detailed description of the Finesse Version data)

error (String)
A string containing an error message if the action was not successful

Return Value

None.

Sample Code

Visualforce:

ConnectsIntegrationAPI.getFinesseVersion(function (response) {
    if (!response.success) {
        ConnectsIntegrationAPI.showError("USER", "getFinesseVersion failed",response.error);
}
});

Lightning Aura/Web Component:

cnxIntegrationAPI.getFinesseVersion(function (response) {
    if (!response.success) {
        cnxIntegrationAPI.showError("USER", "getFinesseVersion failed", response.error);
    }
});

getCtiData()

This function can be called to get information about the agent, the channels (in the same order as in the gadget) and the currently active work items.

Argument(s)

None

Return Value

A ctiDataObject (see section ctiDataObject Structure for details) or null, if the data is not yet available.

Sample Code

Visualforce:

var currentCtiData = ConnectsIntegrationAPI.getCtiData();
if (currentCtiData) {
    ConnectsIntegrationAPI.writeLogDebug("The name of this agent is " + currentCtiData.FirstName +
        " " + currentCtiData.LastName);
}

Lightning Aura/Web Component:

var currentCtiData = cnxIntegrationAPI.getCtiData();
if (currentCtiData) {
    cnxIntegrationAPI.writeLogDebug("The name of this agent is " + currentCtiData.FirstName + " " +
        currentCtiData.LastName);
}

isMakeCallEnabled()

This function returns, whether the makeCall feature is enabled or not.

Argument(s)

None

Return Value

A Boolean value that indicates, whether the makeCall feature is enabled or not.

Sample Code

Visualforce:

if (ConnectsIntegrationAPI.isMakeCallEnabled()) {
    ConnectsIntegrationAPI.writeLogDebug("makeCall function is currently enabled");
}

Lightning Aura/Web Component:

if (cnxIntegrationAPI.isMakeCallEnabled()) {
    cnxIntegrationAPI.writeLogDebug("makeCall function is currently enabled");
}

makeCall(numberToDial, callVariables [, callback])

This function can be called to initiate an outgoing call or a consultation call.

Argument(s)

numberToDial (String)
The number that should be dialed

callVariables (Object)
An object of type itemVarObject.

info

Setting call variables with the makeCall request is only supported in CCE. Setting anything other than an empty object will result in an error.
Setting LocalVariables and WrapUpReason is also not supported by the makeCall request.

All variables PerVar1-10, NamedVariables are optional. Add only the variables that you want to add a value to.

dialNumberImmediately (boolean)
A boolean that defines whether or not the number should be dialed directly without having any dialing rules applied. If set to true, the onBeforeDial event is also skipped.

callback (Function)
A callback function that is executed when the request is completed It is called with a response object as parameter

The response object contains the following fields:

success (Boolean)
true if the action was successful, otherwise false

error (String)
A string containing an error message if the action was not successful

Return Value

None

Sample Code

Visualforce:

var callVariables = {};
callVariables.PerVar9 = "newValue";
callVariables.PerVar10 = "{k:MyTitle;v:MyValue}";
ConnectsIntegrationAPI.makeCall("12345", callVariables, false, function (response) {
    if (!response.success) {
        ConnectsIntegrationAPI.showError("USER", "makeCall failed", response.error);
    }
});

Lightning Aura/Web Component:

var callVariables = {};
callVariables.PerVar9 = "newValue";
callVariables.PerVar10 = "{k:MyTitle;v:MyValue}";
cnxIntegrationAPI.makeCall("12345", callVariables, false, function (response) {
    if (!response.success) {
        cnxIntegrationAPI.showError("USER", "makeCall failed", response.error);
    }
});

blindTransferCall(workItemId, numberToTransferTo, dialNumberImmediately [, callback])

This function can be called to initiate a blind transfer of an ongoing call.

Argument(s)

workItemId (String)
The work item ID

numberToTransferTo (String)
The number to which the call should be blind transferred

dialNumberImmediately (boolean)
A boolean that defines whether or not the number should be dialed directly without having any dialing rules applied. If set to true, the onBeforeDial event is also skipped.

callback (Function)
A callback function executed when the request is completed It is called with a response object as parameter

The response object contains the following fields:

success (Boolean)
true if the action was successful, otherwise false

error (String)
A string containing an error message if the action was not successful

Return Value

None

Sample Code

Visualforce:

ConnectsIntegrationAPI.blindTransferCall("12345", "3217654321", false, function (response) {
    if (!response.success) {
        ConnectsIntegrationAPI.showError("USER", "blindTransferCall failed", response.error);
    }
});

Lightning Aura/Web Component:

cnxIntegrationAPI.blindTransferCall("12345", "3217654321", false, function (response) {
    if (!response.success) {
        cnxIntegrationAPI.showError("USER", "blindTransferCall failed", response.error);
    }
});

conferenceConsultationCall(workItemId [, callback])

This function can be called to start a conference between the existing active call and a held call identified by workItemId.

Argument(s)

workItemId (String)
The work item ID

callback (Function)
A callback function that is executed when the request is completed It is called with a response object as parameter

The response object contains the following fields:

success (Boolean)
true if the action was successful, otherwise false

error (String)
A string containing an error message if the action was not successful

Return Value

None

Sample Code

Visualforce:

ConnectsIntegrationAPI.conferenceConsultationCall("12345", function (response) {
    if (!response.success) {
        ConnectsIntegrationAPI.showError("USER", "conferenceConsultationCall failed", response.error);
    }
});

Lightning Aura/Web Component:

cnxIntegrationAPI.conferenceConsultationCall("12345", function (response) {
    if (!response.success) {
        cnxIntegrationAPI.showError("USER", "conferenceConsultationCall failed", response.error);
    }
});

transferConsultationCall(workItemId [, callback])

This function can be called to complete a transfer between the existing active call and a held call identified by workItemId.

Argument(s)

workItemId (String)
The work item ID

callback (Function)
A callback function that is executed when the request is completed It is called with a response object as parameter

The response object contains the following fields:

success (Boolean)
true if the action was successful, otherwise false

error (String)
A string containing an error message if the action was not successful

Return Value

None

Sample Code

Visualforce:

ConnectsIntegrationAPI.transferConsultationCall("12345", function (response) {
    if (!response.success) {
        ConnectsIntegrationAPI.showError("USER", "transferConsultationCall failed", response.error);
    }
});

Lightning Aura/Web Component:

cnxIntegrationAPI.transferConsultationCall("12345", function (response) {
    if (!response.success) {
        cnxIntegrationAPI.showError("USER", "transferConsultationCall failed", response.error);
    }
});

getTeamMessagesByTeamId(teamId, callback)

This function can be called to get all team messages by its ID.

Argument(s)

teamId (String)
The team ID

callback (Function)
A callback function that is executed when the request is completed It is called with a response object as parameter

The response object contains the following fields:

success (Boolean)
true if the action was successful, otherwise false

data (Array of Objects)
An array of team message objects. (See section TeamMessages Structure for a detailed description of the data)

error (String)
A string containing an error message if the action was not successful

Return Value

None

Sample Code

Visualforce:

ConnectsIntegrationAPI.getTeamMessagesByTeamId("5000", function (response) {
    if (!response.success) {
        ConnectsIntegrationAPI.showError("USER", "getTeamMessagesByTeamId failed", response.error);
    }
});

Lightning Aura/Web Component:

cnxIntegrationAPI.getTeamMessagesByTeamId("5000", function (response) {
    if (!response.success) {
        cnxIntegrationAPI.showError("USER", "getTeamMessagesByTeamId failed", response.error);
    }
});

getActiveTeamMessages(callback)

This function can be called to get all team messages from the logged in user. The user has to be a supervisor.

Argument(s)

callback (Function)
A callback function that is executed when the request is completed It is called with a response object as parameter

The response object contains the following fields:

success (Boolean)
true if the action was successful, otherwise false

data (Array of Objects)
An array of team message objects. (See section TeamMessages Structure for a detailed description of the data)

error (String)
A string containing an error message if the action was not successful

Return Value

None

Sample Code

Visualforce:

ConnectsIntegrationAPI.getActiveTeamMessages(function (response) {
    if (!response.success) {
        ConnectsIntegrationAPI.showError("USER", "getActiveTeamMessages failed", response.error);
    }
});

Lightning Aura/Web Component:

cnxIntegrationAPI.getActiveTeamMessages(function (response) {
    if (!response.success) {
        cnxIntegrationAPI.showError("USER", "getActiveTeamMessages failed", response.error);
    }
});

createTeamMessage(duration, content, teams [, callback])

This function can be called to create a new team message. The user has to be a supervisor.

Argument(s)

duration (Number)
The life span of the team message in seconds.

content (String)
The team message text

teams (Array of Strings)
An array of team IDs to send the message to. The logged in user has to be a supervisor of those teams.

callback (Function)
A callback function that is executed when the request is completed It is called with a response object as parameter

The response object contains the following fields:

success (Boolean)
true if the action was successful, otherwise false

error (String)
A string containing an error message if the action was not successful

Return Value

None

Sample Code

Visualforce:

ConnectsIntegrationAPI.createTeamMessage(100, "my message", ["5000", "5050"], function (response) {
    if (!response.success) {
        ConnectsIntegrationAPI.showError("USER", "createTeamMessage failed", response.error);
    }
});

Lightning Aura/Web Component:

cnxIntegrationAPI.createTeamMessage(100, "my message", ["5000", "5050"], function (response) {
    if (!response.success) {
        cnxIntegrationAPI.showError("USER", "createTeamMessage failed", response.error);
    }
});

deleteTeamMessage(teamMessageId [, callback])

This function can be called to delete a team message. The user has to be a supervisor.

Argument(s)

teamMessageId (String)
The ID of the team message to delete.

callback (Function)
A callback function that is executed when the request is completed It is called with a response object as parameter

The response object contains the following fields:

success (Boolean)
true if the action was successful, otherwise false

error (String)
A string containing an error message if the action was not successful

Return Value

None

Sample Code

Visualforce:

ConnectsIntegrationAPI.deleteTeamMessage("be1598bb-bb2a-4dfc-8c01-91ec10b029a", function (response) {
    if (!response.success) {
        ConnectsIntegrationAPI.showError("USER", "deleteTeamMessage failed", response.error);
    }
});

Lightning Aura/Web Component:

cnxIntegrationAPI.deleteTeamMessage("be1598bb-bb2a-4dfc-8c01-91ec10b029a", function (response) {
    if (!response.success) {
        cnxIntegrationAPI.showError("USER", "deleteTeamMessage failed", response.error);
    }
});

isSendDtmfEnabled()

This function returns, whether the sendDtmf feature is enabled or not.

Argument(s)

None

Return Value

A Boolean value that indicates, whether the sendDtmf feature is enabled or not.

Sample Code

Visualforce:

if (ConnectsIntegrationAPI.isSendDtmfEnabled()) {
    ConnectsIntegrationAPI.writeLogDebug("sendDtmf function is currently enabled");
}

Lightning Aura/Web Component:

if (cnxIntegrationAPI.isSendDtmfEnabled()) {
    cnxIntegrationAPI.writeLogDebug("sendDtmf function is currently enabled");
}

sendDtmf(dtmf [, callback])

This function can be called to send a dual-tone multifrequency (DTMF) string during a call.

Argument(s)

dtmf (String)
The dtmf to be send to the active call Note: The DTMF string to submit can contain 0-9, *, ##, or A-D for Unified CCE. For Unified CCX, the value can only contain 0-9, *, or ##.

callback (Function)
A callback function that is executed when the request is completed It is called with a response object as parameter

The response object contains the following fields:

success (Boolean)
true if the action was successful, otherwise false otherwise

error (String)
A string containing an error message if the action was not successful

Return Value

None

Sample Code

Visualforce:

ConnectsIntegrationAPI.sendDtmf("12345", function (response) {
    if (!response.success) {
        ConnectsIntegrationAPI.showError("USER", "sendDtmf failed", response.error);
    }
});

Lightning Aura/Web Component:

cnxIntegrationAPI.sendDtmf("12345", function (response) {
    if (!response.success) {
        cnxIntegrationAPI.showError("USER", "sendDtmf failed", response.error);
    }
});

startItem(workItemType, workItemId [, callback])

This function can be called to start a work item. In the case of a ringing call, startItem answers the call. An offered case/ticket/chat is accepted with startItem.

Argument(s)

workItemType (WORKITEM.TYPE)
The channel that the item is on. Can be VOICE, TICKET or CHAT

workItemId (String)
The work item ID

callback (Function)
A callback function that is executed when the request is completed It is called with a response object as parameter

The response object contains the following fields:

success (Boolean)
true if the action was successful, otherwise false

error (String)
A string containing an error message if the action was not successful

Return Value

None

Sample Code

Visualforce:

var workItemType = ConnectsIntegrationAPI.WORKITEM.TYPE.VOICE;
ConnectsIntegrationAPI.startItem(workItemType, "12345", function (response) {
    if (!response.success) {
        ConnectsIntegrationAPI.showError("USER", "startItem failed", response.error);
    }
});

Lightning Aura/Web Component:

var workItemType = cnxIntegrationAPI.WORKITEM.TYPE.VOICE;
cnxIntegrationAPI.startItem(workItemType, "12345", function (response) {
    if (!response.success) {
        cnxIntegrationAPI.showError("USER", "startItem failed", response.error);
    }
});

wrapUpItem(workItemType, workItemId [, callback])

This function can be called to put a media task into the wrap-up state.

caution

This function does only work for media tasks.

Argument(s)

workItemType (WORKITEM.TYPE)
The channel that the item is on. Can be TICKET, or CHAT

workItemId (String)
The work item ID

callback (Function)
A callback function that is executed when the request is completed It is called with a response object as parameter

The response object contains the following fields:

success (Boolean)
true if the action was successful, otherwise false

error (String)
A string containing an error message if the action was not successful

Return Value

None

Sample Code

Visualforce:

var workItemType = ConnectsIntegrationAPI.WORKITEM.TYPE.TICKET;
ConnectsIntegrationAPI.wrapUpItem(workItemType, "12345", function (response) {
    if (!response.success) {
        ConnectsIntegrationAPI.showError("USER", "wrapUpItem failed", response.error);
    }
});

Lightning Aura/Web Component:

var workItemType = cnxIntegrationAPI.WORKITEM.TYPE.TICKET;
cnxIntegrationAPI.wrapUpItem(workItemType, "12345", function (response) {
    if (!response.success) {
        cnxIntegrationAPI.showError("USER", "wrapUpItem failed", response.error);
    }
});

endItem(workItemType, workItemId [, callback])

This function can be called to end a work item. In the case of an established call, endItem ends the call. Started case/ticket/chat is ended with endItem.

Argument(s)

workItemType (WORKITEM.TYPE)
The channel that the item is on. Can be VOICE, TICKET, or CHAT

workItemId (String)
The work item ID

callback (Function)
A callback function that is executed when the request is completed It is called with a response object as parameter

The response object contains the following fields:

success (Boolean)
true if the action was successful, otherwise false

error (String)
A string containing an error message if the action was not successful

Return Value

None

Sample Code

Visualforce:

var workItemType = ConnectsIntegrationAPI.WORKITEM.TYPE.VOICE;
ConnectsIntegrationAPI.endItem(workItemType, "12345", function (response) {
    if (!response.success) {
        ConnectsIntegrationAPI.showError("USER", "endItem failed", response.error);
    }
});

Lightning Aura/Web Component:

var workItemType = cnxIntegrationAPI.WORKITEM.TYPE.VOICE;
cnxIntegrationAPI.endItem(workItemType, "12345", function (response) {
    if (!response.success) {
        cnxIntegrationAPI.showError("USER", "endItem failed", response.error);
    }
});

isShareRecordEnabled()

This function returns, whether or not the shareRecord feature is enabled.

Argument(s)

None

Return Value

A Boolean value that indicates, whether or not the shareRecord feature is enabled.

Sample Code

Visualforce:

if (ConnectsIntegrationAPI.isShareRecordEnabled()) {
    ConnectsIntegrationAPI.writeLogDebug("shareRecord function is currently enabled");
}

Lightning Aura/Web Component:

if (cnxIntegrationAPI.isShareRecordEnabled()) {
    cnxIntegrationAPI.writeLogDebug("shareRecord function is currently enabled");
}

shareRecord(recordType, recordId [, callback])

This function is used to share a salesforce record with other call participants.

Argument(s)

recordType (String)
The type of the record that will be shared (e.g. "Contact"), used for the displayed icon on the link

recordId (String)
The id of the record that will be shared (e.g. "005U00000023iYb")

callback (Function)
A callback function that is executed when the request is completed It is called with a response object as parameter

The response object contains the following fields:

success (Boolean)
true if the action was successful, otherwise false

error(String)
A string containing an error message if the action was not successful

Return Value

None

Sample Code

Visualforce:

ConnectsIntegrationAPI.shareRecord("Contact", "00500000023iYb", function (response) {
    if (!response.success) {
        ConnectsIntegrationAPI.showError("USER", "shareRecord failed", response.error);
    }
});

Lightning Aura/Web Component:

cnxIntegrationAPI.shareRecord("Contact", "00500000023iYb", function (response) {
    if (!response.success) {
        cnxIntegrationAPI.showError("USER", "shareRecord failed", response.error);
    }
});

isUpdateWorkItemDataEnabled(workItemType, workItemId)

This function returns, whether or not it is possible to update the data of a work item that is on the specific channel.

Argument(s)

workItemType (WORKITEM.TYPE)
The specific channel that should be checked Can be VOICE, TICKET, or CHAT

workItemId (String)
The ID of the work item to be checked

Return Value

A Boolean value that indicates, whether or not it is possible to update the data of a work item of the specific channel.

If invalid arguments are passed to the function an error is logged and the function returns null.

Sample Code

Visualforce:

var workItemType = ConnectsIntegrationAPI.WORKITEM.TYPE.VOICE;
var workItemId = ConnectsIntegrationAPI.getFirstWorkItemId(workItemType);
if (ConnectsIntegrationAPI.isUpdateWorkItemDataEnabled(workItemType, workItemId)) {
    ConnectsIntegrationAPI.writeLogDebug("updateWorkItemData function for VOICE is currently" + "enabled");
}

Lightning Aura/Web Component:

var channelType = cnxIntegrationAPI.WORKITEM.TYPE.VOICE;
var workItemId = cnxIntegrationAPI.getFirstWorkItemId(channelType);
if (cnxIntegrationAPI.isUpdateWorkItemDataEnabled(channelType, workItemId)) {
    cnxIntegrationAPI.writeLogDebug("updateWorkItemData function for VOICE is currently enabled");
}

updateWorkItemData(workItemType, workItemId, updatedData [, callback])

This function can be called to update peripheral variables, ECC variables (named variables), local variables and/or the Wrap-Up reason of a work item (call, ticket or chat).

Peripheral variables, ECC variables (named variables) and Wrap-Up reasons are forwarded to Cisco CCE/CCX and are also displayed in the b+s Connects Agent Gadget of the second agent in case of a call transfer.

Local variables are used only locally in the current browser and are not forwarded to Cisco CCE/CCX or another agent. They are intended to display some data in the b+s Connects Agent Gadget or temporarily store some data with the call.

To display any data or link inside the b+s Connects Agent Gadget to the agent, please follow the instructions in the Display Customizable Data section.

(Short sample: {k:MyTitle;v:MyValue} displays a line with title "MyTitle" and the value "MyValue" in the b+s Connects Agent Gadget.)

info

When a custom Wrap-Up reason is set using the Integration API, the new value is automatically added as selected to the list of available Wrap-Up reasons in the gadget. When a different reason is manually selected from the list or set via Integration API, the previously custom set reason is removed from the list.

Argument(s)

workItemType (WORKITEM.TYPE)
The channel where the item that should be updated is located. Can be VOICE, TICKET, or CHAT

workItemId (String)
The work item ID, to be updated

updatedData (Object)
An object of type itemVarObject.
All variables PerVar1-10, NamedVariables, LocalVariables, WrapUpReason are optional. Add only the variables that should be changed. All other variables of the call will keep their current value

callback (Function)
A callback function that is executed when the request is completed It is called with a response object as parameter

The response object contains the following fields:

success (Boolean)
true if the action was successful, otherwise false

error (String)
A string containing an error message if the action was not successful

Return Value

None

Sample Code

Visualforce:

var workItemType = ConnectsIntegrationAPI.WORKITEM.TYPE.VOICE;
var workItemId = ConnectsIntegrationAPI.getFirstWorkItemId(workItemType);
if (workItemId) {
    var update = {};
    update.PerVar9 = "newValue";
    update.PerVar10 = "{k:MyTitle;v:MyValue}";
    update.WrapUpReason = "New Custom WrapUp Reason";
    ConnectsIntegrationAPI.updateWorkItemData(workItemType, workItemId, update, function (response) {
        if (!response.success) {
            ConnectsIntegrationAPI.showError("USER", "updateWorkItemData failed", response.error);
        }
    });
}

Lightning Aura/Web Component:

var workItemType = cnxIntegrationAPI.WORKITEM.TYPE.VOICE;
var workItemId = cnxIntegrationAPI.getFirstWorkItemId(workItemType);
if (workItemId) {
    var update = {};
    update.PerVar9 = "newValue";
    update.PerVar10 = "{k:MyTitle;v:MyValue}";
    update.WrapUpReason = "New Custom WrapUp Reason";
    cnxIntegrationAPI.updateWorkItemData(workItemType, workItemId, update, function (response) {
        if (!response.success) {
            cnxIntegrationAPI.showError("USER", "updateWorkItemData failed", response.error);
        }
    });
}

info

For incoming calls in state "ringing" only local variables are allowed to be set. Setting peripheral variables and/or ECC variables in this state is an invalid action (CCE/CCX limitation) and throws an error.

getLastWorkItems(channelType, callback)

This function can be called to get information about the last calls and tickets.

Argument(s)

channelType (CHANNEL.TYPE)
The channel for which the last work items should be returned Can be OVERALL, VOICE, TICKET, or CHAT

callback (Function)
A callback function that is executed when the request is completed It is called with a response object as parameter

The response object contains the following fields:

success (Boolean)
true if the action was successful, otherwise false

data (String)
A JSON encoded string containing an array of work items (See section Workitem Structure for a detailed description of the WorkItem data)

error (String)
A string containing an error message if the action was not successful

Return Value

None

Sample Code

Visualforce:

var channelType = ConnectsIntegrationAPI.CHANNEL.TYPE.VOICE;
ConnectsIntegrationAPI.getLastWorkItems(channelType, function (response) {
    if (response.success) {
        var calls = JSON.parse(response.data);
        calls.forEach(function (call) {
            ConnectsIntegrationAPI.writeLogDebug("Call from " + call.Sender + " to " +
                call.Destination);
        });
    } else {
        ConnectsIntegrationAPI.showError("USER", "getLastWorkItems failed", response.error);
    }
});

Lightning Aura/Web Component:

var channelType = cnxIntegrationAPI.CHANNEL.TYPE.VOICE;
cnxIntegrationAPI.getLastWorkItems(channelType, function (response) {
    if (response.success) {
        var calls = JSON.parse(response.data);
        calls.forEach(function (call) {
            cnxIntegrationAPI.writeLogDebug("Call from " + call.Sender + " to " + call.Destination);
        });
    } else {
        cnxIntegrationAPI.showError("USER", "getLastWorkItems failed", response.error);
    }
});

setAgentState(channelType, channelState, reason [, callback])

This function can be called to set the state of the agent on a specific channel.

Argument(s)

channelType (CHANNEL.TYPE)
The channel on which the state will be changed Can be OVERALL, VOICE, TICKET, or CHAT

channelState (CHANNEL.STATE)
The new state for the channel Can be READY, NOT_READY, WORK, WORK_READY or LOGOUT

info

WORK and WORK_READY states are used to request Wrap-Up and are only available for VOICE Channel Type and from the TALKING Channel State

reason (Number)
Used to select a not ready reason When not ready reasons are defined in Finesse, it is necessary to fill the provided valid reason code number here, otherwise the request will fail

callback (Function)
A callback function that is executed when the request is completed It is called with a response object as parameter

The response object contains the following fields:

success (Boolean)
true if the action was successful, otherwise false

error (String)
A string containing an error message if the action was not successful

Return Value

None

Sample Code

Visualforce:

var channelType = ConnectsIntegrationAPI.CHANNEL.TYPE.OVERALL;
var channelState = ConnectsIntegrationAPI.CHANNEL.STATE.READY;
ConnectsIntegrationAPI.setAgentState(channelType, channelState, 0, function (response) {
    if (!response.success) {
        ConnectsIntegrationAPI.showError("USER", "setAgentState failed", response.error);
    }
});

Lightning Aura/Web Component:

var channelType = cnxIntegrationAPI.CHANNEL.TYPE.OVERALL;
var channelState = cnxIntegrationAPI.CHANNEL.STATE.READY;
cnxIntegrationAPI.setAgentState(channelType, channelState, 0, function (response) {
    if (!response.success) {
        cnxIntegrationAPI.showError("USER", "setAgentState failed", response.error);
    }
});

getChannel(channelType)

This is a helper function.

It returns information, such as the current state, about a specific channel type.

Argument(s)

channelType (CHANNEL.TYPE)
Can be VOICE, TICKET or CHAT.

Return Value

Null, if the data is not available. Otherwise, a channel object as it is present in the current CTI data (see Channel sub object in section ctiDataObject Structure for more details).

Sample Code

Visualforce:

var channelType = ConnectsIntegrationAPI.CHANNEL.TYPE.VOICE;
var channelData = ConnectsIntegrationAPI.getChannel(channelType);
if (channelData) {
    ConnectsIntegrationAPI.writeLogDebug("The current state of the channel 'VOICE' is " + channelData.State);
}

Lightning Aura/Web Component:

var channelType = cnxIntegrationAPI.CHANNEL.TYPE.VOICE;
var channelData = cnxIntegrationAPI.getChannel(channelType);
if (channelData) {
    cnxIntegrationAPI.writeLogDebug("The current state of the channel 'VOICE' is " + channelData.State);
}

getFirstWorkItem(workItemType)

This is a helper function.

It returns only the first object of the channel type from the data that the getCtiData()function returns.

You can use this to easily access the work item data in the most common case with only one active work item on the agent gadget.

Argument(s)

workItemType (WORKITEM.TYPE)
Can be VOICE, TICKET, or CHAT

Return Value

A WorkItem object (see section Workitem Structure for a detailed description) or null, if the data is not available.

Sample Code

Visualforce:

var workItemType = ConnectsIntegrationAPI.WORKITEM.TYPE.VOICE;
var firstWorkItemData = ConnectsIntegrationAPI.getFirstWorkItem(workItemType);
if (firstWorkItemData) {
    ConnectsIntegrationAPI.writeLogDebug("The current state of the first work item is " +
        firstWorkItemData.State);
}

Lightning Aura/Web Component:

var workItemType = cnxIntegrationAPI.WORKITEM.TYPE.VOICE;
var firstWorkItemData = cnxIntegrationAPI.getFirstWorkItem(workItemType);
if (firstWorkItemData) {
    cnxIntegrationAPI.writeLogDebug("The current state of the first work item is " +
        firstWorkItemData.State);
}

getSecondWorkItem(workItemType)

This is a helper function.

It returns only the second object of the channel type from the data that the getCtiData() function returns.

You can for example, use this to easily access the consultation call data in a simple consult call scenario.

Argument(s)

workItemType (WORKITEM.TYPE)
Can be VOICE, TICKET, or CHAT

Return Value

A WorkItem object (see section Workitem Structure for a detailed description) or null, if the data is not available.

Sample Code

Visualforce:

var workItemType = ConnectsIntegrationAPI.WORKITEM.TYPE.VOICE;
var secondWorkItemData = ConnectsIntegrationAPI.getSecondWorkItem(workItemType);
if (secondWorkItemData) {
    ConnectsIntegrationAPI.writeLogDebug("The current state of the second work item is " +
        secondWorkItemData.State);
}

Lightning Aura/Web Component:

var workItemType = cnxIntegrationAPI.WORKITEM.TYPE.VOICE;
var secondWorkItemData = cnxIntegrationAPI.getSecondWorkItem(workItemType);
if (secondWorkItemData) {
    cnxIntegrationAPI.writeLogDebug("The current state of the second work item is " +
        secondWorkItemData.State);
}

getFirstWorkItemId(workItemType)

This is a helper function.

It returns only the work item id of the channel types first object from the data that the getCtiData() function returns.

You can use this to easily access the work item id in the most common case with only one active work item on the b+s Connects Agent Gadget.

Argument(s)

workItemType (WORKITEM.TYPE)
Can be VOICE, TICKET, or CHAT

Return Value

The id of the first existing work item of the channel type or an empty string, if no work item is available.

Sample Code

Visualforce:

var workItemType = ConnectsIntegrationAPI.WORKITEM.TYPE.VOICE;
var firstWorkItemId = ConnectsIntegrationAPI.getFirstWorkItemId(workItemType);
if (firstWorkItemId) {
    ConnectsIntegrationAPI.writeLogDebug("The id of the first work item is " + firstWorkItemId);
}

Lightning Aura/Web Component:

var workItemType = cnxIntegrationAPI.WORKITEM.TYPE.VOICE;
var firstWorkItemId = cnxIntegrationAPI.getFirstWorkItemId(workItemType);
if (firstWorkItemId) {
    cnxIntegrationAPI.writeLogDebug("The id of the first work item is " + firstWorkItemId);
}

getSecondWorkItemId(workItemType)

This is a helper function.

It returns only the work item ID of the channel types second object from the data that the getCtiData() function returns.

It is possible to use this to do things like access the consultation call work item ID in a simple consult call scenario.

Argument(s)

workItemType (WORKITEM.TYPE)
Can be VOICE, TICKET, or CHAT

Return Value

The ID of the second existing work item of the channel type or an empty string, if no work item is available.

Sample Code

Visualforce:

var workItemType = ConnectsIntegrationAPI.WORKITEM.TYPE.VOICE;
var secondWorkItemId = ConnectsIntegrationAPI.getSecondWorkItemId(workItemType);
if (secondWorkItemId) {
    ConnectsIntegrationAPI.writeLogDebug("The id of the second work item is " + secondWorkItemId);
}

Lightning Aura/Web Component:

var workItemType = cnxIntegrationAPI.WORKITEM.TYPE.VOICE;
var secondWorkItemId = cnxIntegrationAPI.getSecondWorkItemId(workItemType);
if (secondWorkItemId) {
    cnxIntegrationAPI.writeLogDebug("The id of the second work item is " + secondWorkItemId);
}

setCustomToolbarSize(toolbarPosition, height [, callback])

This function can be called to change the height of a custom toolbar.

It is possible to use this to do things like add a button to expand/collapse the custom toolbar.

Argument(s)

toolbarPosition (TOOLBAR_POSITION)
Can be TOP, BOTTOM, or AUTO

height (Integer)
New height of the toolbar in pixels Can be set to 0 to completely hide the toolbar

callback (Function)
A callback function that is executed when the request is completed It is called with a response object as parameter

The response object contains the following fields:

success (Boolean)
true if the action was successful, otherwise false

error (String)
A string containing an error message if the action was not successful

Return Value

None

Sample Code

Visualforce:

var toolbarPosition = ConnectsIntegrationAPI.GENERAL.TOOLBAR_POSITION.TOP;
ConnectsIntegrationAPI.setCustomToolbarSize(toolbarPosition, 55, function (response) {
    if (!response.success) {
        ConnectsIntegrationAPI.showError("USER", "setCustomToolbarSize failed", response.error);
    }
});

Lightning Aura/Web Component:

var toolbarPosition = cnxIntegrationAPI.GENERAL.TOOLBAR_POSITION.TOP;
cnxIntegrationAPI.setCustomToolbarSize(toolbarPosition, 55, function (response) {
    if (!response.success) {
        cnxIntegrationAPI.showError("USER", "setCustomToolbarSize failed", response.error);
    }
});

getCustomToolbarDefaultSize(toolbarPosition, callback)

This function can be called to get the configured default size of the toolbar.

Argument(s)

toolbarPosition (TOOLBAR_POSITION)
Can be TOP, BOTTOM, or AUTO

callback (Function)
A callback function that is executed when the request is completed It is called with a response object as parameter

The response object contains the following fields:

success (Boolean)
true if the action was successful, otherwise false

data.height (Integer)
The default height of the toolbar

error (String)
A string containing an error message if the action was not successful

Return Value

None

Sample Code

Visualforce:

var toolbarPosition = ConnectsIntegrationAPI.GENERAL.TOOLBAR_POSITION.TOP;
ConnectsIntegrationAPI.getCustomToolbarDefaultSize(toolbarPosition, function (response) {
    if (response.success) {
        ConnectsIntegrationAPI.writeLogDebug("Top toolbar default height is: " +
            response.data.height);
    }
});

Lightning Aura/Web Component:

var toolbarPosition = cnxIntegrationAPI.GENERAL.TOOLBAR_POSITION.TOP;
cnxIntegrationAPI.getCustomToolbarDefaultSize(toolbarPosition, function (response) {
    if (response.success) {
        cnxIntegrationAPI.writeLogDebug("Top toolbar default height is: " + response.data.height);
    }
});

setGadgetVisibility(visible [, callback])

This function can be called to set the gadget to be visible or not visible (minimized).

The request is forwarded to sforce.interaction.setVisible().

Argument(s)

visible (Boolean)
Boolean determining whether the gadget should be visible (true) or not visible (false)

callback (Function)
A callback function that is executed when the request is completed It is called with a response object as parameter

The response object contains the following fields:

success (Boolean)
true if the action was successful, otherwise false

error (String)
A string containing an error message if the action was not successful

Return Value

None

Sample Code

Visualforce:

ConnectsIntegrationAPI.setGadgetVisibility(true, function (response) {
    if (!response.success) {
        ConnectsIntegrationAPI.showError("USER", "setGadgetVisibility failed", response.error);
    }
});

Lightning Aura/Web Component:

cnxIntegrationAPI.setGadgetVisibility(true, function (response) {
    if (!response.success) {
        cnxIntegrationAPI.showError("USER", "setGadgetVisibility failed", response.error);
    }
});

screenPop(toPop [, callback])

This function can be called to open Salesforce links or external pages.

In Salesforce Classic Console the request is forwarded to sforce.interaction.screenPop(), in Salesforce Lightning Experience and Lightning Console the request is forwarded to sforce.opencti.screenPop().

Argument(s)

toPop (String)
A string which contains the Salesforce ID, Salesforce Link (e.g. Visualforce Page) or External URL to pop

callback (Function)
A callback function that is executed when the request is completed It is called with a response object as parameter

The response object contains the following fields:

success (Boolean)
true if the action was successful, otherwise false

error (String)
A string containing an error message if the action was not successful

Return Value

None

Sample Code

Visualforce:

var recordId = "001U000001cmsUu"; //Some record id
var sfLink = "/apex/SfdcWelcome"; //Some Salesforce Link
var externalURL = "https://google.ch"; //Some External URL
var callback = function (response) {
    if (!response.success) {
        ConnectsIntegrationAPI.showError("USER", "screenPop failed", response.error);
    }
}
ConnectsIntegrationAPI.screenPop(recordId, callback);
ConnectsIntegrationAPI.screenPop(sfLink, callback);
ConnectsIntegrationAPI.screenPop(externalURL, callback);

Lightning Aura/Web Component:

var recordId = "001U000001cmsUu"; //Some record id
var sfLink = "/apex/SfdcWelcome"; //Some Salesforce Link
var externalURL = "https://google.ch"; //Some External URL
var callback = function (response) {
    if (!response.success) {
        cnxIntegrationAPI.showError("USER", "screenPop failed", response.error);
    }
}
cnxIntegrationAPI.screenPop(recordId, callback);
cnxIntegrationAPI.screenPop(sfLink, callback);
cnxIntegrationAPI.screenPop(externalURL, callback);

screenPopToSearch(searchString [, callback])

This function can be called to trigger a screen pop to a search page.

caution

This function is supported in Salesforce Lightning and Lightning Console only.

Argument(s)

searchString (String)
Pops to the Top Results section of the search page. The string must be at least 3 characters in length. Example: "John Doe"

callback (Function)
A callback function that is executed when the request is completed It is called with a response object as parameter

The response object contains the following fields:

success (Boolean)
true if the action was successful, otherwise false

error (String)
A string containing an error message if the action was not successful

Return Value

None

Sample Code

Visualforce:

var searchString = "John Doe";
ConnectsIntegrationAPI.screenPopToSearch(searchString, function (response) {
    if (!response.success) {
        ConnectsIntegrationAPI.showError("USER", "screenPopToSearch failed", response.error);
    }
});

Lightning Aura/Web Component:

var searchString = "John Doe";
cnxIntegrationAPI.screenPopToSearch(searchString, function (response) {
    if (!response.success) {
        cnxIntegrationAPI.showError("USER", "screenPopToSearch failed", response.error);
    }
});

screenPopToFlow(flowDevName, flowArgs [, callback])

This function can be called to trigger a screen pop to a flow.

caution

This function is supported in Salesforce Lightning and Lightning Console only.

Argument(s)

flowDevName (String)
Developer name of a flow Example: sample_flow

flowArgs (Array)
Array with arguments to pass to the Flow. Example: [{name: "phoneVariable", type: "String", value: "123"}]

callback (Function)
A callback function that is executed when the request is completed It is called with a response object as parameter

The response object contains the following fields:

success (Boolean)
true if the action was successful, otherwise false

error (String)
A string containing an error message if the action was not successful

Return Value

None

Sample Code

Visualforce:

var flowDevName = "sample_flow";
var flowArgs = [{name: "phoneVariable", type: "String", value: "123"}];
ConnectsIntegrationAPI.screenPopToFlow(flowDevName, flowArgs, function (response) {
    if (!response.success) {
        ConnectsIntegrationAPI.showError("USER", "screenPopToFlow failed", response.error);
    }
});

Lightning Aura/Web Component:

var flowDevName = "sample_flow";
var flowArgs = [{name: "phoneVariable", type: "String", value: "123"}];
cnxIntegrationAPI.screenPopToFlow(flowDevName, flowArgs, function (response) {
    if (!response.success) {
        cnxIntegrationAPI.showError("USER", "screenPopToFlow failed", response.error);
    }
});

getReasonCodeList(reasonType, callback)

This is a helper function.

It returns the list of reason codes for the given reason type (not ready reasons, Wrap-Up reasons or logout reasons).

Argument(s)

reasonType (REASON.TYPE)
Can be NOTREADY, WRAPUP, or LOGOUT

callback (Function)
A callback function that is executed when the request is completed It is called with a response object as parameter

The response object contains the following fields:

success (Boolean)
true if the action was successful, otherwise false

data (String)
A JSON encoded string containing an array of reason codes (See section reasonCodeList Structure for a detailed description of the reasonCodeList data)

error (String)
A string containing an error message if the action was not successful

Return Value

None

Sample Code

Visualforce:

var reasonType = ConnectsIntegrationAPI.REASON.TYPE.NOTREADY;
ConnectsIntegrationAPI.getReasonCodeList (reasonType, function (response) {
    if (!response.success) {
        ConnectsIntegrationAPI.showError("USER", "getReasonCodeList failed", response.error);
    }
});

Lightning Aura/Web Component:

var reasonType = cnxIntegrationAPI.REASON.TYPE.NOTREADY;
cnxIntegrationAPI.getReasonCodeList (reasonType, function (response) {
    if (!response.success) {
        cnxIntegrationAPI.showError("USER", "getReasonCodeList failed", response.error);
    }
});

info

Be aware that the reason code list will be empty if the agent is not logged in. It is recommended to wait for the onAgentStateEvent that signals the logged in agent state before executing getReasonCodeList.

Shared Data Structures

Some data structures are used in several Connects Integration API calls. Here it is possible to find the specification of these generic data structures.

Finesse Version Structure

This item concerns Finesse version information. It contains the major, minor, patch, build and cop versions.

An object of this structure is returned by the function getFinesseVersion()

{
    "major": 0,
    "minor": 0,
    "patch": 0,
    "build": 0,
    "cop": 0
};

WorkItem Structure

The item represents information about the call or task related to the Connects Integration API call.

This is a sample of what a work item object looks like:

{
    "Id": "17482876",   //Call id or Task
    "SecondaryId": "17482876",          //Secondary call id
    "UniqueId": "VOICE.17482876.1413791998330.005U0000000i9UbIAI", //Unique id of the task
    "CrmId": "00TU0000019xdg9",         //Id of an activity record for the current workitem
    "CrmData":                          //Data from Salesforce linked to this workitem
        {
            "RelatedObject": "",        //Salesforce Click to Dial data
            "SearchResult":             //Salesforce search result data
                {
                    "errors": null,     //If the API call was successful, this variable is
                                        //null. If the API call failed, this variable returns
                                        //an array of error
                    "returnValue":
                         {
                             "003U000001If40e":
                                 {
                                     "Name": "John Doe",
                                     "displayName": "Contact",
                                     "object": "Contact",
                                     "Title": "",
                                     "Department": ""
                                 }
                         },
                    "success": true     //Returns true if the API function call was invoked
                                        //successfully, false otherwise.
                }
        }
    "AgentId": "52370",                 //Agent id
    "State": "ACTIVE",                  //Current State (OFFERED, ACTIVE, WRAPUP, PAUSED)
    "Service": "",                      //Service
    "DNIS": "333300",                   //DNIS of the Call
    "DialedNumber": "333300",           //Dialed Number of the Call
    "Sender": "41319175200",            //Sender of the Call or Task
    "Subject": "",                      //Subject of a Ticket or Chat
    "Destination": "333300",            //Destination of the Call or Task
    "Direction": "inbound",             //Item Direction (inbound or outbound)
    "Channel": "VOICE",                 //Channel Type (VOICE, TICKET, CHAT)
    "CorrelationData": "",              //Media URL passed in RouteRequest
    "SelectedWrapupReason": "",         //Currently set Wrap-Up reason of the Call
    "MediaWrapUpReason": "",            //Wrap-Up reason of a Media Item when it is closed
    "CallType": "OTHER_IN",             //Cisco Finesse Call Type of the Call
    "IsInternalCall": false,            //Boolean value if call is declared as internal
    "PerVar1": "",                      //Peripheral Variable 1 attached to Call/Task
    "PerVar2": "",                      //Peripheral Variable 2 attached to Call/Task
    "PerVar3": "",                      //Peripheral Variable 3 attached to Call/Task
    "PerVar4": "",                      //Peripheral Variable 4 attached to Call/Task
    "PerVar5": "",                      //Peripheral Variable 5 attached to Call/Task
    "PerVar6": "",                      //Peripheral Variable 6 attached to Call/Task
    "PerVar7": "",                      //Peripheral Variable 7 attached to Call/Task
    "PerVar8": "",                      //Peripheral Variable 8 attached to Call/Task
    "PerVar9": "",                      //Peripheral Variable 9 attached to Call/Task
    "PerVar10": "",                     //Peripheral Variable 10 attached to Call/Task
    "NamedVariables": [                 //Array of ECC variables
        {
            "Key": "user.Var1",
            "Value": "{k:MyTitle;v:Sample-Value}"
        },
        {
            "Key": "user.SpecialField",
            "Value": "Sample Content"
        }
    ],
    "LocalVariables": [                 //Array of local Variables
        {
            "Key": "MyVariableName",
            "Value": "Sample Content"
        },
        {
            "Key": "MyOtherVariableName",
            "Value": "{k:MyLocalVarTitle;v:Sample-Value}"
        }
    ],
    "CreatedTimeStamp": 1410357491231,      //in ms since midnight, January 1, 1970
    "ConnectedTimeStamp": 1410357491231,    //in ms since midnight, January 1, 1970
    "WrapedupTimeStamp": 1410357491231,     //in ms since midnight, January 1, 1970
    "EndedTimeStamp": 1410357491231,        //in ms since midnight, January 1, 1970
    "TimeZoneOffset": -120,                 //Timezone offset in minutes for timestamps
    "Participants": [                       //Call Participants, not used for tasks
        {
            "MediaAddress": "41319175200",
            "State": "ACTIVE",
            "StateCause": ""
        }
    ],
    "QueueName": "MyQueue",                 //Name of the queue
    "QueueNumber": "12345",                 //Id of the Queue Name
    "CallKeyCallId": "343548",              //Unique number for the call routed on that day
    "CallKeyPrefix": "45684",               //Day when the call was routed
    "CallKeySequenceNum": "12345"           //Call sequence number
}

itemVarObject Structure

The itemVarObject contains peripheral variables, ECC variables, local variables and the WrapUpReason and is used, for example, in the request to update call variables in CCE/CCX.

tip

All fields are optional. Only fields that should change must be contained in the object.

{
    "PerVar1": "",  //Peripheral Vars. attached to Call
    "PerVar2": "",
    "PerVar3": "",
    "PerVar4": "",
    "PerVar5": "",
    "PerVar6": "",
    "PerVar7": "",
    "PerVar8": "",
    "PerVar9": "",
    "PerVar10": "",
    "NamedVariables": [ //Array of ECC variables
        {
            "Key": "user.Var1",
            "Value": "{k:MyTitle;v:Sample-Value}"
        },
        {
            "Key": "user.SpecialField",
            "Value": "Sample Content"
        }
    ],
    "LocalVariables": [ //Array of local Variables
        {
            "Key": "MyVariableName",
            "Value": "Sample Content"
        },
        {
            "Key": "MyOtherVariableName",
            "Value": "{k:MyLocalVarTitle;v:Sample-Value}"
        }
    ],
    "WrapUpReason": "Service Issue"
}

relatedObject Structure

The relatedObject contains information about a 'Click-to- -Dial' event.

{
    "recipientType": "Account",
    "recipientId": "0011j00001HRryWAAT",
    "recipientName": "Test Account",
    "number":"342115"
}

ctiDataObject Structure

The ctiDataObject contains information about the agent, its state in each channel and the items (calls or tasks) in each channel.

An object of this structure is returned by the function GetCtiData().

{
    "Agent": "52270",   //Agent-Id
    "Extension": "333050",  //Extension where agent is logged in
    "Supervisor": false,    //Is the agent a supervisor or not?
    "MobileAgent": false,   //Is the agent logged in as mobile agent or not?
    "MobileMode": "",   //The mobile agent mode, CALL_BY_CALL or NAILED
    "MobileNumber": "", //The external phone number of mobile agent
    "FirstName": "John",    //The first name of agent as configured in UCCE
    "LastName": "Doe",  //The last name of agent as configured in UCCE
    "LoginName": "",    //The login name of agent
    "TeamId": "1",  //The id of the team where the agent belongs to in UCCE
    "TeamName": "Default",  //The name of the team where the agent belongs to in UCCE
    "Channels": [   //Array of channels, currently VOICE and/or TICKET, CHAT
        {
            "Name": "VOICE",    //Name of the channel
            "State": "TALKING", //Agent state in this channel
            "ReasonCode": 0,    //e.g. selected Not-Ready reason code
            "ReasonCodeLabel": "",  //label for selected Not-Ready reason code
            "StateChangeTime": "2016-08-18T16:53:43.417+00:00", //Time the agent changed to state
            "Items": [  //Array of items (calls or tasks)
                {
                    "Id": "16850634",
                    "UniqueId": "VOICE.16850634.1413791998330.005U0000000i9UbIAI",
                    "AgentId": "52270",
                    "State": "PAUSED",
                    ...
                },
                {
                    "Id": "16850635",
                    "UniqueId": "VOICE. 16850635.1413792801738.005U0000000i9UbIAI",
                    "AgentId": "52270",
                    "State": "ACTIVE",
                    ...
                }
        },
        {
            "Name": "TICKET",   //Name of the channel
            "State": "ACTIVE",  //Agent state in this channel
            "ReasonCode": 0,    //e.g. selected Not-Ready reason code
            "ReasonCodeLabel": "",  //label for selected Not-Ready reason code
            "StateChangeTime": "2016-08-18T16:53:43.417+00:00", //Time the agent changed to state
            "Items": [  //Array of items (calls or tasks)
                {
                    "Id": "10001",
                    "AgentId": "52270",
                    "State": "PAUSED",
                    ...
                },
                {
                    "Id": "10002",
                    "AgentId": "52270",
                    "State": "ACTIVE",
                    ...
                }
        }
    ]
}

realTimeAgentObject Structure

The realTimeAgentObject in onTeamDataUpdate event contains information about the agent and his state in each channel.

Currently it only contains the channel VOICE.

The structure of the realTimeAgentObject is similar to the ctiDataObject, but contains less data.

The event onTeamDataUpdate sends an array of these realTimeAgentObjects.

{
    "Agent": "52270",   //Agent-Id
    "Extension": "333050",  //Extension where agent is logged in
    "FirstName": "John",    //The first name of agent as configured in UCCE
    "LastName": "Doe",  //The last name of agent as configured in UCCE
    "Channels": [   //Array of channels, currently only VOICE
        {
            "Name": "VOICE",    //Name of the channel
            "State": "NOTREADY",    //Agent state in this channel
            "StateChangeTime": 548, //Time since last channel state change (in seconds)
            "ReasonCode": 2,    //e.g. selected Not-Ready reason code
            "ReasonName": "Meeting",    //e.g. selected Not-Ready reason name
            "TalkingStateDetail": "HOLD"    //more detailed information about the talking state,
    //this can be "TALKING", "RESERVED",
    //"RESERVED_OUTBOUND", "RESERVED_OUTBOUND_PREVIEW" or
    //"HOLD". If the channel is not in the state
    //"TALKING", this property is null,
        }
    ]
}

realTimeQueueObject Structure

The realTimeQueueObject in onQueueDataUpdate event contains information about the queue and its statistics.

The event onQueueDataUpdate sends an array of these queueObjects.

{
  "Channel": "VOICE",   //currently only VOICE
  "Name": "Internal Helpdesk",  //Name of the queue / skill group
  "Id": 5,  //Peripheral id of the skill group
  "Statistics": {   //Container for statistic values
      "CallsInQueue": 0,    //Number of calls in queue
      "StartTimeOfLongestCallInQueue": null,    //Format: YYYY-MM-DDThh:MM:ssZ
      "AgentsReady": 3,     //Number of agents in READY state
      "AgentsNotReady": 10,     //Number of agents in NOT_READY state
      "AgentsBusyOther": 5, //Number of agents in another BUSY state
      "AgentsTalkingInbound": 4,    //Number of agents in TALKING state on inbound calls
      "AgentsTalkingInternal": 2,   //Number of agents in TALKING state on internal calls
      "AgentsTalkingOutbound": 3,   //Number of agents in TALKING state on outbound calls
      "AgentsWrapupNotReady": 1,    //Number of agents in WORK state
      "AgentsWrapupReady": 1,   //Number of agents in WORK_READY state
  }
}

reasonCodeList Structure

The reasonCodeList contains information about NOT_READY, LOGOUT and WRAPUP reasons.

A request for the NOT_READY reasons returns a JSON encoded array with zero or more instances of the following reasonCode object:

{
  "Label": "Away from Desk",    //Label of the Reason Code shown to the Agent
  "ReasonCode": "1",    //Reason code of the NotReady reason
  "Id": "15"    //Finesse API id of the NotReady reason
}

A request for the LOGOUT reasons returns a JSON encoded array with zero or more instances of the following reasonCode object:

{
  "Label": "Left for the day",  //Label of the Reason Code shown to the Agent
  "ReasonCode": "1000", //Reason code of the NotReady reason
  "Id": "1" //Finesse API id of the NotReady reason
}

A request for the WRAPUP reasons returns a JSON encoded array with zero or more instances of the following reasonCode object:

{
  "Label": "Documentation", //Label of the Reason Code shown to the Agent
  "ReasonCode": "9", *
  "Id": "9" //Finesse API id of the Wrap-Up reason
}

* This field is set to the Finesse API id of the Wrap-Up reason to make the structure match with the one from the NotReady and Logout reasons.

TeamMessages Structure

This is the structure of a response object for team message requests.

Note that these are returned as an array.

[
  {
    "uri":"/finesse/api/TeamMessage/3dd59687-e787-4c96-9018-41c4520d982f",
    "id":"3dd59687-e787-4c96-9018-41c4520d982f",
    "createdBy":{
       "id":"112234",
       "firstName":"John",
       "lastName":"Doe"
    },
    "createdAt":"1588339098",
    "duration":"600",
    "content":"Test API",
    "teams":{
      "team":"5041"
    }
  }
]

Utterance Structure

This is the structure of the utterance object returned as a property of the onTranscriptUtteranceReceived event.

{
    "role": "Agent",
    "workItemId": "24142550",
    "transcript": "hello, how may i help you",
    "confidence": 0.9563773572444916,
    "startTimestamp": 1638276556188,
    "endTimestamp": 1638276586188
}

Agent Answers Structure

This is the structure of the agentAnswers object returned as a property of the onAgentAnswersReceived event.

[
    {
      "workItemId": "1234567",
      "title": "What happens if my flight is cancelled?",
      "description": "You have the option of rebooking on another flight or taking a refund if you choose not to travel.",
      "answerRecord": "projects/acme-v2/answerRecords/3bb4bb8f388d0509",
      "confidence": 0.961065411567688,
      "source": "projects/acme-v2/knowledgeBases/MTUxMzk5NzM4NDgyODk1MDkzNzY/documents/OTg0MTI5NDI3MzEzMDAwNDQ4MA",
      "uri": "",
      "snippetsList": []
    },
    ...
]

Integration API Sample

The section features Connects Integration API sample code usage in the different supported environments

Basic Event and Request Sample Code

This sample code will show how to integrate the Connects Integration API and handle one event as well as send a "go ready" and a "go not ready" request in the different supported modes.

Visualforce Page Code for Classic and Custom Toolbar

<apex:page showHeader="false" docType="html-5.0">
    <apex:includeScript value="{!URLFOR($Resource.cnx__CnxSfdcResources,'js/ConnectsIntegrationAPI.min.js')}"/>

    <p>WaitReady Test</p>
    <div>
        <button id="setReadyButton">Ready</button>
        <button id="setNotReadyButton">Not Ready</button>
    </div>

    <p>WaitReady Result:</p>
    <p id="waitReadyMessage">...</p>
    <p>onAgentStateChange-Events:</p>
    <p id="agentStateEventMessage">...</p>

    <script>
        ConnectsIntegrationAPI.waitReady(function () {
            ConnectsIntegrationAPI.writeLogDebug('Connects Integration API Successfully loaded from' +
                ' Lightning Aura Component.');
            document.getElementById('waitReadyMessage').innerText = 'WaitReady callback was triggered';
            ConnectsIntegrationAPI.onAgentStateChange = function (event) {
                ConnectsIntegrationAPI.writeLogDebug('New state in channel \'' + event.channelType + '\': ' +
                    event.newState.State + ' (' + event.newState.ReasonCode + ')');
                document.getElementById('agentStateEventMessage').innerText = JSON.stringify(event, null, 4);
            };
            document.getElementById('setReadyButton').onclick = doChangeReady;
            document.getElementById('setNotReadyButton').onclick = doChangeNotReady;
        });

        function doChangeReady (component, event, helper) {
            var channelTypeVoice = ConnectsIntegrationAPI.CHANNEL.TYPE.VOICE;
            var channelStateReady = ConnectsIntegrationAPI.CHANNEL.STATE.READY;
            ConnectsIntegrationAPI.setAgentState(channelTypeVoice, channelStateReady, 0, function (response) {
                if (!response.success) {
                    ConnectsIntegrationAPI.showError('USER', 'setAgentState failed', response.error);
                }
            });
        }

        function doChangeNotReady (component, event, helper) {
            var channelTypeVoice = ConnectsIntegrationAPI.CHANNEL.TYPE.VOICE;
            var channelStateNotReady = ConnectsIntegrationAPI.CHANNEL.STATE.NOT_READY;
            // change this to any of your not ready reason code ids
            var notReadyReasonCodeId = '0';
            ConnectsIntegrationAPI.setAgentState(channelTypeVoice, channelStateNotReady, notReadyReasonCodeId,
                function (response) {
                    if (!response.success) {
                        ConnectsIntegrationAPI.showError('USER', 'setAgentState failed', response.error);
                    }
                }
            );
        }
    </script>
</apex:page>

Visualforce Page Code for Utility Item and Lightning Apps

<apex:page showHeader="false" docType="html-5.0">
    <apex:includeScript value="{!URLFOR($Resource.cnx__CnxSfdcResources,'js/ConnectsIntegrationAPI.min.js')}"/>
    <script>
        var messageChannel = "{!$MessageChannel.cnx__ConnectsIntegrationAPI__c}";
        ConnectsIntegrationAPI.setLMSEnvironment({
            mode: 'Visualforce',
            channel: messageChannel
        });
    </script>

    <p>WaitReady Test</p>
    <div>
        <button id="setReadyButton">Ready</button>
        <button id="setNotReadyButton">Not Ready</button>
    </div>

    <p>WaitReady Result:</p>
    <p id="waitReadyMessage">...</p>
    <p>onAgentStateChange-Events:</p>
    <p id="agentStateEventMessage">...</p>

    <script>
        ConnectsIntegrationAPI.waitReady(function () {
            ConnectsIntegrationAPI.writeLogDebug('Connects Integration API Successfully loaded from' +
                ' Lightning Aura Component.');
            document.getElementById('waitReadyMessage').innerText = 'WaitReady callback was triggered';
            ConnectsIntegrationAPI.onAgentStateChange = function (event) {
                ConnectsIntegrationAPI.writeLogDebug('New state in channel \'' + event.channelType + '\': ' +
                    event.newState.State + ' (' + event.newState.ReasonCode + ')');
                document.getElementById('agentStateEventMessage').innerText = JSON.stringify(event, null, 4);
            };
            document.getElementById('setReadyButton').onclick = doChangeReady;
            document.getElementById('setNotReadyButton').onclick = doChangeNotReady;
        });

        function doChangeReady (component, event, helper) {
            var channelTypeVoice = ConnectsIntegrationAPI.CHANNEL.TYPE.VOICE;
            var channelStateReady = ConnectsIntegrationAPI.CHANNEL.STATE.READY;
            ConnectsIntegrationAPI.setAgentState(channelTypeVoice, channelStateReady, 0, function (response) {
                if (!response.success) {
                    ConnectsIntegrationAPI.showError('USER', 'setAgentState failed', response.error);
                }
            });
        }

        function doChangeNotReady (component, event, helper) {
            var channelTypeVoice = ConnectsIntegrationAPI.CHANNEL.TYPE.VOICE;
            var channelStateNotReady = ConnectsIntegrationAPI.CHANNEL.STATE.NOT_READY;
            // change this to any of your not ready reason code ids
            var notReadyReasonCodeId = '0';
            ConnectsIntegrationAPI.setAgentState(channelTypeVoice, channelStateNotReady, notReadyReasonCodeId,
                function (response) {
                    if (!response.success) {
                        ConnectsIntegrationAPI.showError('USER', 'setAgentState failed', response.error);
                    }
                }
            );
        }
    </script>
</apex:page>

Aura Component Code for Lightning Apps

Component

<aura:component implements="flexipage:availableForAllPageTypes" access="global">
    <cnx:ConnectsIntegrationAPI aura:id="cnxIntegrationAPI"/>
    <aura:handler name="waitReady" event="cnx:ConnectsIntegrationAPIEvent" action="{!c.waitReady}"/>
    <aura:attribute name="cnxIntegrationAPI" type="Object" default="null" />
    <aura:attribute name="waitReadyMessage" type="String" default="..."/>
    <aura:attribute name="agentStateEventMessage" type="String" default="..."/>

    <p>WaitReady Test</p>
    <div>
        <lightning:button label="Ready" onclick="{!c.doChangeReady}"/>
        <lightning:button label="Not Ready" onclick="{!c.doChangeNotReady}"/>
    </div>

    <p>WaitReady Result:</p>
    <p>{!v.waitReadyMessage}</p>
    <p>onAgentStateChange-Events:</p>
    <p>{!v.agentStateEventMessage}</p>
</aura:component>

Controller

({
    waitReady: function (component, event, helper) {
        var cnxIntegrationAPI = component.find('cnxIntegrationAPI').get('v.noConflictConnectsIntegrationAPI');
        cnxIntegrationAPI.writeLogDebug('Connects Integration API Successfully loaded from' +
            ' Lightning Aura Component.');
        component.set('v.waitReadyMessage', 'WaitReady callback was triggered');
        component.set('v.cnxIntegrationAPI', cnxIntegrationAPI);
        cnxIntegrationAPI.onAgentStateChange = function (event) {
            cnxIntegrationAPI.writeLogDebug('New state in channel \'' + event.channelType + '\': ' +
                event.newState.State + ' (' + event.newState.ReasonCode + ')');
            component.set('v.agentStateEventMessage', JSON.stringify(event,null,4));
        };
    },

    doChangeReady: function (component, event, helper) {
        var cnxIntegrationAPI = component.get('v.cnxIntegrationAPI');
        if (cnxIntegrationAPI === null) {
            console.error('setAgentState can not be performed as the API is not ready/retrieved yet');
            return
        }

        var channelTypeVoice = cnxIntegrationAPI.CHANNEL.TYPE.VOICE;
        var channelStateReady = cnxIntegrationAPI.CHANNEL.STATE.READY;
        cnxIntegrationAPI.setAgentState(channelTypeVoice, channelStateReady, 0,
            function (response) {
                if (!response.success) {
                    cnxIntegrationAPI.showError('USER', 'setAgentState failed', response.error);
                }
            }
        );
    },

    doChangeNotReady: function (component, event, helper) {
        var cnxIntegrationAPI = component.get('v.cnxIntegrationAPI');
        if (cnxIntegrationAPI === null) {
            console.error('setAgentState can not be performed as the API is not ready/retrieved yet');
            return
        }

        var channelTypeVoice = cnxIntegrationAPI.CHANNEL.TYPE.VOICE;
        var channelStateNotReady = cnxIntegrationAPI.CHANNEL.STATE.NOT_READY;
        // change this to any of your not ready reason code ids
        var notReadyReasonCodeId = '0';
        cnxIntegrationAPI.setAgentState(channelTypeVoice, channelStateNotReady,
            notReadyReasonCodeId,
            function (response) {
                if (!response.success) {
                    cnxIntegrationAPI.showError('USER', 'setAgentState failed', response.error);
                }
            }
        );
    }
})

Example Code for Lightning Web Components

Service Component (required)

File name: connectsIntegrationApiSvc.js

import CNX_RESOURCE_LINK from '@salesforce/resourceUrl/cnx__CnxSfdcResources';
import { loadScript } from 'lightning/platformResourceLoader';
import { subscribe, publish, APPLICATION_SCOPE, createMessageContext } from 'lightning/messageService';
import cnxmc from '@salesforce/messageChannel/cnx__ConnectsIntegrationAPI__c';

export default function getIntegrationApi(lwc, cb) {
    Promise.all([
        // Load Integration API from static resource
        loadScript(lwc, CNX_RESOURCE_LINK + '/js/ConnectsIntegrationAPI.min.js')
    ])
        .then(() => {
            const messageContext = createMessageContext();
            const iAPIInstance = ConnectsIntegrationAPI.noConflict();
            iAPIInstance.setLMSEnvironment({
                mode: 'LWC',
                publishMethod: function (message) {
                    publish(messageContext, cnxmc, message);
                },
                subscribeMethod: function (handler) {
                    subscribe(messageContext, cnxmc, handler, { scope: APPLICATION_SCOPE });
                }
            });
            // Return the Integration API object when it is ready
            iAPIInstance.waitReady(() => {
                return cb(iAPIInstance);
            });
        })
        .catch(error => {
            cb(null, error);
        });
}

File name: connectsIntegrationApiSvc.js-meta.xml

<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>60.0</apiVersion>
    <description>Connects Integration Api Service</description>
    <masterLabel>Connects Integration Api Service</masterLabel>
    <isExposed>false</isExposed>
</LightningComponentBundle>

Custom Lightning Web Component Template

File name: yourLWCname.js

import {LightningElement} from 'lwc';
import getIntegrationApi from 'c/connectsIntegrationApiSvc';

export default class TestLWCCustomer extends LightningElement {

    // Connects Integration API object
    cnxIntegrationAPI;

    connectedCallback() {
        let _this = this;
        // Retrieve Connects Integration API object
        // First parameter "this" must be a valid LWC (must extend LightningElement)
        // Second parameter is the callback, it will run when the API is initialized
        // (substitutes the waitReady() request)
        getIntegrationApi(this, function(el, err) {
            if(el !== null) {
                _this.cnxIntegrationAPI = el;
                _this.run();
            } else {
                // An error occurred: the static resource may not exist or the library is not readable
                console.log(err);
            }
        });
    }

    run() {
        // Custom code can be inserted here
        // Use the following listeners template to run code on the required events
        // More events can be found at the following url:
        // https://docs.bucher-suter.com./
        //      forDevelopersIntegrationAPIDeveloperGuide.html#events-gadget-custom-component
        // Additional requests can be found at the following url:
        // https://docs.bucher-suter.com./
        //      forDevelopersIntegrationAPIDeveloperGuide.html#requests-custom-component-gadget

        this.cnxIntegrationAPI.onWorkItemCreate = event => {
            if (event.item.Channel === 'VOICE') {
                console.log('onWorkItemCreate');
                // Insert your code here
            }
        };

        this.cnxIntegrationAPI.onWorkItemConnect = event => {
            if (event.item.Channel === "VOICE") {
                console.log('onWorkItemConnect');
                // Insert your code here
            }
        };

        this.cnxIntegrationAPI.onAgentStateChange = event => {
            if (event.channelType === 'VOICE') {
                console.log('onAgentStateChange');
                // Insert your code here
            }
        };

        let ctiData = this.cnxIntegrationAPI.getCtiData();
        console.log('getCtiData', ctiData);
    }
}

File name: yourLWCname.js-meta.xml

<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>60.0</apiVersion>
    <description>Your LWC name</description>
    <masterLabel>Your LWC name</masterLabel>
    <isExposed>true</isExposed>
    <targets>
        <target>lightning__AppPage</target>
        <target>lightning__RecordPage</target>
        <target>lightning__HomePage</target>
    </targets>
</LightningComponentBundle>

File name: yourLWCname.html

<template>
    <lightning-card title="Customer LWC" icon-name="custom:custom14">
        <div class="slds-m-around_medium">
            <p>Your LWC name</p>
        </div>
    </lightning-card>
</template>

Including the Sample Integration in Salesforce

This section contains instructions on how to add the Visualforce Page or Lightning Aura Component from the Basic Event and Request Sample Code section into your Salesforce user interface.

Custom Toolbar

Create a new Visualforce Page with the following data:

Label: b+s Integration Sample

Name: bsIntegrationSample

Enable the checkbox "Available for Lightning Experience, Lightning Communities, and the mobile app"

Paste the Visualforce Page Code inside the Visualforce Markup of the newly created Visualforce Page.

Click the Save button

Click the Preview button and copy the URL of the Visualforce Page from the newly opened tab after it is fully loaded.

Load the b+s Configurations App and create a new configuration or edit a previously created one.

In the Custom Toolbars section, create a new Toolbar with the following data:

Location: Top Toolbar

URL: The previously copied URL from the Visualforce Page

Height: 200

App Navigation Item

In the Setup Page go to User Interface | Lightning App Builder | New | App Page

Label: b+s Integration Sample

Select One Region and click Finish.

At this point you can choose to add the Visualforce Page or Lightning Aura Component as part of the page. In order to do it, just drag and drop the selected option to the desired page region.

Click Save and Activate. From this point, you can add it to the desired App as a new Navigation Item.

Click on the dropdown arrow (1) | Edit (2) | Add More Items | Select the b+s Wait Ready Sample and Save.

Utility Item

In the Setup Page go to Apps | App Manager then edit the Lightning App you want the Navigation Item to be included in or create a new one. Then go to Utility Items.

Click Add Utility Item

At this point you can choose to add the Utility Item as a Visualforce Page or as a Lightning Aura Component.

caution

The Background Utility Item mode is not supported.

Using Salesforce Interaction Log

b+s Connects for Salesforce also supports using the Salesforce Interaction Logs.

Using Salesforce Interaction Log

When a call is active, it can be added into the Interaction Log form. When the call (and optional call Wrap-Up) ends, the interaction is automatically saved and the Call Duration field updated.

Administrators can customize the interaction log form to contain additional task fields.

To automatically add additional CTI information into the interaction log form, replace this form with custom code to copy specific data from the call into the form.

In a custom Interaction Log it is possible to use the following events and functions from the SFDC Console Integration Toolkit Developers Guide:

• onCallBegin() fired when a call is answered
• onCallEnd() fired when a call (and optional call Wrap-Up) is ended
• getCallObjectIds()
• getCallAttachedData() returns item data.

Instead of, or in addition to, these Salesforce events and functions it is also possible to use all other events and functions defined in this document for custom Interaction Log forms.

Here is a list of some links with additional information about Salesforce Interaction Logs:

• Add Notes to Records in a Salesforce Console (using Interaction Logs): https://help.salesforce.com/HTViewHelpDoc?id=console2_using_log.htm&language=en_US
• Turn on Interaction Logs: https://help.salesforce.com/HTViewHelpDoc?id=console2_log_on.htm&language=en_US
• Set Up Interaction Logs for a Salesforce Console: https://help.salesforce.com/HTViewHelpDoc?id=console2_setup_log.htm&language=en_US
• Building a Custom Interaction Log: https://help.salesforce.com/s/articleView?id=sf.console2_setup_log.htm&type=5

Troubleshooting

For Troubleshooting please refer to the Troubleshooting section