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.

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.

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 CodeFailure

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