Cention
API Documentation
Cention Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage

Cention Chat API 5.1.0

Introduction

The purpose of this document is to describe the Cention Chat API which you can use to build your own chat client for Cention Contact Center. You should have received this document together with a fully working example. If you have not received this please contact Cention Support by emailing support@cention.com to receive the full documentation with examples. Please note that the provided example does not work when opened as a file directly from your hard disk. It must be put in a server and served through a web server in order to work correctly.

Among the files in the package you’ve received you will find a file named CentionChatAPI.js. This file is meant to be included in your web site so that you can use the functionality it provides to build your own chat client for your web site that can start chats with your agents that are working in Cention Contact Center. CentionChatAPI.js contains a JavaScript library that handles all the communication with the Cention chat server. A variable called FOR_THIRD_PARTY_USE defined on top of the CentionChatAPI.js needs to be set to true in order for this it to work properly with your web site.

CentionChatAPI.js has two dependencies which are the socket.js and the sockwrap.js library.

A copy of socket.js and sockwrap.js is included together in the “chat” folder sent to you, and you can serve it from your web site.

In order for your server to be allowed to connect to your Cention Contact Center system using the Cention Chat API you must first provide Cention with the name of the domains where your connections will come from. Provide this to Cention by emailing support@cention.com with the details.

Version compatibility

The API as described in this document and the corresponding example code is designed to work with Cention Contact Center version 5.0.

Cention Chat API

Initialization

This is the first step towards the integration of Cention Chat into your system. Create an instance of of the Cention Chat API object and initialize the mandatory field baseURL. Also identify the Cention Contact Center area id that we are going to connect to.

Field Type Description
baseURL String The base URL for the Cention Contact Center in https://<cention api domain>/s/<workspace> format

Example

If the name of your Cention workspace is “demo” and the cention api domain is api.cention.com

var CentionAreaId = 2;
var CentionChat = _CentionChat();
CentionChat.baseURL = 'https://api.cention.com/s/demo';

Internationalization

Messages sent to the client may come from the system. You might want to intercept these messages in order to translate it, for example:

var translation = {
	"Agent(s) removed: {AGENT_NAMES}": "Agent(s) removed: {AGENT_NAMES}",
	"Agent(s) added: {AGENT_NAMES}": "Agent(s) added: {AGENT_NAMES}",
	"{AGENT_NAME} has left the chat.": "{AGENT_NAME} has left the chat.",
	"Client ended the chat.": "Client ended the chat.",
	"{NAME} ended the chat.": "{NAME} ended the chat.",
	"{NAME} attached a file.": "{NAME} attached a file."
};
CentionChat.I = function(text) {
	return translation[text];
};

For the full list of translatable messages please refer to the example file.

CentionChat.registerAction()

Description: Register an action handler in the form of a callback function that will be invoked when the specified event occurs.

Name Type
action String
handler Function

The function requires two parameters. The first parameter is the name of the event. The second parameter is the action callback that should be invoked when the event specified in the first parameter occurs. When an event occurs data may be passed to the action callback as its sole argument. The following events are available.

Chat events

Event id Description Argument
agent preview Agent is typing [Agent preview object]
agent unavailable There were no agent available for chat None
chat closed Chat is already closed None
chat message New message received [Chat message object]
connect Connection was succesful None
connect_error Connection failed Error object
finish chat session Chat session is closed by agent or expired None
message acked Message was sent to the agent successfully [Message acked object]
message sent Message was sent to the server successfully [Message sent object]
queue Queue number change Queue number
queue full Queue is full None

Chat message object

Field Type Description
agent String Name of the agent currently assigned to the chat. Empty if no agent is assigned yet.
chat Array List of message objects that the client has not seen. In rare cases it may contain messages that are already received.
client String Name of the client as recorded in the Cention Contact Center.

Message object

This contains a message that should be displayed to the client. It may be a message that was already displayed.

Field Type Description
id Number The Cention Contact Center message id.
sender String One of CLIENT, AGENT or SYSTEM.
sent Number The unix timestamp of when the message was received.
sentHuman String Human readable timestamp (HH:MM) of when the message was received, expressed in the configured timezone for the chat area.
text String The chat message.
umid String The unsent message id. For messages originating from the client, this the same id that was generated at the client side when the message was sent. This string can be empty on the rare occasion that the Cention chat server is restarted.

Message acked object

This can be used to tell the client that the agent has seen the message that they sent.

Field Type Description
ids Array List of message ids that has been successfully sent to the agent.

Example

CentionChat.registerAction('message acked', function(msg) {
	console.log("messages received by agent", msg.ids);
});

Message sent object

Field Type Description
id String Normally this will contain the Cention Contact Center message id. In rare cases it will contain the string ‘already-seen-’ + umid.
umid String The unsent message id (generated client side).
sent Number The unix timestamp of when the message was received.
sentHuman String The timestamp (HH:MM) of when the message was received, expressed in the configured timezone for the chat area.

Agent preview object

Field Type Description
messageLen Number The length of the message that the agent is typing

Example

CentionChat.registerAction("chat message", function(data) {
	console.log("Chat message received", data);
});

CentionChat.connect()

Description: Connect the web browser to Cention Contact Center and start a new chat.

Name Type
parameters Object

The function requires one parameter in the form of an object with required key-value pairs that must be set within the object.

Name Type Description
area Number Cention Contact Center area id
email String Client’s email address.
message String Client’s initial question.
name String Client’s name.

Example

CentionChat.connect({
	area:    1,
	email:   "john.smith@gmail.com",
	message: "Hello! Where can I find Cention's office?"
	name:    "John Smith",
});

CentionChat.resetChat()

Description: Reset the internal chat state variables. When the chat ends, call this function before starting a new one.

