Cention Chat API 5.1.0

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.

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

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.

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

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

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.

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

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.

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

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

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

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

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

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

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

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

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.

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

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

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

Description: Disconnect the ongoing chat.

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

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.

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

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

The return value is an [Unsent message object]

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:

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

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

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.

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

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

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:

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.

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

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

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

$('#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.

$('#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();
	}
});

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

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