This document describes current Clinked chat implementation.

1. Connecting

A client can connect to URL https://pubsub.clinked.com/ using any Socket.IO client implementation.

1.1. Authentication

There are several client authentication types available. A client should also pass a subscribe query parameter with a list of topics to get notifications for separated by comma. In the following examples only the chat topic is used.

1.1.1. Using session id

/?auth_type=session&session={sessionId}&subscribe=chat

1.1.2. Using API auth access token

/?auth_type=token&token={token}&subscribe=chat

2. Chatting

2.1. Getting list of connected users

To get list of currently connected users a client should listen to buddies event and emit buddies-notify message. The server will push an array that contains chat id as first element and list of User objects as the second. This event will also trigger online status for a user, so make sure you always send it after connecting.

[
    "f4fb76e09624f7711f1214e1ba6e8942",
    [
        {
            "id": 123,
            "username": "richard.atkins",
            "name": "Richard Atkins"
        }
    ]
]

2.2. Stay online

In order for a user to always appear online it is important to emit be-here event every 30 seconds.

2.3. Sending a message

The message should be emitted as the chat-message event.

Table 1. Chat message fields
Parameter Description

conversation

Chat id

deliveryId

Message id. Can be a randomly generated UUID

body

Chat message body

type

Type of a message

properties

A list of additional properties

Table 2. Chat message types
Type Description

text

Send a chat message

update

Edit an existing chat message

type

Notify about the typing status

Example of a message
{
    "conversation": "f4fb76e09624f7711f1214e1ba6e8942",
    "deliveryId": "99d53ce1-f0e5-45b7-9a61-13676e5b9df6",
    "body": "Hello Chat!",
    "type": "text", (1)
    "properties": []
}
1 Text message type
Example of a typing status message
{
    "conversation": "0274f93945c7ac8fcf77e6ee00a17f72",
    "deliveryId": "99d53ce1-f0e5-45b7-9a61-13676e5b9df6",
    "body": "yes", (1)
    "type": "type", (2)
    "properties": []
}
1 Set to yes when typing, otherwise no
2 Typing message type

2.4. Receiving messages

A client should subscribe to chat-message events.

Table 3. Received message fields
Parameter Description

conversation

Chat id

deliveryId

Message id. Can be a randomly generated UUID

body

Chat message body

type

Type of a message

properties

A list of additional properties

source

Data about the user who sent a message

read

Flag that indicates if a message is read or not

dateReceived

Message date in ISO-8601 format

properties

Additional message properties, if it containts selfie it means that it has been sent by a current user

Received message example
{
    "conversation": "f4fb76e09624f7711f1214e1ba6e8942",
    "deliveryId": "99d53ce1-f0e5-45b7-9a61-13676e5b9df6",
    "body": "Hello Chat!",
    "type": "text",
    "properties": [
        "selfie"
    ],
    "source": {
        "name": "Richard",
        "id": "uri:user:richard:24438",
        "properties": []
    },
    "read": true,
    "dateReceived": "2017-07-10T12:42:13.352+0000"
}

2.6. Handling unread messages

Once connected the server will push a list of chats with unread messages as the unread event.

Example unread event message
[
    {
        "lastMessageReceived": null,
        "dateCreated": 1499072111006,
        "name": "The best group in the world",
        "changeable": true,
        "id": "1210b21bbc5032decd781a1d59ff943a"
    }
]