API Reference

Events

onAgentStateChange

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)}`);
});

onCallVariableChanged

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)}`);
});

onCreateChannel

This event is raised when a new channel is created in b+s Connects.

Please see create channel event reference for available data and format.

Sample code for custom integrations

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

onError

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)}`);
});

onQueueDataUpdate

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.

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.

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)}`);
});

onTeamDataUpdate

This is a real time statistic event. It is fired when an agent in the current agent's team changes their 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

Field	Description
event	Event name "teamDataUpdate"
version	API version
teamDataState	The state describing the received event data. See teamDataState reference for more information.
teamData	If the data state is ENABLED, the object contains a list of all agents in the team. If the data state is UPDATED, the object contains only the data updated from the agent logged in. If the data state is DISABLED, the array is empty. See Team Data Structure for more information.

Sample code for custom integrations

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

onWorkitemConnect

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)}`);
});

info

If auto-accept is enabled, the field activity is empty for this event.

onWorkitemCreate

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)}`);
});

info

The field activity is empty for this event.

onWorkitemEnd

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)}`);
});

onWorkitemPause

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)}`);
});

onWorkitemResume

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)}`);
});

onWorkitemWrapup

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)}`);
});

onWrapupDataChanged

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

dialOrConsult

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

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

getReasonCodeList

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

isUpdateWorkitemDataEnabled

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);

setAgentState

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

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.

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);

updateWorkitemData

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.

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, 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.
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);

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.

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	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 Wrap-Up with follow-up state Not Ready
agentsWrapUpReady	Number	Amount of agents in Wrap-Up with follow-up state Ready
callsInQueue	Number	Amount of calls in queue
startTimeOfLongestCallInQueue	String	Start date and time of the longest call in queue

Shared Data Structures

Team Data Structure

Enabled Event

When the data state is enabled, the agent is connected and the data structure should resemble the structure below:

{
  teamId: '0101',
  teamName: 'TEAM_NAME',
  teamDataState: 'ENABLED',
  teamData: [
    {
      userId: '000001',
      extension: '',
      stateChangeTime: '2024-03-30T16:27:49.259Z',
      firstName: 'AgentName',
      lastName: 'AgentLastName 01',
      state: {
        state: '0_Logout',
        id: '-4',
        displayName: '',
        origin: '0_SafelyIgnore',
        options: []
      },
      listeningAllowed: false,
      watchingAllowed: false
    },
    {
      userId: '000002',
      extension: '300002',
      stateChangeTime: '2024-03-30T16:27:49.254Z',
      firstName: 'AgentName',
      lastName: 'AgentLastName 02',
      state: {
        state: '0_Logout',
        id: '-4',
        displayName: '',
        origin: '0_SafelyIgnore',
        options: []
      },
      listeningAllowed: false,
      watchingAllowed: false
    },
    {
      userId: '000003',
      extension: '300003',
      stateChangeTime: '2024-04-03T17:13:02.349Z',
      firstName: 'AgentName',
      lastName: 'AgentLastName 03',
      state: {
        state: '3_NotReady',
        id: '-4',
        displayName: '',
        origin: '0_SafelyIgnore',
        options: []
      },
      listeningAllowed: false,
      watchingAllowed: false
    }
  ],
  event: 'teamDataUpdate',
  version: 1
}

Updated Event

When the data state is updated, the agent is already connected and has one update. The data structure should look like the structure below:

{
  teamDataState: 'UPDATED',
  teamData: [
    {
      state: {
        id: '0',
        origin: '0_SafelyIgnore',
        state: '2_Ready',
        displayName: '',
        options: []
      },
      id: '0101',
      userId: '000001',
      firstName: 'AgentName',
      lastName: 'AgentLastName 01',
      stateChangeTime: '2024-04-03T17:13:24.015Z',
      extension: '300001',
      listeningAllowed: false,
      watchingAllowed: false
    }
  ],
  event: 'teamDataUpdate',
  version: 1
}

Disabled Event

When the data state is disabled, the agent is disconnected and the data structure should look like the structure below:

{
  teamDataState: 'DISABLED',
  teamData: [],
  event: 'teamDataUpdate',
  version: 1
}

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.