Skip to main content
Version: 6.1

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:

  • Unified Service Desk (referred to as USD)
  • 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.

When integrating in USD you need to be able to configure USD, work with Events, Action Calls and Hosted Controls. Furthermore you might need to write USD components in C#/.NET.

How to pick the right integration type

There are 3 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).

  • Integration is inside Unified Service Desk. React to events and issue requests: USD

  • 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: USD Custom Integration

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

FieldDescription
eventEvent name "agentStateChange"
versionAPI version
requestIdIdentifier to match this event to a request
channelTypeChannel type (Voice, Mail, Chat, Task, Federation)
channelIdChannel identifier (voice_<peripheral_id>)
For CCX: voice_-1
For WxCC: telephony
newStateNew state (Logout, Offline, Ready, NotReady, Active, Wrapup, Unknown)
newReasonCodeNew reason code. Negative values indicate no code available.
newReasonCodeLabelNew reason name
newStateChangeTimeNew state change time
oldStatePrevious state: (Logout, Offline, Ready, NotReady, Active, Wrapup, Unknown)
oldReasonCodePreviously selected reason code. Negative values indicate no code available.
oldReasonCodeLabelPreviously selected reason name
oldStateChangeTimePrevious change state time

Sample code for custom integrations

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

callVariableChanged

Available for: Custom Integration

This event is raised when a call variable (e.g. callVariable1, user.eccVar, wrapUpReason) is changed.

Please see workitem reference for available data and format.

Sample code for custom integrations

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

error

Available for: USD Custom Integration

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

FieldDescription
eventEvent name "error"
versionAPI version
requestIdIdentifier of the request that might have caused the error, empty if the source of the error cannot be detected.
messageShort message describing the encountered error

Sample code for custom integrations

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

queueDataUpdate

Available for: Custom Integration

info

This event is not available in CCX environments.

This event is raised when the queue data is updated.

QueueDataUpdate events are only fired when the agent is logged in, altough registering callback functions to subscribe on queueDataUpdates is possible before login.

FieldDescription
eventEvent name "queueDataUpdate"
versionAPI version
dataStateThe state describing the received event data. See dataState reference for more information.
queueDataArray containing the queues for which the event was fired. Depending on the dataState the array contains no, one or multiple elements. See queueData reference for more information about available data.

Depending on the dataState the array contains no, one or multiple queues.

  • When dataState is ENABLED the array contains all the queues that are currently available. This can be any number of queues.
  • When dataState is ADDED the array only contains the queue for which the subscription was added.
  • When dataState is UPDATED the array contains the updated queue.
  • When dataState is DELETED the array contains only one item with only the id property.
  • When dataState is DISABLED the array is empty.
info

If a hidden and a visible integration are active at the same time, the hidden integration will also receive an event with ENABLED each time the visible integration is registered for queue updates.

Sample code for custom integrations

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

workitemConnect

Available for: USD 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: USD 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: USD 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: USD 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: USD 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)}`);
});

wrapupDataChanged

Available for: Custom Integration

This event is raised when the Wrap-Up reason is changed.

Please see workitem reference for available data and format.

Sample code for custom integrations

cil.onWrapupDataChanged((data) => {
console.warn(`message: onWrapupDataChanged, 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.

FieldDescription
requestRequest name "createSession"
templateNameName of the Session Template
templateParametersTemplate 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.

FieldDescription
channelIdvoice 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.
addressDestination address
requestIdIdentifier 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);

directTransfer

Available for: USD Custom Requests Custom Integration

This request initiates a direct transfer of a workitem. If no workitemId is provided, the request is only successful when there's exactly one workitem in Active state.

FieldDescription
requestRequest name "directTransfer"
channelIdvoice 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,
Make sure the channel is uniquely identified by this id.
addressDestination address
workitemIdId of the workitem to be direct transferred (optional)
requestIdIdentifier to map an event/error to the request (optional)

Return Value

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

Sample code for custom integrations

await cil.directTransfer('voice', phonenumber, undefined, requestId);

getChannel

Available for: Custom Integration

This request returns information about the specified channel.

FieldDescription
channelIdvoice 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.

FieldDescription
Keysetting1-5
ValueConfigured 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.

FieldDescription
channelIdvoice 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.
reasonTypeLogout, 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');

isSendDtmfEnabled

Available for: Custom Integration

This request returns whether DTMF signals can be sent or not.

Return Value

Returns a promise which resolves to true if a workitem (call) exists for which DTMF signals can be sent and false otherwise.

Sample code for custom integrations

const result = await cil.isSendDtmfEnabled();

isUpdateWorkitemDataEnabled

Available for: Custom Integration

