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.
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)}`);
});
Loading a custom integration as hidden is recommended if the beforeDial event is used, to avoid it being unloaded.
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.
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)}`);
});
queueDataUpdate
Available for: Custom Integration
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.
Field | Description |
---|---|
event | Event name "queueDataUpdate" |
version | API version |
dataState | The state describing the received event data. See dataState reference for more information. |
queueData | Array 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.
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.
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);
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.
Field | Description |
---|---|
request | Request name "directTransfer" |
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,Make sure the channel is uniquely identified by this id. |
address | Destination address |
workitemId | Id of the workitem to be direct transferred (optional) |
requestId | Identifier 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.
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();
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.
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. |
workitemId | Id 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.
Field | Description |
---|---|
request | Request name "sendDtmf" |
dtmf | The dtmf string to be sent to the active call. Possible characters are: CCE: 0-9, *, #, A-D .CCX: 0-9, *, # . |
requestId | Identifier 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.
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);
setWrapupReason
Available for: Custom Requests Custom Integration
This request updates the Wrap-Up reason of a call.
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.
Field | Description |
---|---|
request | Request name "setWrapupReason" |
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. |
workitemId | Id of the workitem to update the Wrap-Up reason of. |
wrapUpReason | The name of the Wrap-Up reason to be set. |
requestId | Identifier 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.
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.
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');
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.
Field | Description |
---|---|
request | Request name "singleStepConference". |
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.Make sure the channel is uniquely identified by this id. |
address | Destination address |
workitemId | Id of the workitem to be single step transferred (optional) |
requestId | Identifier 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.
Overwriting the configured share record variable can lead to incorrect behavior of the b+s Connects.
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.
Field | Description |
---|---|
request | Request name "updateWorkitemData" |
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,Make sure the channel is uniquely identified by this id. |
workitemId | Id of the workitem whose data is to be updated. |
updatedData | An object containing the data that is to be updated. Values have to be of type string. Example: {'callVariable1': '12345', 'user.eccVar1': '999999', 'wrapUpReason': 'Documentation'} |
requestId | Identifier 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.
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 |
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 (voice_<peripheral_id> )For CCX: voice_-1 For WxCC: telephony |
channelType | Channel type (Voice, Mail, Chat, Task, Federation ). |
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
Availability of the following fields is dependent on the Finesse version, please see the Finesse documentation for more details.
Property | Description |
---|---|
callKeyCallId | Indicates the unique number for the call routed on that particular day (CCE only) |
callKeyPrefix | Indicates the day when the call was routed (CCE only) |
callType | Type of the call |
callVariable1-10 | Peripheral variables 1 to 10 |
dialedNumber | Dialed Number of the call |
DNIS | DNIS of the call |
mediaId | Media routing id |
outboundClassification | Outbound call classification (VOICE, FAX, ANS_MACHINE, INVALID, DO_NOT_CALL, or BUSY ) |
queueName | Name of the queue |
queueNumber | Queue name id |
user.<variable> | ECC variables |
wrapUpReason | Currently set call wrap-up reason |
Activity record
The activity field contains information about the created phonecall record.
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
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 | Active device id for agents using shared line feature |
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 | Identifier of the agent |
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 |
type | Channel type (Voice, Mail, Chat, Task, Federation ) |
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 |
Channel (Create Event)
Property | Description |
---|---|
id | Unique Identifier for the channel |
type | Channel type (Voice, Mail, Chat, Task, Federation ) |
previousState | Previous channel/agent state (Logout, Offline, Ready, NotReady, Active, Wrapup, Unknown ) |
activeState | Active channel/agent state (Logout, Offline, Ready, NotReady, Active, Wrapup, Unknown ) |
nextState | Next channel/agent state (Logout, Offline, Ready, NotReady, Active, Wrapup, Unknown ) |
lastStateChange | Date of the last State change |
stateChangeInProgress | Indicates if a state change is currently pending |
getReasonCodeList
Property | Description |
---|---|
label | The descriptive reason name |
id | Unique Identifier for the reason |
dataState
Value | Description |
---|---|
ENABLED | The agent is logged in and queueDataUpdate events can be received. |
ADDED | A new subscription for a queue was created. |
UPDATED | The data of a queue has been updated. |
DELETED | The agent has been removed from a queue and the subscription to that queue was deleted. |
DISABLED | queueDataUpdate events currently can't be received because the agent is logged out. |
teamDataState
Value | Description |
---|---|
ENABLED | The agent is logged in and teamDataUpdate events can be received that contain a list of all agents in the team. |
UPDATED | Team data has been updated and contains information on the updated logged in agent. |
DISABLED | teamDataUpdate events currently can't be received because the agent is logged out. |
queueData
Queue items have the following structure:
Property | Type | Description |
---|---|---|
id | String | Unique identifier of the queue. |
name | String | Name of the queue. |
channel | String | Type of channel the queue belongs to. Currently only Voice . |
escalationLevel | String | Threshold of the queue, calculated based on the configuration (Normal, Warn, Critical ). |
statistics | Object | Statistic values for this queue. Please see the statistics reference for available data and format. |
statistics
Property | Type | Description |
---|---|---|
agentsNotReady | Number | Amount of agents in state Not Ready. |
agentsReady | Number | Amount of agents in state Ready. |
agentsTalkingInbound | Number | Amount of agents in state Talking having an inbound call. |
agentsTalkingInternal | Number | Amount of agents in state Talking having an agent-to-agent call |
agentsTalkingOutbound | Number | Amount of agents in state Talking having an outbound call |
agentsWrapUpNotReady | Number | Amount of agents in Wrapup with follow-up state Not Ready |
agentsWrapUpReady | Number | Amount of agents in Wrapup with follow-up state Ready |
callsInQueue | Number | Amount of calls in queue |
startTimeOfLongestCallInQueue | String | Start 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.