WebSocket API

WebSockets support full-duplex communication. After establishing a WebSocket connection. you can use any of the methods described in the Chat section of the REST API.

This provides performance improvements on slower connections since the TCP connection has already been established. To send a request over WebSocket, it should be in JSON RPC format, with the first parameter being a JSON Object that contains the actual parameters. The id parameter can be used to identify the response to the request message from other messages.

The following is a sample message to make a call to sendMessage:

{
    "method":"sendMessage",
    "params":[
        {
            "ChatKey":"euzei4ohF0ahng8ohhoh2Daekaigae6l",
            "ChatMessageID":"312081676718313",
            "Name":"Jeff",
            "Message":"Hello World!"
        }
    ],
    "id":"11498"
}

The response is as follows:

{
    "result":
    {
        "Status":"success"
    },
    "error": null,
    "id":"11498"
}

Long Poll Sockets

WebSocket is a relatively new technology, so not all proxies support them. To improve the reliability of the connection, it is recommended (although optional) to implement a long poll fallback for events when WebSocket fails to establish a connection. The long poll socket is a regular HTTP GET request that is inactive until the server has data to send back to the client. The server sends messages in a JSON array and then closes the connection. If the server expects the client to re-establish the connection after processing the messages then the last message sent is always a "reconnect" message. Please note that the long poll connection is one-way messaging, so any communication from the client to the server must occur through REST messages.

To connect to a long poll socket, use the LongPollURL value returned in the response for createChat. Take this LongPollURL value and append the LastMessageID to the URL. The LastMessageID is the "id" value of the last message that was received over the previous long poll socket connection. If no message was received previously, then its value is zero. After connecting to the server, the connection is blocked until the server sends a JSON array of RPC messages. Connection to the server can then be closed. The last message in the array is generally a "reconnect" message. The long poll connection should be re-established after appending the last message ID in the batch of messages. "Heartbeat" messages can be ignored.

A long poll connection can be established at the same time (or after a short delay) as a web socket connection. If the BoldChat server gets two connections from the same client, the WebSocket connection has priority, and closes the long poll connection without sending a reconnect message.

[
{"method":"updateTyper","params":[{"PersonID":"5701072127270","Values":{"IsTyping":true}}]},
{"method":"reconnect","params":[],"id":null}
]

Socket Maintenance

There are some maintenance messages that the server sends over the WebSocket connection to ensure its health and to move the connection to a new server if necessary.

connect

After establishing WebSocket connection, a connect message should be sent to notify the server that you are ready to start receiving data, and pass the last message ID that you received from the server:

Parameter	Type	Required
LastMessageID	string id	yes

{
    "method":"connect",
    "params":[
        {
            "LastMessageID": "0"
        }
    ],
    "id":"11497"
}

redirect

WebSocket should disconnect and then reconnect at a new address. This address should be stored for future use.

Parameter	Type	Required
WebSocketURL	string	The new URL that should be connected.

{
    "method":"redirect",
    "params":
    [
        {
            "WebSocketURL":"wss://ows.boldchat.com/?param=blahblah"
        }
    ],
    "id":null
}

heartbeat

Heartbeat messages ensure that the connection stays open between the two parties.

{
    "method":"heartbeat",
    "params": null,
    "id":"20828"
}

After receiving a heartbeat message, send back a JSON object with a Response key of ack as follows:

{
    "result":
    {
        "Response":"ack"
    },
    "error": null,
    "id": "20828"
}

reconnect

The WebSocket connection should be closed and then reconnected at the last address received.

{
    "method":"reconnect"
    "params":[],
    "id":null
}

reset

The WebSocket connection should be completely reset. After receiving this message, reset the LastMessageID to 0 and make another call to startChat to reconnect with the new address.

{
    "method":"reset"
    "params":[],
    "id":null
}

closed

The chat has either been ended/closed by the agent, or it has been disconnected so long that upon reconnection, the chat was already closed. Finish the chat and handle any post-chat logic with the finishChat method.

{
    "method":"closed"
    "params":[],
    "id":null
}