Web Chat Cloud Service Integration

Instructions on how to create a custom WebChat widget that uses Xima’s cloud backend.

Note: This API functionality requires Contact Center Web Chat Licenses.

To use this, you must request an API Key by contacting Xima. As a note, an API Key is different from the Authentication Key received from creating a Service User.

You will also need the 'Chat Installation Id' which can be found under the Multimedia Chat Seat section of Chronicall's System Settings.

The URLs used in the Web Chat API begin with https://mm-v1.ximasoftware.com. Any breaking changes to the Xima Web Chat API will be deployed to https://mm-v2.ximasoftware.com, then mm-v3, etc.

Note: For this feature, you must be updated to version 4.0.9 or newer.

Suggest Edits

Use Cases

Create your own WebChat client that connects to Chronicall Contact Center.

Checking a Session

GET /chat/queue?existingChatSessionId={chat-session-id}

An endpoint to verify that a chat session exists. The chat widget does this on page load.

Arguments
chat‑session‑id (optional)	A UUID to identify the chat session.

Response

If a chat session exists, a ChatSession object will be returned. If the chat session does not exist, a 204 response code will be returned.

Response Breakdown

chatQueueType: Possible values are SERVERTOCLIENT, CLIENTTOSERVER, or QUEUESTATUS
id: Session ID
installationId: The chat installation ID
email: End user email
name: End user name
agent: Agent name
agentImage: Base 64 encoded image

{
  "sessionDetails": {
    "serverToClientQueue": {
      "url": "https://sqs.us-east-1.amazonaws.com/775407092955/mm-queue-054d867a-76da-44f3-b63a-1ca187398f6d",
      "arn": "arn:aws:sqs:us-east-1:775407092955:mm-queue-054d867a-76da-44f3-b63a-1ca187398f6d",
      "created": "2012-04-23T18:25:43.511Z",
      "lastUsed": " 2012-04-23T18:25:43.511Z",
      "chatQueueType": "SERVERTOCLIENT",
    },
    "clientToServerQueue": {
      "url": "https://sqs.us-east-1.amazonaws.com/775407092955/mm-queue-054d867a-76da-44f3-b63a-1ca187398f6d",
      "arn": "arn:aws:sqs:us-east-1:775407092955:mm-queue-054d867a-76da-44f3-b63a-1ca187398f6d",
      "created": "2012-04-23T18:25:43.511Z",
      "lastUsed": " 2012-04-23T18:25:43.511Z",
      "chatQueueType": "CLIENTTOSERVER",
    },
    "id": "9c108bb3-8924-4234-a53c-be9ab284d4e3",
    "installationId": "9c108bb3-8924-4234-a53c-be9ab284d4e3",
    "email": "[email protected]",
    "name": "End User",
    "agent": "Agent Name", //agent name
    "agentImage": "iVBORw0KGgoAAAANSUhEUg...ruPfsj78onZEAAAAASUVORK5CYII=",
    "skill": "SkillName",
    "created": "2012-04-23T18:25:43.511Z"
  }
}

Potential Errors

Status Code	Failure
204 No Content	The chat session does not exist.

Starting a Session

POST /chat/queue

An endpoint to start a chat session and enter the chat queue. This requires a token received by completing a captcha.

Arguments

Send a ClientChatSessionRequest in the request body.

POST Body Breakdown

installationId: The chat installation ID
email: End user email
name: End user name
skill: The skill to queue for
recaptchaToken: The token received after completing a captcha challenge
customChatInfo: Some custom parameters that will show on the agent’s screen

{
  "installationId": "9c108bb3-8924-4234-a53c-be9ab284d4e3",
  "email": "[email protected]",
  "name": "End User",
  "skill": "SkillName",
  "recaptchaToken": "9c108bb3-8924",
  "customChatInfo": [
    { "name": "Parameter Display Name", "value": "Parameter Value" }
  ]
}

Response

A ChatSession object will be returned.

Response Breakdown

chatQueueType: Possible values are SERVERTOCLIENT, CLIENTTOSERVER, or QUEUESTATUS
id: Session ID
installationId: The chat installation ID
email: End user email
name: End user name
agent: Agent name
agentImage: Base 64 encoded image

