The OneCloud CX Mobile/Web Messaging API v2 is a RESTful API that allows developers to integrate chat and voice interactions with mobile devices or third-party applications. The CX Mobile/Web Messaging API v2 expands on our existing Mobile/Web Messaging API v1, and can be used for development of rich contact applications, such as customer-facing mobile, web, and messaging applications for advanced chat, voice, and video communications with OneCloud Contact Center-based contact centers.

Features

In addition to all the methods and events included in the v1 API, the Mobile/Web Messaging API v2 includes the following:

Support for the Apple Push Notification service (iOS) and Firebase Cloud Messaging push notifications (Android and iOS) with the Mobile Notification Subscription method
The Get Case History method, which returns the combined transcripts of all chat sessions linked to a specific CRM Case object
The Close Case method, which allows a client application request to close the case associated with the chat session
The Get Version method, which returns the version of Bright Pattern Contact Center used on the server.
Server and client events indicating that a chat session message was delivered or read
A server event indicating if a chat session case was set

Note

The CX Mobile/Web Messaging API v2 endpoint prefix is as follows:

https://[tenant_url]/clientweb/api/v2/

Audience

This documentation is intended for the IT personnel and developers of custom applications for Bright Pattern Contact Center-based contact centers. Readers of this documentation are expected to have expertise in web and mobile application development as well as a solid understanding of contact center operations and resources that are involved in such operations.

Sample Applications

OneCloud provides source code of sample customer-facing rich contact applications. This source code can be used as a reference for in-house application development or it can be embedded directly into the customer-facing mobile applications and/or web applications of your organization.

For web chat applications, you can download the source code by clicking the Client application button on the Messaging/Chat Scenario Entry page of the Contact Center Administrator application.

For mobile applications, you can obtain the source code by submitting a service request to OneCloud Success Management.

Example Request

The following is an example of an API request:

URL: https://tenant.cx.onecloud.com/clientweb/api/v2/chats?tenantUrl=yourcompany.brightpattern.com
Method: POST
Authorization: MOBILE-API-140-327-PLAIN appId="test", clientId="123"
Content-Type: application/json; charset=UTF-8
User-Agent: MobileClient
{
    "phone_number":"3001",
    "parameters": {
        "first_name":"John",
        "last_name":"Lee"
        }
}

Client Authentication Elements

The following elements are used for client authentication and must be specified in every client request:

Element	Description
tenantUrl	Identifies your contact center. It corresponds to the domain name of your contact center that you see in the upper right corner of the Contact Center Administrator application after login.
appId	Unique identifier of the Messaging/Chat scenario entry that will be used to associate your application with a specific scenario
clientId	Unique identifier of the client application. It is used to identify communication sessions of a particular instance of the mobile application (i.e., of a specific mobile device). It must be generated by the mobile application and should be unique for each client application/device combination. If clientId is set to WebChat, HTTP cookies will be used for client identification.
User-Agent	Specifies the type of client interface. For web applications, it is determined by the browser type. For mobile applications, this parameter shall always be set to MobileClient.

Additional Information

Standard HTTP response codes whose meaning conforms to the original specification (RFC 2616) are not discussed in this document. For specification of such responses, see section 10 of http://www.ietf.org/rfc/rfc2616.txt. This document only specifies the response codes whose description deviates from the original specification (e.g., is defined more narrowly or has a different meaning).

Note: A client application can only have one active communication session at a time.

Error Body

When the response status code indicates an error, a JSON response body is provided by the server to
give more details about the error:
{"error_code": "error code", "error_message":"error message"}

Authorization Errors

Here is a list of the possible values of authorization-related error codes and error messages that are
common to all requests that require authorization.

error_code	error_message
1000	Missing or invalid tenantUrl
2000	Authorization header is missing
2001	Authorization parameter format is incorrect
2002	Authorization scheme is incorrect
2003	Authorization parameter is missing: appId
2004	Authorization parameter is missing: clientId

Other Errors

Here is a list of the possible values of other error codes and error messages.

error_code	error_message
3000	Missing or invalid application unique id
5000	Timeout - chat server takes too long to respond
5001	No server is available to accept chat connection
5003	Error decoding JSON request body: {JSON exception message}
5004	Chat server disconnected
5005	Chat session is not found
5006	Mobile Launch Point (application) is not found
5500	[internal server error message]
5501	Upload size limit exceeded
5502	File not found
5509	Too many concurrent poll requests for the same session
5511	No events
5558	[file operation error message]
5955	Unspecified server error
5601	No case is specified for this session.
5602	CRM server responded with error.
5603	Too many parameters.