This request returns whether the data of a workitem (call) can be updated or not.

FieldDescription
channelIdvoice 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.
workitemIdId of the workitem whose data is to be updated.

Return Value

Returns a promise which resolves to true if workitem data can be updated and false otherwise.

Sample code for custom integrations

const result = await cil.isUpdateWorkitemDataEnabled('voice', workitemId);

sendDtmf

Available for: Custom Requests Custom Integration

This request sends a dual-tone multi-frequency (DTMF) string during a call.

FieldDescription
requestRequest name "sendDtmf"
dtmfThe dtmf string to be sent to the active call.
Possible characters are:
CCE: 0-9, *, #, A-D.
CCX: 0-9, *, #.
requestIdIdentifier to map an event/error to the request (optional).

Return Value

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

Sample code for custom integrations

const result = await cil.sendDtmf('1', requestId);

setAgentState

Available for: USD Custom Requests Custom Integration

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

FieldDescription
requestRequest name "setAgentState"
channelIdvoice 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.
stateRequested state (Ready, NotReady, Logout)
reasonCodeNot ready or logout reason code (empty if no reason code is required)
requestIdIdentifier 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);

setWrapupReason

Available for: Custom Requests Custom Integration

This request updates the Wrap-Up reason of a call.

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 the Integration API, the previously custom set reason is removed from the list.

FieldDescription
requestRequest name "setWrapupReason"
channelIdvoice 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.
workitemIdId of the workitem to update the Wrap-Up reason of.
wrapUpReasonThe name of the Wrap-Up reason to be set.
requestIdIdentifier to map an event/error to the request (optional)

Return Value

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

Sample code for custom integrations