{
  "sessionDetails": {
    "serverToClientQueue": {
      "url": "https://sqs.us-east-1.amazonaws.com/775407092955/mm-queue-054d867a-76da-44f3-b63a-1ca187398f6d",
      "arn": "arn:aws:sqs:us-east-1:775407092955:mm-queue-054d867a-76da-44f3-b63a-1ca187398f6d",
      "created": "2012-04-23T18:25:43.511Z",
      "lastUsed": " 2012-04-23T18:25:43.511Z",
      "chatQueueType": "SERVERTOCLIENT",
    },
    "clientToServerQueue": {
      "url": "https://sqs.us-east-1.amazonaws.com/775407092955/mm-queue-054d867a-76da-44f3-b63a-1ca187398f6d",
      "arn": "arn:aws:sqs:us-east-1:775407092955:mm-queue-054d867a-76da-44f3-b63a-1ca187398f6d",
      "created": "2012-04-23T18:25:43.511Z",
      "lastUsed": " 2012-04-23T18:25:43.511Z",
      "chatQueueType": "CLIENTTOSERVER",
    },
    "id": "9c108bb3-8924-4234-a53c-be9ab284d4e3",
    "installationId": "9c108bb3-8924-4234-a53c-be9ab284d4e3",
    "email": "[email protected]",
    "name": "End User",
    "agent": "Agent Name", //agent name
    "agentImage": "iVBORw0KGgoAAAANSUhEUg...ruPfsj78onZEAAAAASUVORK5CYII=",
    "skill": "SkillName",
    "created": "2012-04-23T18:25:43.511Z"
  }
}

POST /chat/apiqueue

An endpoint to start a chat session and enter the chat queue. This uses an API key rather than a captcha token, therefore bypassing the captcha requirement.

Arguments

Send a ClientChatSessionRequest in the request body.

POST Request Body Breakdown

installationId: The chat installation ID
email: End user email
name: End user name
skill: The skill to queue for
apiKey: The API key received from the Xima Software
customChatInfo: Some custom parameters that will show on the agent’s screen

{
  "installationId": "9c108bb3-8924-4234-a53c-be9ab284d4e3",
  "email": "[email protected]",
  "name": "End User",
  "skill": "SkillName",
  "apiKey": "9c108bb3-8924-4234-a53c-be9ab284d4e3",
  "customChatInfo": [
    { "name": "Parameter Display Name", "value": "Parameter Value" }
  ]
}

Response

A ChatSession object will be returned.

Response Breakdown

chatQueueType: Possible values are SERVERTOCLIENT, CLIENTTOSERVER, or QUEUESTATUS
id: Session ID
installationId: The chat installation ID
email: End user email
name: End user name
agent: Agent name
agentImage: Base 64 encoded image

{
  "sessionDetails": {
    "serverToClientQueue": {
      "url": "https://sqs.us-east-1.amazonaws.com/775407092955/mm-queue-054d867a-76da-44f3-b63a-1ca187398f6d",
      "arn": "arn:aws:sqs:us-east-1:775407092955:mm-queue-054d867a-76da-44f3-b63a-1ca187398f6d",
      "created": "2012-04-23T18:25:43.511Z",
      "lastUsed": " 2012-04-23T18:25:43.511Z",
      "chatQueueType": "SERVERTOCLIENT",
    },
    "clientToServerQueue": {
      "url": "https://sqs.us-east-1.amazonaws.com/775407092955/mm-queue-054d867a-76da-44f3-b63a-1ca187398f6d",
      "arn": "arn:aws:sqs:us-east-1:775407092955:mm-queue-054d867a-76da-44f3-b63a-1ca187398f6d",
      "created": "2012-04-23T18:25:43.511Z",
      "lastUsed": " 2012-04-23T18:25:43.511Z",
      "chatQueueType": "CLIENTTOSERVER",
    },
    "id": "9c108bb3-8924-4234-a53c-be9ab284d4e3",
    "installationId": "9c108bb3-8924-4234-a53c-be9ab284d4e3",
    "email": "[email protected]",
    "name": "End User",
    "agent": "Agent Name", //agent name
    "agentImage": "iVBORw0KGgoAAAANSUhEUg...ruPfsj78onZEAAAAASUVORK5CYII=",
    "skill": "SkillName",
    "created": "2012-04-23T18:25:43.511Z"
  }
}

