Overview

Scope

The Integration API allows customers to extend the default functionality of b+s Connects.

b+s Connects dispatches events on CTI related changes, so that integrators can run custom code to cover customer specific requirements. The events and requests described on this page are available for different environments. Please note the following list for availability.

Supported environments:

• Initiate requests from within a Microsoft Dynamics page to b+s Connects (no consumption of events) (referred to as Custom Requests)
• Place custom code within b+s Connects (referred to as Custom Integration)

Prerequisites

Regardless of the environment for which you want to do an integration, you must have experience working with Microsoft Dynamics 365 (configuring, customizing and developing), as well as knowing how to write code and working with JSON.

How to pick the right integration type

There are 2 ways to integrate with b+s Connects. This chapter tries to help you pick the right type of integration by describing main usages. Each integration type differs in terms of available events and requests (note availability list for each event/request).

• Simple instruction(s) from within the CRM to b+s Connects. No events required to react upon: → Custom Requests

• Custom user interface hosted within b+s Connects. React to events and issue requests: → Custom Integration

Events

agentStateChange

Available for: Custom Integration

This event is raised when the state of an agent for a specific channel changes.

Field	Description
event	Event name "agentStateChange"
version	API version
requestId	Identifier to match this event to a request
channelType	Channel type (Voice, Mail, Chat, Task, Federation)
channelId	Channel identifier (voice_<peripheral_id>) For CCX: voice_-1 For WxCC: telephony
newState	New state (Logout, Offline, Ready, NotReady, Active, Wrapup, Unknown)
newReasonCode	New reason code. Negative values indicate no code available.
newReasonCodeLabel	New reason name
newStateChangeTime	New state change time
oldState	Previous state: (Logout, Offline, Ready, NotReady, Active, Wrapup, Unknown)
oldReasonCode	Previously selected reason code. Negative values indicate no code available.
oldReasonCodeLabel	Previously selected reason name
oldStateChangeTime	Previous change state time

Sample code for custom integrations

cil.onAgentStateChange((data) => {
  console.warn(`message: onAgentStateChange, data: ${JSON.stringify(data)}`);
});

beforeDial

Available for: Custom Integration

This event is raised before a call is initiated.

Subscribing to this event blocks outgoing calls that are not initiated by a custom integration. If you want the number to be dialed, you need to start a call by using dialOrConsult.

Consultation and transfer calls are not affected and do not dispatch the event.

Field	Description
event	Event name "beforeDial"
version	API version
requestId	Identifier to match this event to a request.
dialedNumber	The number to be dialed.
callType	Call type (Outbound)

Sample code for custom integrations

cil.onBeforeDial((data) => {
  console.warn(`message: onBeforeDial, data: ${JSON.stringify(data)}`);
});

info

Loading a custom integration as hidden is recommended if the beforeDial event is used, to avoid it being unloaded.

error

Available for: Custom Integration

This event is raised when an Integration API request fails or an error is encountered in b+s Connects.

Field	Description
event	Event name "error"
version	API version
requestId	Identifier of the request that might have caused the error, empty if the source of the error cannot be detected.
message	Short message describing the encountered error

Sample code for custom integrations

cil.onError((error) => {
  console.warn(`message: onError data: ${JSON.stringify(error)}`);
});

workitemConnect

Available for: Custom Integration

This event is raised when a work item is accepted.

Please see workitem reference for available data and format.

Sample code for custom integrations

cil.onWorkitemConnect((data) => {
  console.warn(`message: onWorkitemConnect, data: ${JSON.stringify(data)}`);
});

workitemCreate

Available for: Custom Integration

This event is raised when a new work item (e.g. phone call) appears in b+s Connects and is alerting. WorkitemCreate is also dispatched, when the agent logs in while a call is on the phone (call recovery).

Please see workitem reference for available data and format.

Sample code for custom integrations

cil.onWorkitemCreate((data) => {
  console.warn(`message: onWorkitemCreate, data: ${JSON.stringify(data)}`);
});

workitemEnd

Available for: Custom Integration

This event is raised when a work item disappears from b+s Connects. If Wrap-Up is enabled, this event is sent when Wrap-Up for the item ends. If Wrap-Up is not enabled, the event is sent immediately after hang-up/end.

Please see workitem reference for available data and format.

Sample code for custom integrations

cil.onWorkitemEnd((data) => {
  console.warn(`message: onWorkitemEnd, data: ${JSON.stringify(data)}`);
});

workitemPause

Available for: Custom Integration