await cil.setWrapupReason(channelId, workitemId, 'Documentation', 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.

FieldDescription
descriptionThe description of the error message and a suggestion of how to deal with it.
titleThe title of the error message (optional).
confirmActionAn object containing a label and a callback for a button that confirms the suggested action (optional).
dismissActionAn 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.

FieldDescription
descriptionThe 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');

singleStepConference

Available for: USD Custom Requests Custom Integration

This request effects a single step conference in a new party. If no workitemId is provided the request is only successful when there's exactly one workitem in Active state.

FieldDescription
requestRequest name "singleStepConference".
channelIdvoice 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.
Make sure the channel is uniquely identified by this id.
addressDestination address
workitemIdId of the workitem to be single step transferred (optional)
requestIdIdentifier to map an event/error to the request (optional)

Return Value

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

Sample code for custom integrations

await cil.singleStepConference('voice', phonenumber, undefined, requestId);

updateWorkitemData

Available for: Custom Requests Custom Integration

This request updates the call variables and Wrap-Up reason of a call.

caution

Overwriting the configured share record variable can lead to incorrect behavior of the b+s Connects.

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 the Integration API, the previously custom set reason is removed from the list.

FieldDescription
requestRequest name "updateWorkitemData"
channelIdvoice 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,
Make sure the channel is uniquely identified by this id.
workitemIdId of the workitem whose data is to be updated.
updatedDataAn object containing the data that is to be updated.
Values have to be of type string.
Example: {'callVariable1': '12345', 'user.eccVar1': '999999', 'wrapUpReason': 'Documentation'}
requestIdIdentifier to map an event/error to the request (optional)

Return Value

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

Sample code for custom integrations

await cil.updateWorkitemData(channelId, workitemId, {'callVariable1': '12345', 'user.eccVar1': '999999', 'wrapUpReason': 'Documentation'}, requestId);

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.

FieldDescription
requestRequest name "writeLog"
logMessageA string containing the message to be written into the b+s Connects log.
logLevelA 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:

FieldDescription
eventName of the event
versionAPI version
requestIdIdentifier to match this event to a request (for future use)
activityObject containing the phone call record details. See Activity record reference.
agentIdAgent id
aniWhen there is only one participant and the direction is outgoing, toAddress is picked otherwise fromAddress is chosen.
associatedParticipantThe assigned record of the participant lookup. See CRM record reference
associationsList of all records that are assigned to the workitem (currently this list only contains the phone call record). See CRM record reference
capabilitiesList of actions that can be carried out
channelIdChannel identifier (voice_<peripheral_id>)
For CCX: voice_-1
For WxCC: telephony
channelTypeChannel type (Voice, Mail, Chat, Task, Federation).
classificationWork item class (Customer, Consultation, Conference, Transfer, Internal, Unknown).
connectedAtDate and time in UTC when the call was established (e.g 2020-07-28T09:51:17.696Z)
ctiDataPlease see the ctiData reference for available data and format.
directionIncoming or Outgoing
idCall id or Task id for the current work item
participantsList of participants with their address
participantLookupResultList of the found participant lookup entries. See CRM record reference
stateCurrent State (Unknown, Initiated, Offered, Active, Paused, Wrapup, Ended, EndedAbandoned, EndedTransferred, EndedUnknown)

ctiData

Availability of the following fields is dependent on the Finesse version, please see the Finesse documentation for more details.

PropertyDescription
callKeyCallIdIndicates the unique number for the call routed on that particular day (CCE only)
callKeyPrefixIndicates the day when the call was routed (CCE only)
callTypeType of the call
callVariable1-10Peripheral variables 1 to 10
dialedNumberDialed Number of the call
DNISDNIS of the call
mediaIdMedia routing id
outboundClassificationOutbound call classification (VOICE, FAX, ANS_MACHINE, INVALID, DO_NOT_CALL, or BUSY)
queueNameName of the queue
queueNumberQueue name id
user.<variable>ECC variables
wrapUpReasonCurrently set call wrap-up reason

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.

FieldTypeDescription
idStringUnique identifier of the phonecall record
recordTypeStringType 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.

FieldTypeDescription
idStringUnique identifier of the CRM record
nameStringThe name / subject of the record
recordTypeStringCRM table name of the record (e.g. contact)

getChannel

PropertyDescription
activeDeviceIdActive device id for agents using shared line feature
channelPlease see the channel reference for available data and format.
extensionThe extension the agent is working with
firstNameFirst name of the agent
agentIdIdentifier of the agent
lastNameLast name of the agent
loginNameLogin name of the agent
teamIdThe identifier of the team the user belongs to

Channel

PropertyDescription
idUnique Identifier for the channel
typeChannel type (Voice, Mail, Chat, Task, Federation)
stateChannel/agent state (Logout, Offline, Ready, NotReady, Active, Wrapup, Unknown)
reasonCodeSelected reason code; negative values indicate no code available
reasonCodeLabelThe descriptive reason name
stateChangeTimePrevious change state time
workitemsList of workitems; please see workitem reference

Channel (Create Event)

PropertyDescription
idUnique Identifier for the channel
typeChannel type (Voice, Mail, Chat, Task, Federation)
previousStatePrevious channel/agent state (Logout, Offline, Ready, NotReady, Active, Wrapup, Unknown)
activeStateActive channel/agent state (Logout, Offline, Ready, NotReady, Active, Wrapup, Unknown)
nextStateNext channel/agent state (Logout, Offline, Ready, NotReady, Active, Wrapup, Unknown)
lastStateChangeDate of the last State change
stateChangeInProgressIndicates if a state change is currently pending

getReasonCodeList

PropertyDescription
labelThe descriptive reason name
idUnique Identifier for the reason

dataState

ValueDescription
ENABLEDThe agent is logged in and queueDataUpdate events can be received.
ADDEDA new subscription for a queue was created.
UPDATEDThe data of a queue has been updated.
DELETEDThe agent has been removed from a queue and the subscription to that queue was deleted.
DISABLEDqueueDataUpdate events currently can't be received because the agent is logged out.

queueData

Queue items have the following structure:

PropertyTypeDescription
idStringUnique identifier of the queue.
nameStringName of the queue.
channelStringType of channel the queue belongs to. Currently only Voice.
escalationLevelStringThreshold of the queue, calculated based on the configuration (Normal, Warn, Critical).
statisticsObjectStatistic values for this queue. Please see the statistics reference for available data and format.

statistics

PropertyTypeDescription
agentsNotReadyNumberAmount of agents in state Not Ready.
agentsReadyNumberAmount of agents in state Ready.
agentsTalkingInboundNumberAmount of agents in state Talking having an inbound call.
agentsTalkingInternalNumberAmount of agents in state Talking having an agent-to-agent call
agentsTalkingOutboundNumberAmount of agents in state Talking having an outbound call
agentsWrapUpNotReadyNumberAmount of agents in Wrapup with follow-up state Not Ready
agentsWrapUpReadyNumberAmount of agents in Wrapup with follow-up state Ready
callsInQueueNumberAmount of calls in queue
startTimeOfLongestCallInQueueStringStart date and time of the longest call in queue

Differences between CCE and CCX

This page can't give a complete overview of the differences between CCE and CCX. Please note the following observations as pointers to assist you when planning the integration.

Blind transfer

For CCE there might be an additional call in order to complete the transfer, whereas in CCX only one call is used/signalled.

Receive a call in Not Ready state

When a call is received/placed and the agent state is Not Ready, no agentStateChange (Active) event will be dispatched in CCX.

No queueDataUpdate events in CCX

Since queues are not available in CCX queueDataUpdate events are not available as well.