Receiving Messages

Once a session has started, messages are sent to the chat widget over the serverToClientQueue defined in the ChatSession object. The serverToClientQueue is an AWS SQS queue. You can find documentation on reading messages off the queue here.

serverToClientQueue SQS Credentials

You will need AWS credentials to pull messages off the serverToClientQueue. Get these credentials by sending a GET request to https://mm-v1.ximasoftware.com/chat/queue/auth?installation-id=[your installation id here]

These credentials may change over time, so be sure to periodically query for them. The response is as follows:

{
    "sqsAccessKey": "<sqs aws access key>",
    "sqsSecretKey": "<sqs aws secret key>",
    "sqsRegion": "<sqs aws region>"
}

Possible Messages

The receivable message types are as follows:

ESTIMATED_WAIT_TIME

The estimated time left in queue until chat starts.

Message Breakdown

type: The message type
estimatedWait: English description of wait time

{
  "type": "ESTIMATED_WAIT_TIME",
  "estimatedWait": "about 2 minutes"
}

CHAT_STARTED

Sent when an agent is ready to chat.

Message Breakdown

type: The message type
agent: Agent name
agentBase64Image: Base 64 encoded image for the agent

{
  "type": "CHAT_STARTED",
  "agent": "Myles",
  "agentBase64Image": "iVBORw0KGgoAAAANSUhEUg...ruPfsjnZEAAAAASUVORK5CYII="
}

CHAT_TRANSFERRED

Sent when the end user is transferred to a new agent.

Message Breakdown

type: The message type
newAgent: The name of the new agent
newAgentImage: Base 64 encoded image for the new agent

{
  "type": "CHAT_TRANSFERRED",
  "newAgent": "Shawn",
  "newAgentImage": "iVBORw0KGgoAAAANSUhEUg...ruPfQfGsj7ZEAAAAASUVORK5CYII="
}

CHAT_TEXT

Chat message sent by the agent.

Message Breakdown

type: The message type
text: The text of the chat

{
  "type": "CHAT_TEXT",
  "text": "Hello, how can I help you today?"
}

AGENT_TYPING

Sent when the agent is typing a message or when the agent has stopped typing.

Message Breakdown

type: The message type
isTyping: This is whether the agent is typing or not. This option can be "True" or "False."

{
  "type": "AGENT_TYPING",
  "isTyping": "true"
}

TAKE_SCREENSHOT

Sent when the agent would like to take a screenshot of the end user's browser window.

Message Breakdown

type: The message type

{
  "type": "TAKE_SCREENSHOT"
}

CHAT_ENDED

Sent when the agent ends the chat.

Message Breakdown

type: The message type

{
  "type": "CHAT_ENDED"
}

FORCE_CLOSE

Sent when the agent is unexpectedly disconnected from the chat. This ends the chat.

Message Breakdown

type: The message type

{
  "type": "FORCE_CLOSE"
}

MULTIMEDIA_DOWN

Sent when the server goes offline. This is the customer's server, not the server hosted at https://mm-v1.ximasoftware.com. This ends the chat.

Message Breakdown

type: The message type

{
  "type": "MULTIMEDIA_DOWN"
}

Sending Messages

Messages sent from the chat widget are sent to endpoints on https://mm-v1.ximasoftware.com as POST requests with various messages in the request body, not over an SQS queue like the incoming messages. All endpoints respond with either a 204 No Content or a 200 OK.

POST /chat/still-here

Needs to be sent every 30 seconds to keep the chat alive.

Arguments

Send a JSON message in the request body.

Request Body Breakdown

chatSessionId: The chat session ID

{
  "chatSessionId": "9c108bb3-8924-4234-a53c-be9ab284d4e3"
}