CentionChat.tryResume()

Description: Connect the web browser to Cention Contact Center and try resume an ongoing chat that was previously associated with the current cookie session. This can be used to continue a chat session after the client navigates to another page of your website.

Name Type
handler Function

On a successful resume, the handler is passed an msg object that contains the client and chat session details:

Name Type
areaId Number
clientName String
sessionId Number
sessionSecret String

If the resume was not successfull the msg object contains an error field that describes why the resume failed.

Example

CentionChat.tryResume(function(msg) {
	if (msg.error) {
		// resume failed, show the chat form instead...
		console.log("resume failed", msg.error);
		$('StartView').show();
		return;
	}
	$('ChatView').show();
});

CentionChat.disconnect()

Description: Disconnect the ongoing chat.

This function will do nothing if you haven’t successfully connected using the CentionChat.connect() function.

CentionChat.message()

Description: Queue a message to be sent to the agent which the chat is connected to. The message remains in the queue until it is successfully sent, at which point the message sent event is generated.

The function returns an Unsent message object which allows you to immediately add the message to the client chat message list and display it as sending and mark it as sent after its corresponding message sent event is received.

Name Type
message String

This function will do nothing if you haven’t successfully connected using the CentionChat.connect() function.

Example

var sending = CentionChat.message("Hello! Are you there?");

The return value is an [Unsent message object]

Unsent message object

Field Type Description
id String A unique message id, generated client-side.
message String The message to be sent.

CentionChat.attachFile()

Description: This function allows sending files as attachments to the agent. It would upload the selected file to the server, and queue a message to the agent that client has sent a file (similar to CentionChat.message() API).

The function takes 3 parameters:

Name Type
file Object
cbOnDone callback function

Example

var fileInput = document.getElementById('ChatViewSendFileButton');
if(fileInput.files.length > 0){
	for (var i = 0; i < fileInput.files.length; i++) {
		CentionChat.attachFile(
		fileInput.files[i], 	/*the file object*/
		function(um){		/*the callback function cbOnDone*/
			// value 'um' is an [Unsent message object],
			// handle similar to CentionChat.message() API above
		});
	}
}

Uploaded file object

Field Type Description
name String the client name
file Object The file object that has been uploaded

CentionChat.preview()

Description: Send preview of the message the client is typing.

Name Type
preview String

The purpose of this function is to notify the agent that the client is typing a message. The agent can within Cention Contact Center configure the system to either show the actual message being typed or only show that the client is typing something. This function will do nothing if you haven’t successfully connected using the CentionChat.connect() function.

Example

CentionChat.preview("Hello! Are y");

CentionChat.canChat(handler, area)

Description: Find out if it is possible to start a chat.

Name Type
handler Function
area Number

The first parameter is the callback function that is called once the call to the server returns. The callback is passed an object that represent whether it is possible to start a chat for the given Cention Chat Area.

The following object is passed to the handler:

Field Type Description
chatOpen Boolean Whether the chat is open
agentsAvailable Number The number of agents available
feature Object The related chat features that was setup from cention contact center (Features available can be referred in the example)
resumable Boolean Whether the chat can be resumed
error String An error message

The presence of a non-empty error message means that it is not possible to start a chat.

Working hours can be configured in Cention Contact Center. As an example your chat for the specific area might only be open between 08:00 and 17:00. Use this function to determine if the chat for the specific area is open and whether there are agents available. If the chat isn’t open you can display a message saying that the chat is only open between 08:00 and 17:00. Or if the chat is open but there are no agents available you can display a message saying all of your agents are busy at the moment but please try again later.

Example

CentionChat.canChat(function(o) {
	if (o.error) {
		// It is not possible to start a chat
		return;
	}

	if (!o.chatOpen) {
		// Chat is not open (outside of working hours)
		return;
	}

	if (o.agentsAvailable <= 0) {
		// No agents available
		return
	}

	if(o.resumable) {
		resume: true,
			area: -1,
			callback: function(msg) {
				if(msg.sessionId) {
					// Show current chat
				}else {
					// Show chat start view
				}
			}
	}

	if(o.feature) {
		//Features included to be used if necessary
		var sendAttacmentAllowed = o.feature["chat.attachment"];
		var externalSourcePage = o.feature["chat.external-source-page"];
		var maxAttachmentSize = o.feature["chat.max-attachment-size"];
		var maxImageSize = o.feature["chat.max-image-size"];
	}

	// It is possible to start a chat
}, CentionAreaId);

CentionChat.close()

Description: CentionChat.close() function closes chat connection between user and agent.

Save Chat History

Description: Register event handler for when the “Save a copy” link is clicked. User can save and download the chat history by this event.

Example

$('#CentionChatSaveButton').on('click', function() {
	var url = CentionChat.baseURL
		+ "/socket/external.api/savehistory?area="+ CentionAreaId
		+ "&secret=" + CentionChat.sessionSecret
		;
	window.open(url, '_self');
});

Description: Register event handler for when the print button is clicked. User can print the chat history by clicking print button. The popup window will appear with save button to print the chat history.

Example

$('#CentionChatPrintButton').on('click', function() {
	var url = CentionChat.baseURL
		+ "/socket/external.api/printhistory?area=" + CentionAreaId
		+"&secret=" + CentionChat.sessionSecret
		;
	var popup = window.open(url, 'window', 'width=640,height=480,scrollbars=yes,status=no');
	if( window.focus ) {
		popup.focus();
	}
});

Close Chat

Description: Register event handler for when the “Finish chat” link is clicked.

Example

$('#CentionChatFinishButton').on('click', function() {
	// CentionChat.close() function close chat connection between user and agent.
	CentionChat.close();
});