The third-party extensions are custom UI extensions for the Sinch Contact Center Communication Panel. They are normal HTML pages running inside an iframe in the side panel view of Communication Panel.
In this document and in the API, interaction is a single term used for email, chat or SMS conversation, or phone call.
There are two types of extensions: global and interaction-specific. For global extensions, the lifecycle is from user login to logout. For interaction-specfic extensions, the extension will be loaded once the user accepts the offered interaction and removed when the user handles the interaction.
The custom extensions and Communication Panel communicate with the postMessage cross-origin messaging. In the extension code, window.parent.postMessage will be used to send messages towards Communication Panel and the responses will be captured with event listener window.addEventListener("message", callback). This documentation describes the type of messages that can be sent.
The schema describes the messages and data structures returned from Communication Panel.
Custom extensions are configured and loaded on queue or global basis. The configuration consist of the translatable title, URL to the location of the extension, icon and whether it should be executed in hidden or built-in global mode. Once the configuration is in place, Communication Panel will load the extension from the URL and place it behind a button in the Communication Panel's interaction view sidebar. Currently global extensions can only be hidden extensions. For more information on configuring the extensions for queues, see the System Configurator document (Queue Management > Configuring Third-Party Extensions).
Because the extension is running inside an iframe within Communication Panel, your server that shares the extension needs to allow this by setting the web security model correctly.
Content Security Policy (CSP) is an added layer of security that helps to detect and mitigate certain types of attacks. First of all the server that shares the extension must not send X-Frame-Options header at all. The server should send Content-Security-Policy with parameters:
Content-Security-Policy: frame-ancestors https://www.CC_COMMUNICATION_PANEL_HOST.com
Cross-Origin Resource Sharing (CORS) is a mechanism that uses additional HTTP headers to tell browsers to give a web application running at one origin, access to selected resources from a different origin. Depending on what type of requests are made towards your server from the extension, you need to configure the correct CORS headers sent from the server. As an example:
Access-Control-Allow-Origin: https://www.CC_COMMUNICATION_PANEL_HOST.com
Access-Control-Allow-Methods: POST, GET, OPTIONS
Access-Control-Allow-Headers: My-Header, Content-Type
Access-Control-Max-Age: 86400
Access-Control-Allow-Credentials: true
If your extension relies on cookies, note that they are treated as third party. Cookies have a parameter called SameSite that specifies when the cookie will be sent.
The default behavior when it is not specified is Lax, so you should always provide the attribute as None to allow the cookie:
Set-Cookie: widget_session=abc123; SameSite=None; Secure
In your extension code, start listening to "message" events in the startup code. In the callback function you should handle the responses coming from Communication Panel:
function onMessage(event){
console.log("Communication Panel message", event.data);
if(event.data.id === "my-init"){
console.log("Communication Panel init", event.data.payload);
}else if(event.data.id === "my-details"){
console.log("Communication Panel extension info", event.data.payload);
}
}
window.attachEventListener("message", onMessage);
To send messages towards Communication Panel, use the window.parent.postMessage function. The "init" message should always be the first message you send to initiate the extension.
var _commPanelOrigin = window.location.ancestorOrigins ? window.location.ancestorOrigins[0] : document.referrer;
window.parent.postMessage({type: "init", payload: false, id: "my-init"}, _commPanelOrigin);
window.parent.postMessage({type: "action", payload: {command: "details", value: "extension"}, id: "my-details"}, _commPanelOrigin);
See examples chapter for a full-fledged intermediate application utilizing all the messages. The second example contains code that registers helper functions to window scope to deal with messaging if that is something preferred.
This chapter contains descriptions and limited examples of the messages. See the schema for all the possible values and descriptions of the attributes.
All the messages have a basic structure made of attributes id, message type and varying payload field. The id field is used to map between request and response messages and it can be anything (for example an increasing number).
Whenever there is error, the response payload will contain the "error" in the value field and description in the reason field.
When sending messages towards Communication Panel from your extension, it is recommended to provide Communication Panel origin as the second parameter for window.postMessage for security reasons.
The extension needs to send init message once it is ready to accept messages from Communication Panel. The response contains the details of the current interactions.
If the payload is set to true, all the cached messages that would have been delivered before the init message are sent.
request
{
"id": "id-init",
"type": "init",
"payload": true
}
response
{
"id": "id-init",
"type": "response",
"payload": {
"value": {
"attached_data": {"d1": "041"},
"id": "3B0E6C12382D470EA3EB33B90685E984",
...
}
}
}
response
{
"id": "id-init",
"type": "response",
"payload": {
"value": "error",
"reason": "initiation failure"
}
}
If the extension sends the exit message, Communication Panel will stop sending messages and cache them instead until init is received.
When Communication Panel sends exit message, it means the user has decided to handle the interaction or the user has logged out and the extension will be removed.
request
{
"id": "id-x",
"type": "exit"
}
response
{
"id": "id-x",
"type": "response",
"payload": {
"value": "ok"
}
}
Communication Panel sends state messages whenever there is a change in the interaction state or the selection of the active interaction or the active
extension changes. Notified attributes are status, channel_status, cad, message, activeExtension and activeInteraction.
Call attached data or cad is a custom object that can be appended by the other participant (that is, the customer client or some custom integration piece). It is the same as attached_data for the interaction object.
{
"id": "id-x",
"type": "state",
"payload": {
"attribute": "status",
"value": "accepted",
"interaction": {
"attached_data": {"d1": "041"},
"id": "3B0E6C12382D470EA3EB33B90685E984",
...
}
}
}
Communication Panel sends status messages whenever there is a change in the capability of the user. Notified attributes are phone_status, work_status, login_status and profile.
Phone status means is the user has a softphone capability .Work status is the user availability in the system and profile is the active presence profile.
{
"id": "id-x",
"type": "status",
"payload": {
"attribute": "login_status",
"value": "logged_in",
"interaction": {
"attached_data": {"d1": "041"},
"id": "3B0E6C12382D470EA3EB33B90685E984",
...
}
}
}
Action type messages are requests made from the extension. Communication Panel will always respond with a response type message including the matching message ID.
Request details of the system from Communication Panel. Possible values are user, interaction, interactions, queue, queues,
transcript , extension, activeExtension and activeInteraction.
Optionally you can provide the id of an interaction you want the related details on. Responses for different details are described in the definition section of schema.
request
{
"id": "id-x",
"type": "action",
"payload": {
"command": "detail",
"value": "extension"
}
}
response
{
"id": "id-x",
"type": "response",
"payload": {
"value": {
"key": "Communication Panel_3rdParty",
"icon": "sap-icon://address-book",
"text":"3rd. Party Extension",
"url":"http://localhost:5001/frame.html",
"visible":true,
"external":true,
"enabled":true,
"expanded": true
}
}
}
Create outbound interaction from Communication Panel. Supported channel values are sms, email and phone.
These following properties are used differently depending on channel:
direct:sms and email.to and content for sms, and additionally subject for email. These are required to send the outgoing interaction "directly".phone: Phone calls are always created "directly".to:channel types.email the value must be an array of string addresses.from:from.email: Defines sender email address.sms: Defines sender number.phone: Defines the caller phone number (Visible A-Number).subject:email channel only. Sets Subject for outgoing email.direct is true.content:email and sms. Sets message Content.direct is true.Returns the details of the created interaction.
request
{
"id": "id-x",
"type": "action",
"payload": {
"command": "outbound",
"value": {
"channel": "email",
"direct": true,
"to": ["test1@test.com", "test2@test.com"],
"from": "emailQueue1@cctr.com",
"subject": "This is a test",
"content": "<b>Hello World </b>"
}
}
}
response
{
"id": "id-x",
"payload": {
"value": {
"attached_data": {"d1": "041"},
"id": "3B0E6C12382D470EA3EB33B90685E984",
...
}
}
}
Transfer interaction, or ask for consultation in the current active interaction. Alternatively, provide the ID of specific interaction for which you want the action to be performed.
Consultation is possible in phone and chat channels.
CAD (call attached data) can be optionally provided when performing transfer operation.
Returns the details of the created interaction.
request
{
"id": "id-x",
"type": "action",
"payload": {
"command": "transfer",
"interactionId": "2B4E6617738D470EA3EB33B90685E984",
"value": {
"to": "test1@test.com",
"cad": {
"key-1":"value-1",
"key-2":"value-2",
}
}
}
}
response
{
"id": "id-x",
"payload": {
"value": {
"attached_data": {"d1": "041"},
"id": "3B0E6C12382D470EA3EB33B90685E984",
...
}
}
}
Sets a configuration property of the extension. Setting visible will change the visibility of the button in the sidebar menu, enabled will define wheter the button can be clicked and expanded will make the extension itself visible or hidden.
request
{
"id": "id-x",
"type": "action",
"payload": {
"command": "expanded",
"value": true
}
}
response
{
"id": "id-x",
"type": "response",
"payload": {
"value": "ok"
}
}
Send a new chat message or DTMF tones. This works for only in progress interactions in chat, sms and phone channels.
Optionally you can provide the id of an interaction that should be acted on.
request
{
"id": "id-x",
"type": "action",
"payload": {
"command": "message",
"interactionId": "2B4E6617738D470EA3EB33B90685E984",
"value": {
"content": "<b>Hello World!</b>"
}
}
}
response
{
"id": "id-x",
"type": "response",
"payload": {
"value": "ok"
}
}
Perform a state changing action on the current interaction. Possible actions are reject, accept, hangup, handle, pick.
Optionally you can provide the id of an interaction that should be acted on.
request
{
"id": "id-x",
"type": "action",
"payload": {
"command": "interaction",
"interactionId": "2B4E6617738D470EA3EB33B90685E984",
"value": "reject"
}
}
response
{
"id": "id-x",
"type": "response",
"payload": {
"value": "ok"
}
}
Perform a state changing action on a proceeding phone call. Possible payload values are startRecording, stopRecording, hold, unhold,
mute and unmute.
Optionally you can provide the id of an interaction that should be acted on.
request
{
"id": "id-x",
"type": "action",
"payload": {
"command": "callState",
"interactionId": "2B4E6617738D470EA3EB33B90685E984",
"value": "startRecording"
}
}
response
{
"id": "id-x",
"type": "response",
"payload": {
"value": "ok"
}
}
Simplified example of utilizing window messaging.
<html>
<body>
<script>
var _sOrigin = window.location.ancestorOrigins ? window.location.ancestorOrigins[0] : document.referrer;
var _onMessage = function(oEvent) {
var data = oEvent.data.payload.value;
if (oEvent.data.id === "fn-1") {
document.getElementById("bd").innerText = "Interaction in channel " + data.channel;
window.parent.postMessage({type: "action", payload: {command:"details", value:"user"}, id: "fn-2"}, _sOrigin);
} else if (oEvent.data.id === "fn-2") {
console.log("User details", data)
}
}
window.addEventListener("message", _onMessage);
window.parent.postMessage({type: "init", payload: false, id: "fn-1"}, _sOrigin);
</script>
<p id="bd">Loading...</p>
</body>
</html>
Example of an extension with all of the possible messages utilized. This register a library cpc to window scope so it is accessible everywhere in the extension.
<html>
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, minimal-ui"/>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=edge"/>
<base target="_blank">
<link rel="stylesheet" href="https://unpkg.com/fundamental-styles@0.6.0/dist/fundamental-styles.css"/>
<!-- cpc library code -->
<script>
/**
* Sinch Contact Center Communication Panel
* Registers a small API to window scope. Iframe messaging example. IE compatible.
* Uses cross-origin communication to send command messages between Communication Panel and this client and provides simplified API.
* @namespace cpc
*/
(function(cpc, undefined) {
// Private variables
/**
* The hostname of ECF Web Server where Communication Panel is server from. Get it directly from window ancestors
* @type {string}
* @private
*/
var _sOrigin = window.location.ancestorOrigins ? window.location.ancestorOrigins[0] : document.referrer;
/**
* Message counter
* @type {number}
* @private
*/
var _iMsgId = 0;
/**
* Message callback map
* @type {object}
* @private
*/
var _mMsg = {};
//Public Methods
/**
* Initiates the controller to start listening window messaging.
* Executed when script is processed.
*/
cpc.init = function() {
window.addEventListener("message", _onMessage);
cpc.sendMessage("init", true, function(oMsg) {
if (oMsg.result !== "error") {
_triggerEvent("init");
} else {
window.removeEventListener("message", _onMessage);
console.error(oMsg.reason);
}
});
};
/**
* Stops listening to messaging events.
*/
cpc.exit = function() {
cpc.sendMessage("exit", null, function(oMsg) {
if (oMsg.result !== "error") {
_triggerEvent("exit");
} else {
console.error(oMsg.reason);
}
});
};
/**
* Sends a XDM message to the visitor host application iframe.
* @param {string} type Type of the interface message
* @param {object} [payload] Optional payload to be sent
* @param {function} [fnCallback] Optional callback to be executed on successful
* @private
*/
cpc.sendMessage = function(type, payload, fnCallback) {
var iId = "cpc-" + _iMsgId++;
if (fnCallback) {
_mMsg[iId] = fnCallback;
}
_sendMessage(type, payload, iId);
};
/**
* Sends a XDM message to the visitor host application iframe.
* Example of ES6 feature code.
* @param {string} type Type of the interface message
* @param {object} [payload] Optional payload to be sent
* @param {function} [fnCallback] Optional callback to be executed on successful
* @private
*/
cpc.sendMessagePromise = (type, payload) => {
return new Promise((res, rej) => {
const iId = "cpc-" + _iMsgId++;
_mMsg[iId] = (msg) => {
if (msg.result === "error") {
rej();
} else {
res(msg);
}
};
_sendMessage(type, payload, iId);
})
};
//Private Methods
/**
* Listens to XDM messages originating from the visitor host application iframe.
* @private
* @listens window#message
*/
function _onMessage(oEvent) {
if (oEvent.source !== window.parent) {
return;
}
var oData = oEvent.data || {};
_triggerEvent("message", oData);
switch (oData.type) {
case "response":
if (_mMsg.hasOwnProperty(oData.id)) {
_mMsg[oData.id](oData.payload);
delete _mMsg[oData.id];
}
break;
case "status":
case "state":
_triggerEvent(oData.type, oData.payload);
break;
case "exit":
window.removeEventListener("message", _onMessage);
_triggerEvent(oData.type);
break;
default:
return;
}
}
/**
* Sends a XDM message to the visitor host application iframe.
* @private
*/
function _sendMessage(sMessage, oData, iId) {
var oMsg = {type: sMessage, payload: oData, id: iId || "cpc-" + _iMsgId++};
_triggerEvent("sendmessage", oMsg);
window.parent.postMessage(oMsg, _sOrigin);
}
/**
* Send an event to parent site
* @private
*/
function _triggerEvent(sType, oDetail) {
var oEvent;
// IE
var fnFallback = function() {
oEvent = document.createEvent('CustomEvent');
oEvent.initCustomEvent(sType, false, false, oDetail);
};
if (window.CustomEvent) {
try {
oEvent = new window.CustomEvent(sType, {
bubbles: false,
cancelable: false,
detail: oDetail
});
} catch (oException) {
fnFallback();
}
} else {
fnFallback();
}
document.dispatchEvent(oEvent);
}
// Load the controller
cpc.init();
}(window.cpc = window.cpc || {}));
</script>
<!-- end library code -->
<script>
/**
* Example UI code implementation
*/
_bEnabled = true;
_bVisible = true;
_bExpanded = true;
// Event listeners
document.addEventListener("message", function(oMsg) {
addTr(oMsg.detail.id, oMsg.detail.type, JSON.stringify(oMsg.detail.payload), false);
});
document.addEventListener("sendmessage", function(oMsg) {
addTr(oMsg.detail.id, oMsg.detail.type, JSON.stringify(oMsg.detail.payload), true);
});
document.addEventListener("init", function(oMsg) {
showMsg("Extension initialized", "information");
document.getElementById("act-pw").className = "fd-button--positive sap-icon--log";
});
document.addEventListener("exit", function(oMsg) {
showMsg("Extension exited");
document.getElementById("act-pw").className = "fd-button--negative sap-icon--log";
});
document.addEventListener("state", function(oMsg) {
showMsg(oMsg.detail.attribute + ":" + oMsg.detail.value);
});
// UI Functions
function showMsg(sMsg, sLevel) {
var sClass = sLevel ? " fd-message-strip--" + sLevel : "";
var act = document.getElementById("act-item");
act.className = "fd-message-strip" + sClass;
act.childNodes[1].innerText = sMsg;
}
function addTr(sId, sType, sPayload, bDir) {
var tr = document.createElement("tr");
tr.className = "fd-table__row";
var td = document.createElement("th");
td.className = "fd-table__cell";
td.innerText = sId;
tr.appendChild(td);
td = td.cloneNode(true);
td.innerText = sType;
tr.appendChild(td);
td = td.cloneNode(true);
td.innerText = (sPayload || "").slice(0, 30);
td.setAttribute("title", sPayload);
tr.appendChild(td);
td = td.cloneNode(true);
td.innerHTML = bDir ? "<span class=\"sap-icon--arrow-top\"></span>" : "<span class=\"sap-icon--arrow-bottom\"></span>";
tr.appendChild(td);
document.getElementById("msg-table").appendChild(tr);
var container = document.getElementById("msg-table-c");
container.scrollTop = container.scrollHeight;
}
// UI callbacks
function getDetails(sType) {
cpc.sendMessage("action", {command: "detail", value: sType}, function(oMsg) {
if (oMsg.value === "error") {
showMsg("getDetails:" + sType + "\r\n" + oMsg.reason, "error");
} else {
showMsg("getDetails:" + sType, "success");
}
});
}
function power() {
if (document.getElementById("act-pw").className.indexOf("negative") !== -1) {
cpc.init();
} else {
cpc.exit();
}
}
function toggleAction(sType, bValue) {
cpc.sendMessage("action", {command: sType, value: bValue}, function(oMsg) {
if (oMsg.value === "error") {
showMsg("toggleAction:" + sType + "\r\n" + oMsg.reason, "error");
} else {
showMsg("toggleAction:" + sType, "success");
if (sType === "visible") {
_bVisible = bValue;
} else {
_bEnabled = bValue;
}
}
});
}
function createAction(sCommand, oPayload) {
cpc.sendMessage("action", {command: sCommand, value: oPayload}, function(oMsg) {
if (oMsg.value === "error") {
showMsg("createAction:" + sCommand + "\r\n" + oMsg.reason, "error");
} else {
showMsg("createAction:" + sCommand, "success");
}
});
}
function createOutbound(sType, oPayload, bDirect) {
oPayload.channel = sType;
oPayload.direct = bDirect;
createAction("outbound", oPayload);
}
</script>
</head>
<body style="margin: 0">
<div style="display: flex; flex-direction: column;height: 100%">
<br/>
<div style="padding: 10px; margin-right:auto">
<div id="act-item" class="fd-message-strip" role="alert">
<p class="fd-message-strip__text" style="word-break: break-all">
Extension loading
</p>
</div>
</div>
<br/>
<div style="padding: 10px; line-height: 3">
<button id="act-pw" onclick="power()" class="fd-button--negative sap-icon--log"></button>
<button class="fd-button" onclick="getDetails('user')">User</button>
<button class="fd-button" onclick="getDetails('queue')">Queue</button>
<button class="fd-button" onclick="getDetails('queues')">Queues</button>
<button class="fd-button" onclick="getDetails('interaction')">Interaction</button>
<button class="fd-button" onclick="getDetails('transcript')">Transcript</button>
<button class="fd-button" onclick="getDetails('extension')">Extension</button>
<button class="fd-button" onclick="toggleAction('enabled', !_bEnabled)">Enabled</button>
<button class="fd-button" onclick="toggleAction('visible', !_bVisible)">Visible</button>
<button class="fd-button" onclick="toggleAction('expanded', !_bExpanded)">Expanded</button>
<input class="fd-input" type="text" id="i1"/>
<button class="fd-button" onclick="createOutbound('email', {to:[document.getElementById('i1').value]})">Email</button>
<button class="fd-button" onclick="createOutbound('email', {to:[document.getElementById('i1').value], subject:'hi', content:'<b>HELLO WORLD</b>'}, true)">EmailD</button>
<button class="fd-button" onclick="createOutbound('sms', {to:document.getElementById('i1').value, content:'<b>HELLO WORLD</b>'})">SMS</button>
<button class="fd-button" onclick="createOutbound('sms', {to:document.getElementById('i1').value, content:'<b>HELLO WORLD</b>'}, true)">SMSD</button>
<button class="fd-button" onclick="createOutbound('phone', {to:document.getElementById('i1').value})">Call</button>
<button class="fd-button" onclick="createAction('transfer', {to:document.getElementById('i1').value})">Transfer</button>
<button class="fd-button" onclick="createAction('consult', {to:document.getElementById('i1').value})">Consult</button>
<button class="fd-button" onclick="createAction('message', {content:document.getElementById('i1').value})">Message</button>
<button class="fd-button" onclick="createAction('interaction', {content:document.getElementById('i1').value})">InteractionState</button>
</div>
<br/>
<div id="msg-table-c" style="flex-grow: 1; overflow: auto">
<table class="fd-table">
<thead class="fd-table__header">
<tr class="fd-table__row">
<th class="fd-table__cell" scope="col">Id</th>
<th class="fd-table__cell" scope="col">Type</th>
<th class="fd-table__cell" scope="col">Payload</th>
<th class="fd-table__cell" scope="col">Direction</th>
</tr>
</thead>
<tbody id="msg-table" class="fd-table__body">
</tbody>
</table>
</div>
</div>
</body>
</html>
Complete schema of the interface detailing all the available attributes. JSON Schema Validator can be used to validate your messages.
{
"type": "object",
"title": "The Message Schema",
"description": "The root schema of the interface message",
"required": [
"id",
"type"
],
"properties": {
"id": {
"type": "string",
"description": "Unique message id. Simple increasing number is valid",
"examples": [
"cpc-1",
"cpc-2"
]
},
"type": {
"type": "string",
"description": "Message types 'action' and 'response' are reserved to commands between CP and the extension. Type 'state' is for indicating the a change in the interaction. 'init' and 'exit' are for component lifecycle",
"enum": [
"action",
"response",
"state",
"status",
"init",
"exit"
]
},
"payload": {
"description": "The payload content of the message",
"oneOf": [
{
"type": "boolean",
"description": "When sending 'init' message, with payload set to true, all the messages cached to that point (what has happened inside the interaction) will be sent"
},
{
"description": "When using 'action' command a request message is the payload",
"$ref": "#/definitions/requestMessage"
},
{
"description": "When message is a 'response', the payload will contain a response resource",
"$ref": "#/definitions/responseMessage"
},
{
"description": "When message is a 'state' or 'status' change, the payload will contain a state resource",
"$ref": "#/definitions/stateMessage"
}
]
}
},
"definitions": {
"requestMessage": {
"type": "object",
"description": "Request type message",
"required": [
"command",
"value"
],
"properties": {
"command": {
"type": "string",
"description": "One of the commands to execute",
"enum": [
"outbound",
"detail",
"transfer",
"consult",
"dtmf",
"message",
"visible",
"enabled",
"expanded",
"interaction",
"callState"
]
},
"value": {
"description": "The details of the action. With outbound action it contains the details of the contact",
"oneOf": [
{
"type": "boolean",
"description": "When requesting a simple state change ('expanded', 'visible', 'enabled')"
},
{
"type": "string",
"description": "When requesting 'detail', specify the type of details needed",
"enum": [
"user",
"interaction",
"queue",
"queues",
"transcript",
"extension",
"activeExtension",
"activeInteraction"
]
},
{
"type": "string",
"description": "When requesting 'interaction', set the desired action to be performed on the interaction",
"enum": [
"accept",
"reject",
"pick",
"handle",
"hangup"
]
},
{
"type": "string",
"description": "When requesting 'callState', provide one of the actions",
"enum": [
"startRecording",
"stopRecording",
"hold",
"unhold",
"mute",
"unmute"
]
},
{
"type": "object",
"description": "When creating an 'outbound', 'transfer', 'dtmf', 'consult' or 'message', define the details of the recipient",
"properties": {
"to": {
"type": "string",
"description": "When creating call or sms, define the number"
},
"content": {
"type": "string",
"description": "Set the content of the message. In the case of chat and email, HTML syntax is supported"
},
"from": {
"type": "string",
"description": "Optionally define source queue address, to be used as sender (SMS and email) or Visible A Number (phone)"
},
"cc": {
"type": "array",
"description": "CC field for email",
"items": {
"type": "string"
}
},
"bcc": {
"type": "array",
"description": "BCC field for email",
"items": {
"type": "string"
}
},
"channel": {
"type": "string",
"description": "When creating outbound, specify the channel used",
"enum": [
"phone",
"sms",
"email"
]
},
"direct": {
"type": "boolean",
"description": "When creating outbound sms or email, send it directly without confirmation from the CP user"
},
"cad": {
"type": "object",
"description": "CAD to be included when transferring ongoing interaction"
}
}
}
]
},
"interactionId": {
"type": "string",
"description": "When setting interaction state, transferring or consulting optionally define what interaction should be acted on"
}
}
},
"responseMessage": {
"type": "object",
"description": "Response type message payload",
"properties": {
"value": {
"description": "Contains always the output of the action. When action fails, it is simply 'error'",
"oneOf": [
{
"type": "string",
"description": "For simple actions, result contains only 'ok'. When action fails this field is 'error'",
"enum": [
"ok",
"error"
]
},
{
"$ref": "#/definitions/interaction"
},
{
"$ref": "#/definitions/queue"
},
{
"$ref": "#/definitions/queues"
},
{
"$ref": "#/definitions/user"
},
{
"$ref": "#/definitions/transcript"
}
]
},
"reason": {
"type": "string",
"description": "In a case of error, this field contains the reason for the error"
}
}
},
"stateMessage": {
"type": "object",
"description": "State change type message payload",
"properties": {
"attribute": {
"type": "string",
"description": "The attribute that changed during the interaction",
"enum": [
"cad",
"status",
"channel_status",
"message",
"login_status",
"work_status",
"phone_status",
"activeExtension",
"activeInteraction"
]
},
"value": {
"description": "Value depends on the attribute changed",
"oneOf": [
{
"description": "CAD change",
"$ref": "#/definitions/interaction/properties/attached_data"
},
{
"description": "Channel status change",
"$ref": "#/definitions/interaction/properties/channel_status"
},
{
"description": "Interaction status change",
"$ref": "#/definitions/interaction/properties/status"
},
{
"description": "New chat message",
"$ref": "#/definitions/interaction/properties/transcript/properties/messages/items"
},
{
"description": "Login status change",
"$ref": "#/definitions/user/properties/login_status"
},
{
"description": "Work status change",
"$ref": "#/definitions/user/properties/work_status"
},
{
"description": "Active interaction change",
"$ref": "#/definitions/interaction"
},
{
"description": "Active extension change",
"$ref": "#/definitions/extension"
}
]
},
"interaction": {
"description": "Interaction that was changed",
"$ref": "#/definitions/interaction"
}
}
},
"interaction": {
"type": "object",
"description": "Interaction is a presentation of the action that is happening for the user",
"properties": {
"id": {
"description": "Unique ID of the interaction",
"type": "string",
"pattern": "^[a-zA-Z0-9]{32}$",
"unique_key": true
},
"channel_type": {
"description": "Channel type of the interaction",
"type": "string",
"enum": [
"user_defined",
"chat",
"email",
"phone"
]
},
"channel_status": {
"description": "Channel status of the interaction",
"type": "string",
"enum": [
"bad_address",
"barred",
"busy",
"calling",
"congestion",
"connected",
"disconnected",
"knocking",
"muted",
"no_answer",
"onhold",
"onvideo",
"outbound_accepted",
"outbound_incoming",
"outbound_preview",
"outbound_rejected",
"outbound_skipped",
"outgoing",
"picking",
"queue_closed",
"queue_full",
"rejected",
"ringing",
"system_error",
"temporary_failure",
"transferring",
"unknown",
"unreachable"
]
},
"channel_sub_type": {
"description": "Custom channel type specified by host app",
"type": "string"
},
"date_created": {
"description": "Date and Time the interaction was created",
"type": "string"
},
"status": {
"description": "Current status of the interaction",
"type": "string",
"enum": [
"queued",
"incoming",
"outgoing",
"accepted",
"rejected",
"handled",
"ended"
]
},
"originator": {
"description": "Originating address of the interaction. For a phone call would be the A-Number. For email, the email address sent from",
"type": "string"
},
"destination": {
"description": "Destination of the original call. For a phone call would be the B-Number. For email, the email address sent to",
"type": "string"
},
"dir_entry": {
"description": "Directory information of other party",
"type": "object",
"properties": {
"id": {
"description": "Unique ID of the directory entry",
"type": "string",
"pattern": "^[a-zA-Z0-9]{32}$",
"unique_key": true
},
"name": {
"description": "Name of the directory entry",
"type": "string"
}
}
},
"recording": {
"description": "Recording state of the (call) interaction",
"type": "boolean"
},
"consent": {
"description": "Recording consent of the (call) interaction",
"type": "boolean"
},
"consult_for": {
"description": "Id of the interaction for which this is consultation",
"type": "string",
"pattern": "^[a-zA-Z0-9]{32}$"
},
"callback_id": {
"description": "Callback id in case of callback call",
"type": "string",
"pattern": "^[a-zA-Z0-9]{32}$"
},
"conference_id": {
"description": "Conference id in case of conference call",
"type": "string",
"pattern": "^[a-zA-Z0-9]{32}$"
},
"from_queue": {
"description": "Queue that interaction was last routed from",
"type": "object",
"properties": {
"id": {
"description": "CCtr unique ID of the queue",
"type": "string",
"pattern": "^[a-zA-Z0-9]{32}$",
"unique_key": true
},
"name": {
"description": "Name of the queue",
"type": "string"
}
},
"required": [
"id",
"name"
]
},
"orig_queue": {
"description": "Queue that interaction was originally routed from",
"type": "object",
"properties": {
"id": {
"description": "CCtr unique ID of the queue",
"type": "string",
"pattern": "^[a-zA-Z0-9]{32}$",
"unique_key": true
},
"name": {
"description": "Name of the queue",
"type": "string"
}
},
"required": [
"id",
"name"
]
},
"outbound": {
"description": "Outbound campaign call data",
"type": "object",
"properties": {
"campaign": {
"description": "Outbound campaign data",
"type": "object",
"properties": {
"id": {
"description": "CCtr unique ID of the campaign",
"type": "string",
"pattern": "^[a-zA-Z0-9]{32}$",
"unique_key": true
},
"name": {
"description": "Campaign name",
"type": "string"
},
"description": {
"description": "Campaign description",
"type": "string"
},
"start_date": {
"description": "Campaign start date",
"type": "string"
},
"end_date": {
"description": "Campaign end date",
"type": "string"
},
"max_calls": {
"description": "Campaign customer call limit",
"type": "number"
},
"classifiers": {
"description": "Campaign classifiers",
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"description": "CCtr unique ID of the classifier",
"type": "string",
"unique_key": true
},
"name": {
"description": "Classifier name",
"type": "string"
},
"call_result": {
"description": "Classifier call result",
"type": "string"
}
}
}
}
}
},
"customer": {
"description": "Outbound customer data",
"type": "object",
"properties": {
"id": {
"description": "Unique ID of the customer",
"type": "string",
"pattern": "^[a-zA-Z0-9]{32}$",
"unique_key": true
},
"remarks": {
"description": "Customer remarks",
"type": "string"
},
"modify_access": {
"description": "Customer modify access",
"type": "boolean"
},
"attributes": {
"description": "Customer attributes",
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"description": "Attribute name e.g. 'Phone1'",
"type": "string",
"unique_key": true
},
"value": {
"description": "Attribute value e.g. '1234567'",
"type": "string"
},
"editable": {
"description": "Whether attribute is editable",
"type": "boolean"
},
"hidden": {
"description": "Whether attribute is hidden",
"type": "boolean"
}
}
}
},
"previous_calls": {
"description": "Customer previous calls",
"type": "array",
"items": {
"type": "object",
"properties": {
"created": {
"description": "Call creation time",
"type": "string"
},
"result": {
"description": "Call result",
"type": "string"
}
}
}
}
}
},
"initial_info": {
"description": "Customer call initial information text",
"type": "string"
},
"preview_time": {
"description": "Customer call preview time (seconds)",
"type": "number"
}
}
},
"attached_data": {
"description": "Interaction attached data",
"type": "object",
"additionalProperties": true,
"required": []
},
"title": {
"description": "Title that is displayed for this interaction",
"type": "string"
},
"incoming_destination": {
"description": "Identifier for incoming destination",
"type": "string"
},
"iswtf": {
"description": "Interaction waiting time",
"type": "number"
},
"participants": {
"description": "Chat conversation participants",
"type": "array",
"items": {
"type": "object",
"properties": {
"uniquekey": {
"description": "Unique identifier for the chat participant",
"type": "string",
"unique_key": true
},
"alias": {
"description": "Human-readable nick-name for the chat participant",
"type": "string"
},
"status": {
"description": "Status of the participant (typing / not_typing)",
"type": "string",
"enum": [
"typing",
"not_typing"
]
},
"capability": {
"description": "User communication capabilities",
"type": "string",
"enum": [
"text",
"video"
]
}
},
"required": [
"uniquekey",
"alias"
]
}
},
"transcript": {
"description": "Chat conversation transcript",
"type": "object",
"properties": {
"messages": {
"description": "Collection of messages that make up a Chat conversation",
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"description": "Unique ID for the message",
"type": "string",
"unique_key": true
},
"ref_id": {
"description": "Reference to another id to string together a message sequence",
"type": "string"
},
"message": {
"description": "individual message in the chat conversation",
"type": "string"
},
"timestamp": {
"description": "Date and time the message was sent/received",
"type": "string"
},
"originator": {
"description": "Participant who sent the message. (maps to a '/interactions/[index]/participant' value)",
"type": "string"
}
},
"required": [
"message",
"timestamp",
"originator"
]
}
}
},
"required": [
"messages"
]
},
"terminal_id": {
"description": "terminalID of the interaction",
"type": "string"
},
"content": {
"description": "Content of the (email) interaction",
"type": "string"
},
"attachments": {
"description": "Collection of attachments'",
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"description": "Unique ID for the attachment",
"type": "string",
"unique_key": true
},
"filename": {
"description": "File name of the attachment",
"type": "string"
},
"size": {
"description": "File size of the attachment",
"type": "string"
},
"originator": {
"description": "Originator of the attachment",
"type": "string"
}
}
}
},
"case_id": {
"description": "Case id of the (email) interaction",
"type": "string"
},
"cid": {
"description": "CIDt of the (email) interaction",
"type": "string"
},
"contact_id": {
"description": "Contact id of interaction",
"type": "string",
"pattern": "^[a-zA-Z0-9]{32}$"
},
"original_contact_id": {
"description": "Original contact id of interaction",
"type": "string",
"pattern": "^[a-zA-Z0-9]{32}$"
},
"from_address": {
"description": "Address from which the (email) interaction was sent from",
"type": "object",
"properties": {
"address": {
"description": "E-mail address of the sender",
"type": "string",
"unique_key": true
},
"name": {
"description": "Name of the sender",
"type": "string"
}
},
"required": [
"address"
]
},
"reply_to_address": {
"description": "Reply to address in e-mail",
"type": "object",
"properties": {
"address": {
"description": "E-mail address of the reply-to address",
"type": "string",
"unique_key": true
},
"name": {
"description": "Name of the reply-to account",
"type": "string"
}
},
"required": [
"address"
]
},
"to_address": {
"description": "Collection of target addresses'",
"type": "array",
"items": {
"type": "object",
"properties": {
"address": {
"description": "E-mail address of the target",
"type": "string",
"unique_key": true
},
"name": {
"description": "Name of the target",
"type": "string"
}
}
}
},
"cc_address": {
"description": "Collection of cc addresses'",
"type": "array",
"items": {
"type": "object",
"properties": {
"address": {
"description": "E-mail address of the cc",
"type": "string",
"unique_key": true
},
"name": {
"description": "Name of the cc",
"type": "string"
}
}
}
},
"bcc_address": {
"description": "Collection of bcc addresses'",
"type": "array",
"items": {
"type": "object",
"properties": {
"address": {
"description": "E-mail address of the bcc",
"type": "string",
"unique_key": true
},
"name": {
"description": "Name of the bcc",
"type": "string"
}
}
}
},
"draft": {
"description": "Draft email information",
"type": "object",
"properties": {
"id": {
"description": "unique ID of the draft",
"type": "string",
"pattern": "^[a-zA-Z0-9]{32}$",
"unique_key": true
},
"owner_terminal_id": {
"description": "Id the of the handling terminal",
"type": "string"
},
"draft_type": {
"description": "Type of the draft",
"type": "string"
},
"status": {
"description": "Status of the draft",
"type": "string"
},
"subject": {
"description": "Subject of the draft",
"type": "string"
},
"content": {
"description": "Content of the draft",
"type": "string"
},
"attachments": {
"description": "Collection of attachments'",
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"description": "Unique ID for the attachment",
"type": "string",
"unique_key": true
},
"filename": {
"description": "File name of the attachment",
"type": "string"
},
"size": {
"description": "File size of the attachment",
"type": "string"
},
"originator": {
"description": "Originator of the attachment",
"type": "string"
}
}
}
},
"from_address": {
"description": "Selected from address",
"type": "string"
},
"from_addresses": {
"description": "Collection of possible from addresses'",
"type": "array",
"items": {
"type": "object",
"properties": {
"address": {
"description": "E-mail address of the source",
"type": "string",
"unique_key": true
},
"name": {
"description": "Name of the source",
"type": "string"
}
}
}
},
"to_address": {
"description": "Collection of target addresses'",
"type": "array",
"items": {
"type": "object",
"properties": {
"address": {
"description": "E-mail address of the target",
"type": "string",
"unique_key": true
},
"name": {
"description": "Name of the target",
"type": "string"
}
}
}
},
"cc_address": {
"description": "Collection of possible cc addresses'",
"type": "array",
"items": {
"type": "object",
"properties": {
"address": {
"description": "E-mail address of the cc",
"type": "string",
"unique_key": true
},
"name": {
"description": "Name of the cc",
"type": "string"
}
}
}
},
"bcc_address": {
"description": "Collection of possible bcc addresses'",
"type": "array",
"items": {
"type": "object",
"properties": {
"address": {
"description": "E-mail address of the bcc",
"type": "string",
"unique_key": true
},
"name": {
"description": "Name of the bcc",
"type": "string"
}
}
}
}
}
},
"scripts": {
"description": "Script results for this interaction",
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"description": "Unique identifier for script",
"type": "string",
"unique_key": true
},
"script_opening_type": {
"description": "Opening type for script",
"type": "string"
},
"status": {
"description": "Status for script",
"type": "string"
},
"scriptanswers": {
"description": "Answers for script",
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"description": "Question id",
"type": "string",
"unique_key": true
},
"answerdata": {
"description": "Answer data for script",
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"description": "Answer id",
"type": "string"
},
"data": {
"description": "Answer data",
"type": "string"
},
"ordinal": {
"description": "Answer ordinal",
"type": "number"
}
}
}
}
}
}
}
},
"required": [
"uniquekey"
]
}
},
"webrtc": {
"description": "WebRTC signalling 'conversation' for Video Chat",
"type": "object",
"properties": {
"status": {
"description": "Status of the WebRTC 'conversation'",
"type": "string",
"enum": [
"on",
"signalling",
"off",
"error"
]
},
"messages": {
"description": "Collection of messages that make up a WebRTC 'conversation'",
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"description": "Unique ID for the message",
"type": "string",
"unique_key": true
},
"message": {
"description": "individual message in the WebRTC conversation",
"type": "string"
},
"timestamp": {
"description": "Date and time the message was sent/received",
"type": "string"
},
"originator": {
"description": "Participant who sent the message. (maps to a '/interactions/[index]/participant' value)",
"type": "string"
},
"icecandidates": {
"description": "Collection of ICE servers available for WebRTC RTP streaming",
"type": "array",
"items": {
"type": "object",
"properties": {
"candidate": {
"description": "ICE server candidate for WebRTC RTP streaming",
"type": "object",
"additionalProperties": true
},
"sdp": {
"description": "SDP properties used for negotiating WebRTC RTP streaming",
"type": "object",
"additionalProperties": true
}
}
}
}
},
"required": [
"id",
"message",
"timestamp",
"originator",
"icecandidates"
]
}
}
},
"required": [
"status",
"messages"
]
}
},
"required": [
"id",
"channel_type",
"date_created",
"status",
"originator",
"destination",
"from_queue",
"attached_data",
"title"
]
},
"user": {
"description": "Contains properties for user related objects and properties",
"type": "object",
"properties": {
"id": {
"description": "Unique ID of the user",
"type": "string",
"pattern": "^[a-zA-Z0-9]{32}$",
"unique_key": true
},
"name": {
"description": "Name of the user",
"type": "object",
"properties": {
"first_name": {
"description": "First Name of the user",
"type": "string"
},
"last_name": {
"description": "Last Name of the user",
"type": "string"
}
},
"required": [
"first_name",
"last_name"
]
},
"username": {
"description": "Username of the user",
"type": "string"
},
"alias": {
"description": "Alias of the user shown in conversations (ie: chat)",
"type": "string"
},
"login_status": {
"description": "Login status of the user",
"type": "string",
"enum": [
"logged_in",
"logged_out",
"anonymous"
]
},
"visible_a_number": {
"description": "The visible A-number (caller number) of the user. Default value is the current phone extension.",
"type": "string"
},
"work_status": {
"description": "The work status of the user",
"type": "string",
"enum": [
"ready",
"not_ready",
"wrap_up"
]
},
"daily_pause_time": {
"description": "Agent daily pause time (seconds)",
"type": "string"
},
"daily_work_time": {
"description": "Agent daily work time (seconds)",
"type": "string"
},
"default_email_from": {
"description": "Users default email from address",
"type": "string"
},
"default_sms_from": {
"description": "Users default SMS from address",
"type": "string"
},
"presence": {
"description": "Id for user's currently active presence profile",
"type": "string",
"unique_key": true,
"pattern": "^[a-zA-Z0-9]{32}$"
},
"presence_profiles": {
"description": "All of the available profiles",
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"description": "Type of the profile. If presence type is absence, work_status change to ready is not accepted.",
"type": "string",
"enum": [
"presence",
"absence",
"conference",
"unknown"
]
},
"name": {
"description": "Presence profile name",
"type": "string"
},
"id": {
"description": "Unique id for the presence profile",
"type": "string",
"unique_key": true,
"pattern": "^[a-zA-Z0-9]{32}$"
},
"availability": {
"description": "Availability of the profile",
"type": "string",
"enum": [
"FREE",
"TENTATIVE",
"AWAY",
""
]
},
"settings": {
"description": "Profile details",
"type": "object",
"properties": {
"reason": {
"description": "Reason for the profile",
"type": "string"
},
"default_behaviour": {
"description": "What happens when the profile is enabled",
"type": "string"
},
"duration": {
"description": "Duration of the profile when enabled",
"type": "string"
},
"priority": {
"description": "Priority for the profile",
"type": "string"
}
},
"required": [
"reason",
"default_behaviour",
"duration",
"priority"
]
}
},
"required": [
"type",
"name",
"id",
"availability"
]
}
},
"chat_address": {
"description": "email address of the user",
"type": "string"
},
"extension": {
"description": "Phone extension of the user",
"type": "string"
},
"language": {
"description": "Language selected by agent server based on CCtr user configuration",
"type": "string"
},
"permissions": {
"description": "User permissions",
"type": "object",
"properties": {
"ecf_phone": {
"type": "boolean",
"description": "ECF Phone Permission for user"
},
"phone": {
"type": "boolean",
"description": "Phone Permission for user"
},
"mtd": {
"type": "boolean",
"description": "MTD Permission for user"
},
"recording": {
"type": "string",
"description": "Recording Permission (enabled | disabled | hidden) for user"
},
"update_visible_a_number": {
"type": "boolean",
"description": "Visible A-number update Permission for user"
},
"video": {
"type": "boolean",
"description": "Video Permission for user"
}
}
},
"terminal_id": {
"description": "terminalID of the client",
"type": "string",
"pattern": "^[a-zA-Z0-9]{32}$"
},
"phone": {
"description": "Language selected by agent server based on CCtr user configuration",
"type": "object",
"properties": {
"sip_host": {
"description": "sip host to which the sip client will connect to",
"type": "string"
},
"sip_connected": {
"description": "True = sip phone connected, False = sip phone not connected",
"type": "boolean"
},
"extension": {
"description": "Users sip number (when SIPML5 registers, it should use this number)",
"type": "string"
},
"sip_proxies": {
"description": "Array of ws_servers Address of SIP bridge to which we should route sip messages",
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"sip_host",
"extension",
"sip_connected",
"sip_proxies"
]
},
"capabilities": {
"description": "Capabilities of the user",
"type": "object",
"properties": {
"video_chat": {
"description": "Video chat capability of the user",
"type": "boolean",
"enum": [
false,
true
]
},
"phone": {
"description": "Audio chat capability of the user",
"type": "boolean",
"enum": [
false,
true
]
}
},
"required": [
"video_chat",
"phone"
]
}
},
"required": [
"id",
"name",
"username",
"login_status",
"work_status",
"extension",
"language",
"permissions",
"phone",
"capabilities",
"terminal_id"
]
},
"queue": {
"type": "object",
"description": "Information about a queue entity",
"properties": {
"id": {
"description": "Unique ID of the queue",
"type": "string",
"pattern": "^[a-zA-Z0-9]{32}$",
"unique_key": true
},
"name": {
"description": "CCtr Name of the queue",
"type": "string"
},
"serve": {
"description": "Whether the agent is serving or not in a queue",
"type": "boolean"
},
"forced_to_serve": {
"description": "Whether the queue needs to be served and cannot be changed by the user",
"type": "boolean"
},
"type": {
"description": "Type of the queue",
"type": "string"
},
"queue_autopwtime": {
"description": "Interaction wrapup time",
"type": "number"
},
"queue_maxpicktimeout": {
"description": "Interaction offering time",
"type": "number"
},
"queue_answerinfo": {
"description": "Interaction answer info",
"type": "string"
},
"script_opening_type": {
"description": "Script opening type of the queue",
"type": "string"
},
"threshold_max_wait_time_critical": {
"description": "Threshold value for queueing time",
"type": "number"
},
"threshold_max_wait_time_warning": {
"description": "Threshold value for queueing time",
"type": "number"
},
"threshold_interactions_critical": {
"description": "Threshold value for the amount of interactions",
"type": "number"
},
"threshold_interactions_warning": {
"description": "Threshold value for the amount of interactions",
"type": "number"
},
"threshold_agents_waiting_critical": {
"description": "Threshold value for the amount of free agents",
"type": "number"
},
"threshold_agents_waiting_warning": {
"description": "Threshold value for the amount of free agents",
"type": "number"
},
"threshold_agents_serving_critical": {
"description": "Threshold value for the amount of busy agents",
"type": "number"
},
"threshold_agents_serving_warning": {
"description": "Threshold value for the amount of busy agents",
"type": "number"
}
}
},
"queues": {
"type": "array",
"description": "All of the queues available for the agent.",
"items": {
"$ref": "#/definitions/queue"
}
},
"extension": {
"type": "object",
"description": "Information about the extension",
"properties": {
"key": {
"type": "string",
"description": "Unique key of the extension"
},
"text": {
"type": "string",
"description": "Title of the extension"
},
"icon": {
"type": "string",
"description": "UI5 icon shown in the toolbar"
},
"enabled": {
"type": "boolean",
"description": "Is the extension selectable in the toolbar"
},
"visible": {
"type": "boolean",
"description": "Is the extension visible in the toolbar"
},
"external": {
"type": "boolean",
"description": "Is the extension from external source"
},
"url": {
"type": "string",
"description": "Location where the extension is loaded from"
}
}
},
"transcript": {
"description": "Chat conversation transcript",
"type": "array",
"items": {
"$ref": "#/definitions/interaction/properties/transcript/properties/messages/items"
}
}
}
}