POST /chat

Sent when the end user sends a message to the agent.

Arguments

Send a JSON message in the request body.

Request Body Breakdown

chatSessionId: The chat session ID
message: The text of the chat

{
  "chatSessionId": "9c108bb3-8924-4234-a53c-be9ab284d4e3",
  "message": "I have a question about model no. 24601."
}

POST /chat/focus

Sent when the end user clicks or interacts with the chat text box. It notifies the agent that their message was read.

Arguments

Send a JSON message in the request body.

Request Body Breakdown

chatSessionId: The chat session ID
focused: Indicates that the chat text box has been focused. This is always set to "True."

{
  "chatSessionId": "9c108bb3-8924-4234-a53c-be9ab284d4e3",
  "focused": "true"
}

POST /chat/typing

Sent when user starts or stops typing.

Arguments

Send a JSON message in the request body.

Request Body Breakdown

chatSessionId: The chat session ID
typing: A boolean to indicate whether the end user is typing or not

{
  "chatSessionId": "9c108bb3-8924-4234-a53c-be9ab284d4e3",
  "typing": "true"
}

Response

The server will respond with a 204 No Content.

POST /screenshot/notify

Sent when the customer accepts or denies the agent's screenshot request.

Arguments

Send a JSON message in the request body.

Request Body Breakdown

chatSessionId: The chat session ID
status: Whether the screenshot request is accepted or not. Possible values: ACCEPTED or REJECTED.
uuid: The screenshot ID. Only sent if the screenshot is accepted. To get this UUID, see POST /screenshot

{
  "chatSessionId": "9c108bb3-8924-4234-a53c-be9ab284d4e3",
  "status": "ACCEPTED",
  "uuid": "9c108bb3-8924-4234-a53c-be9ab284d4e3"
}

POST /screenshot

Used to upload a screenshot. The screenshot must be encoded as a base64 string. A screenshot UUID is returned.

Arguments

The POST request body should contain a base64 string representation of the image, prefixed by data:image/png;base64;. Currently the only supported file type is PNG.

data:image/png;base64;iVBORw0KGgoAAAANSUhEUgAAANwAAADcCAYAAAAbWs+BAAAGwElEQVR4Ae3cwZFbNxBFUY5rkrDTmKAUk5QT03Aa44U22KC7NHptw+DRikVAXf8fzC3u8Hj4R4AAAQIECBAgQIAAAQIECBAgQIAAAQIECBAgQIAAAQIECBAgQIAAAQIECBAgQIAAAQIECBAgQIAAAQIECBAgQIAAAQIECBAgQIAAgZzAW26USQT+e4HPx+Mz+RRvj0e0kT+SD2cWAQK1gOBqH6sEogKCi3IaRqAWEFztY5VAVEBwUU7DCNQCgqt9rBKICgguymkYgVpAcLWPVQJRAcFFOQ0jUAsIrvaxSiAqILgop2EEagHB1T5WCUQFBBflNIxALSC42scqgaiA4KKchhGoBQRX+1glEBUQXJTTMAK1gOBqH6sEogKCi3IaRqAWeK+Xb1z9iN558fHxcSPS9p2ezx/ROz4e4TtIHt+3j/61hW9f+2+7/+UXbifjewIDAoIbQDWSwE5AcDsZ3xMYEBDcAKqRBHYCgtvJ+J7AgIDgBlCNJLATENxOxvcEBgQEN4BqJIGdgOB2Mr4nMCAguAFUIwnsBAS3k/E9gQEBwQ2gGklgJyC4nYzvCQwICG4A1UgCOwHB7WR8T2BAQHADqEYS2AkIbifjewIDAoIbQDWSwE5AcDsZ3xMYEEjfTzHwiK91B8npd6Q8n8/oGQ/ckRJ9vvQwv3BpUfMIFAKCK3AsEUgLCC4tah6BQkBwB

POST /chat/end

Used to end the chat session. This request has no body. This also uses the browser session to find the relevant chatSessionId and ends the session.

Arguments

None

Updated about 2 months ago