Chat events (Socket.IO)

Interacting with the Karaz Platform realtime chat system is done using the Socket.IO framework (v4), the docs for which can be found here. Skim through the documentation to learn how to:

• Establish a connection with a Socket.IO server
• Pass metadata to the Socket.IO server
• Register listeners for events
• Emit payloads to the Socket.IO server

...among other things using their language specific SDKs.

Here is an Android specific guide on how to use Socket.IO, and here is an iOS specific guide.

Events

Events are tagged in this guide by one of two categories: Client Event or Server Event.

We define Client Events as events that are meant for the client to listen to. The client needs to register a listener for each event. When the server emits a payload to the client, these listeners will be triggered. The schema of the received payload will depend on the event, and are outlined below. As previously mentioned, every Client Event in this guide is tagged with the Client Event tag.

We define Server Events as events that are meant for the server to listen to, and for clients to send payloads on. When the client emits a payload to the server, they need to specify the event name. The schema of this payload will depend on the event. As previously mentioned, every Server Event in this guide is tagged with the Server Event tag.

Rooms & Sessions

Since we're characterising the term "room" as the information about the room that is stored on the database, we need a word to describe the ephemeral sessions where the members of a room can communicate in realtime. We're simply calling these websocket sessions, or "sessions" for short.

Every session is uniquely identified by a key. This key is generated using the room's ID and a secret stored on the server. Multiple users can be connected to the same session, and a single user can connect to multiple sessions.

We refer to other users in a session as peers.

Intended usage

Users must hit our REST API for session keys. They will only receive keys for rooms they are a member of, with the exception of when they are creating a room. In this case, they can simply request our REST API to create a room, which will return a key that the client can use to create a session. They must then put these keys in their message payloads to tell the server which session a message is for.

Headers

The client must send the following required headers when first connecting to the Socket.IO server:

Join sessions

{
    "roomKeys": [
      "NdiOkCerFQCJyIXTqQo4cArULFzRnQuIvq1+8EjIf0=", 
      "YnbTbghNRFQCJyIXTqQo4cArULFzRnQuIvq1+RhrllQ="
    ]
}

Add peers

{
    "roomKey": "YnbTbghNRFQCJyIXTqQo4cArULFzRnQuIvq1+RhrllQ=",
    "userIDs": ["D4c7p43FkVmElcbAAAAF", "tTlSu7juwfKFiMkEAAAB"]
}

Leave session

{
    "roomKey": "YnbTbghNRFQCJyIXTqQo4cArULFzRnQuIvq1+RhrllQ=",
}

Send message

{
    "roomKey": "YnbTbghNRFQCJyIXTqQo4cArULFzRnQuIvq1+RhrllQ=",
    "senderName": "John Doe",
    "type": "file",
    "text": "Hello World!",
    "file": "https://example.com/file.txt",
    "image": "",
    "createdAt": 1234567890
}

Added to session

{
    "roomKey": "YnbTbghNRFQCJyIXTqQo4cArULFzRnQuIvq1+RhrllQ=",
}

Peers joined session

{
    "online": ["D4c7p43FkVmElcbAAAAF", "tTlSu7juwfKFiMkEAAAB"],
    "offline": ["pqs3MKKRDvfV7gOAAAAB"]
}

Peer left room

{
    "roomKey": "YnbTbghNRFQCJyIXTqQo4cArULFzRnQuIvq1+RhrllQ=",
    "userID": "D4c7p43FkVmElcbAAAAF"
}

Message sent

{
    "roomKey": "YnbTbghNRFQCJyIXTqQo4cArULFzRnQuIvq1+RhrllQ=",
    "senderID": "D4c7p43FkVmElcbAAAAF",
    "senderName": "John Doe",
    "type": "file",
    "text": "Hello World!",
    "file": "https://example.com/file.txt",
    "image": null,
    "createdAt": 1234567890
}

Peer went offline

{
    "userID": "D4c7p43FkVmElcbAAAAF"
}