This event is raised when a work item is paused (e.g a call is put on hold).

Please see workitem reference for available data and format.

Sample code for custom integrations

cil.onWorkitemPause((data) => {
  console.warn(`message: onWorkitemPause, data: ${JSON.stringify(data)}`);
});

workitemResume

Available for: Custom Integration

This event is raised when a paused work item is resumed.

Please see workitem reference for available data and format.

Sample code for custom integrations

cil.onWorkitemResume((data) => {
  console.warn(`message: onWorkitemResume, data: ${JSON.stringify(data)}`);
});

workItemWrapup

Available for: Custom Integration

This event is raised when a work item changes the state to Wrap-Up.

Please see workitem reference for available data and format.

Sample code for custom integrations

cil.onWorkitemWrapup((data) => {
  console.warn(`message: onWorkitemWrapup, data: ${JSON.stringify(data)}`);
});

Requests

createSession

Available for: Custom Requests Custom Integration

This request creates a new session based on the given session template name and parameters.

Field	Description
request	Request name "createSession"
templateName	Name of the Session Template
templateParameters	Template parameters object which should be passed to the CIF createSession call (optional)

Return Value

Returns a promise which has no value.

Sample code for custom integrations

await cil.createSession(templateName, templateParameter);

For more information on Session Templates please refer to Manage session templates in Dynamics 365.

dialOrConsult

Available for: Custom Integration

This request initiates a new call. A consultation call is created when the agent already has a call.

Field	Description
channelId	voice for the voice channel (without having to provide the peripheral ID), voice_<peripheral_id> for a specific voice channel, voice_-1 for CCX voice channel, telephony for WxCC voice channel. Make sure the channel is uniquely identified by this id.
address	Destination address
requestId	Identifier to map an event/error to the request (optional)

Return Value

Returns a promise which has no value.
If successful, an "onWorkitemCreate" event will be raised.
If the request fails, an “error” event will be dispatched.

Sample code for custom integrations

await cil.dialOrConsult('voice', phonenumber, requestId);

getChannel

Available for: Custom Integration

This request returns information about the specified channel.

Field	Description
channelId	voice for the voice channel (without having to provide the peripheral ID), voice_<peripheral_id> for a specific voice channel, voice_-1 for CCX voice channel, telephony for WxCC voice channel, Make sure the channel is uniquely identified by this id.

Return Value

Returns a promise which resolves to a getChannel object.
Please see getChannel reference for available data and format.

Sample code for custom integrations

const result = await cil.getChannel('voice');

getCustomSettings

Available for: Custom Integration

This request returns the configured integration settings.

Return Value

Returns a promise which resolves to an array containing key/value pairs.

Field	Description
Key	setting1-5
Value	Configured value

Sample code for custom integrations

const result = await cil.getCustomSettings();

getReasonCodeList

Available for: Custom Integration

This action can be called to retrieve a list of reason codes for a specified reasonType.

Field	Description
channelId	voice for the voice channel (without having to provide the peripheral ID), voice_<peripheral_id> for a specific voice channel, voice_-1 for CCX voice channel, telephony for WxCC voice channel. Make sure the channel is uniquely identified by this id.
reasonType	Logout, NotReady or Wrapup.

Return Value

Returns a promise which resolves to an array of reason code objects.
Please see getReasonCodeList reference for a single object's format.

Sample code for custom integrations

const result = await cil.getReasonCodeList('voice', 'Logout');

isPrimaryTab

Available for: Custom Integration

This request returns whether the integration is running in the primary (i.e. first opened) browser tab or not. As an example this request can be utilized to run custom code only once even though the integration is loaded in multiple browser tabs.

Return Value

Returns a promise which resolves to true if the integration runs in the primary (i.e. first opened) browser tab and false otherwise.

Sample code for custom integrations

const result = await cil.isPrimaryTab();

setAgentState

Available for: Custom Requests Custom Integration

This request sets the state of the agent on a specific channel.

Field	Description
request	Request name "setAgentState"
channelId	voice for all voice channels (multiple matching channels possible), voice_<peripheral_id> for a specific voice channel, voice_-1 for CCX voice channel, telephony for WxCC voice channel.
state	Requested state (Ready, NotReady, Logout)
reasonCode	Not ready or logout reason code (empty if no reason code is required)
requestId	Identifier to map an event/error to the request (optional)

Return Value

Returns a promise which has no value.
If successful, an "agentStateChange" event will be raised.
If the request fails, an “error” event will be dispatched.

