General

This is part of the Customer Chat API section of the Web Services API.

Overview

This API allows client applications to provide its users the ability to initiate a chat session with an agent in the contact center.

Authentication

Unlike the majority of APIs exposed by Web Services API, this API is intended to be used by customers to submit chat requests to agents, which is different than being used by users known to Web Services (for example: agents, supervisors).

Since the identity of a customer requesting a chat is unknown, there should not be an Authorization header included on any customer chat API related requests. Without the Authorization header, the client can only use APIs that are not secured. Attempts to access any of the secure APIs will result in an appropriate error response.

While the identity of the customer is not required for this API, Web Services does need to know which contact center should service the chat request. This is determined using a customer HTTP header that specifies the id of the contact center that should service the request. See the Required HTTP Header section for details.

Required HTTP Header

As noted in the Authentication section, the Customer Chat API does not require authentication of the identity of the customer and does not include account credentials.

However, Web Services still needs to determine which contact center should service the incoming chat request.

To determine this, each request to the Customer Chat API must include a custom HTTP header ContactCenterId, and this value is the id of contact center that will service the request.

The id of the contact center is not generally known to developers and should be obtained from the system administrator and kept as a constant.

There are several approaches to include a custom HTTP header when sending a request. Refer to your toolkit documentation for details. The following example shows one potential approach using jQuery/beforeSend.

Example

post = function (params) {
 
	    var data = JSON.stringify(params.json, undefined, 2);
 
	    var request = {
	        url: util.createUri(params.uri),
	        type: 'POST',
	        data: data,
	        headers: {
	            'Content-Type': 'application/json'
	        },
	        crossDomain: true,
	        xhrFields: {
	            withCredentials: true
	        },
	        success: function (result) {
	            console.log(result);
 
	            if (params.callback) {
	                params.callback(result);
	            }
	        },
	        error: function (result) {
	            console.log(result);
	            if (params.error) {
	                params.error(result);
	            }
	        }
	    };
 
	    if (config.username && config.password) {
	        request.beforeSend = function (xhr) {
	            xhr.setRequestHeader('Authorization', util.encodeCredentials());
	        };
	    } else if (config.contactCenterId) {
	        request.beforeSend = function (xhr) {
	            xhr.setRequestHeader('ContactCenterId', config.contactCenterId);
	        };
	    }
 
	    console.log('Sending POST ' + params.uri + ' ' + data);
	    $.ajax(request);
	};

Requesting updated state and messages

The customer chat API does not currently employ CometD for delivery of unsolicited notifications. Clients will need to send HTTP GET requests to /api/v2/me/chat/{id} and /api/v2/me/chat/{id}/messages to get updates to the chat state and to receive new messages.