Sample code for custom integrations

await cil.setAgentState(channelId, newState, reasonCode, requestId);

showError

Available for: Custom Integration

This request can be used to show an error message in b+s Connects.

info

Alerts are displayed in the same order as they are received by b+s Connects. When b+s Connects is reloaded, all queued alerts are deleted and will not be displayed.

Field	Description
description	The description of the error message and a suggestion of how to deal with it.
title	The title of the error message (optional).
confirmAction	An object containing a label and a callback for a button that confirms the suggested action (optional).
dismissAction	An object containing a label and a callback for a button that dismisses the suggested action (optional). Note: It is possible to pass a dismissAction without a callback.

Return Value

Returns a promise which has no value.

Sample code for custom integrations

await cil.showError(
  'Looks like an error has occurred. Do you want to reload?',
  'Oh no...',
  {label: 'Reload', callback: () => location.reload()},
  {label: 'Cancel', callback: undefined }
)

showInfo

Available for: Custom Integration

This request can be used to show an info message on b+s Connects.

info

Note that info messages will disappear automatically after six seconds.

Field	Description
description	The content of the info message. Cannot be longer than 60 characters.

Return Value

Returns a promise which has no value.

Sample code for custom integrations

await cil.showInfo('Example info message');

writeLog

Available for: Custom Requests Custom Integration

This request writes a log message into the b+s Connects log.

info

You can find your log entries by searching for COR_API_WRITE_LOG in the log viewer.

Field	Description
request	Request name "writeLog"
logMessage	A string containing the message to be written into the b+s Connects log.
logLevel	A log level. Debug for log messages that are for debugging purposes only. Error for log messages that contain information about errors.

Return Value

Returns a promise which has no value.

Sample code for custom integrations

await cil.writeLog('Example debug message', 'Debug');

Data reference

Workitem

Work item events have a field called data, which contains a JSON structure with the following information available:

Field	Description
event	Name of the event
version	API version
requestId	Identifier to match this event to a request (for future use)
activity	Object containing the phone call record details. See Activity record reference.
agentId	Agent id (Cisco Common Identity user id)
ani	When there is only one participant and the direction is outgoing, toAddress is picked otherwise fromAddress is chosen.
associatedParticipant	The assigned record of the participant lookup. See CRM record reference
associations	List of all records that are assigned to the workitem (currently this list only contains the phone call record). See CRM record reference
capabilities	List of actions that can be carried out
channelId	Channel identifier (telephony).
channelType	Channel type (Voice).
classification	Work item class (Customer, Consultation, Conference, Transfer, Internal, Unknown).
connectedAt	Date and time in UTC when the call was established (e.g 2020-07-28T09:51:17.696Z)
ctiData	Please see the ctiData reference for available data and format.
direction	Incoming or Outgoing
id	Call id or Task id for the current work item
participants	List of participants with their address
participantLookupResult	List of the found participant lookup entries. See CRM record reference
state	Current State (Unknown, Initiated, Offered, Active, Paused, Wrapup, Ended, EndedAbandoned, EndedTransferred, EndedUnknown)

ctiData

Property	Description
<callVariable>	For available call variables please contact your WxCC administrator.

Activity record

The activity field contains information about the created phonecall record.

info

It is possible that the activity is undefined for the workitemCreate event.

Field	Type	Description
id	String	Unique identifier of the phonecall record
recordType	String	Type of the activity record, which is phonecall

CRM record

info

It is possible that the field associatedParticipant is undefined.

CRM records consist of the following fields.

Field	Type	Description
id	String	Unique identifier of the CRM record
name	String	The name / subject of the record
recordType	String	CRM table name of the record (e.g. contact)

getChannel

Property	Description
activeDeviceId	Currently not used for WxCC
channel	Please see the channel reference for available data and format.
extension	The extension the agent is working with
firstName	First name of the agent
agentId	Agent identifier (Cisco Common Identity user id)
lastName	Last name of the agent
loginName	Login name of the agent
teamId	The identifier of the team the user belongs to

Channel

Property	Description
id	Unique Identifier for the channel (telephony)
type	Channel type (Voice)
state	Channel/agent state (Logout, Offline, Ready, NotReady, Active, Wrapup, Unknown)
reasonCode	Selected reason code; negative values indicate no code available
reasonCodeLabel	The descriptive reason name
stateChangeTime	Previous change state time
workitems	List of workitems; please see workitem reference

getReasonCodeList

Property	Description
label	The descriptive reason name
id	Unique Identifier for the reason