cadmium-docs-legacy/protocol-spec/private-chats.md

Private chats

1. Introduction

This extension is intended for organizing private chat between two users.

2. Message type identifiers

• urn:cadmium:chats:private:message - regular message
• urn:cadmium:chats:private:read - read message system
• urn:cadmium:chats:private:typing - typing message system

3. Errors

• Ratelimit system: disabled
• Authorization: enabled

4. Chat message types

• urn:cadmium:chats:message-types:general - message with text and optional media
• urn:cadmium:chats:message-types:audio - audio message
• urn:cadmium:chats:message-types:geolocation - message with geolocation (coordinates)

5. Use cases

5.1. Exchanging messages

1. Sending message:

   {
       "id": "abcd",
       "type": "urn:cadmium:chats:private:message",
       "to": ["@user2@cadmium.org"],
       "payload": {
           "type": "urn:cadmium:chats:message-types:general",
           "content": {
               "text": "hello world",
           }
       }
   }
   

   Successful response:

   {
       "id": "abcd",
       "type": "urn:cadmium:chats:private:message",
       "from": "cadmium.org",
       "ok": true,
       "payload": {
           "messageID": "3b5135a5-aff5-4396-a629-a254f383e82f",
           "originServerTimestamp": 1599327584
       }
   }
   

   Error response:

   {
       "id": "abcd",
       "type": "urn:cadmium:chats:private:message",
       "from": "cadmium.org",
       "ok": false,
       "payload": {
           "errID": "banned",
           "errText": "The user banned you"
       }
   }
   

2. Receiving message on other side:

   {
       "id": "abcd",
       "type": "urn:cadmium:chats:private:message",
       "from": "@user1@cadmium.im",
       "ok": true,
       "payload": {
           "messageID": "3b5135a5-aff5-4396-a629-a254f383e82f",
           "originServerTimestamp": 1599327584,
           "type": "urn:cadmium:chats:message-types:general",
           "content": {
               "text": "hello world",
           }
       }
   }
   

5.2. Exchanging media

1. Upload the media to HTTP Upload service (explanation out of scope of this document)

2. Send message containing the URL of uploaded media:

    {
        "id": "abcd",
        "type": "urn:cadmium:chats:private:message",
        "to": ["@user2@cadmium.org"],
        "payload": {
            "type": "urn:cadmium:chats:message-types:general",
            "content": {
                "text": "",
                "media": [
                    {
                        "url": "https://upload.cadmium.im/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67",
                        "mimeType": "image/jpeg"
                    }
                ]
            }
   
        }
    }
   

   Response:

   {
        "id": "abcd",
        "type": "urn:cadmium:chats:private:message",
        "from": "cadmium.org",
        "ok": true,
        "payload": {
            "messageID": "7a1b9a72-1677-4476-9b22-ef7fdbcff52e",
            "originServerTimestamp": 1599329232
        }
    }
   

3. Receive message with media on other side:

   {
        "id": "defg",
        "type": "urn:cadmium:chats:private:message",
        "from": "@user1@cadmium.im",
        "ok": true,
        "payload": {
            "messageID": "7a1b9a72-1677-4476-9b22-ef7fdbcff52e",
            "originServerTimestamp": 1599329232,
            "type": "urn:cadmium:chats:message-types:general",
            "content": {
                "text": "",
                "media": [
                    {
                        "url": "https://upload.cadmium.im/4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67",
                        "mimeType": "image/jpeg"
                    }
                ]
            }
        }
    }
   

5.3. Read messages

1. Read message

   {
       "id": "abcd",
       "type": "urn:cadmium:chats:private:read",
       "to": ["@user1@cadmium.org"],
       "payload": {
           "messageID": "7a1b9a72-1677-4476-9b22-ef7fdbcff52e",
       }
   }
   

   Response:

   {
       "id": "abcd",
       "type": "urn:cadmium:chats:private:read",
       "from": "cadmium.im",
       "ok": true,
       "payload": {}
   }
   

2. Receive notification about message reading on other side:

   {
       "id": "defg",
       "type": "urn:cadmium:chats:private:read",
       "from": "@user2@cadmium.im",
       "ok": true,
       "payload": {
           "messageID": "7a1b9a72-1677-4476-9b22-ef7fdbcff52e"
       }
   }
   

5.3. Typing messages

1. Typing message

   {
       "id": "abcd",
       "type": "urn:cadmium:chats:private:typing",
       "to": ["@user1@cadmium.org"],
       "payload": {
           "status": "typing",
       }
   }
   

2. Receive notification about typing message on other side:

   {
       "id": "defg",
       "type": "urn:cadmium:chats:private:read",
       "from": "@user2@cadmium.im",
       "ok": true,
       "payload": {
           "status": "typing"
       }
   }
   

3. Pause typing message (e.g. when user stops abruptly typing message or just sent the message)

   {
       "id": "abcd",
       "type": "urn:cadmium:chats:private:typing",
       "to": ["@user1@cadmium.org"],
       "payload": {
           "status": "paused",
       }
   }
   

4. Receive notification pausing typing message on other side:

   {
       "id": "defg",
       "type": "urn:cadmium:chats:private:read",
       "from": "@user2@cadmium.im",
       "ok": true,
       "payload": {
           "status": "paused"
       }
   }
   

6. Business Rules

None.

7. JSON Schema

Send message (urn:cadmium:chats:private:message)

Request:

interface SendMessagePayload {
    type: string; // the type of message
    reply?: string; // message id on which this message is replying
    content: Content // the payload of message (depends on type)
}

Response:

interface SendMessageResponsePayload {
    messageID: string; // the message id (stored in chat timeline)
    originServerTimestamp: number // unix timestamp of sent message on the origin server
}

Content sections

• urn:cadmium:chats:message-types:general:

  interface GeneralMessageContent {
      text: string; // the text (body) of message
      media?: Media[]; // media content
  }
  
  interface Media {
      url: string; // url of media (where it stores)
      mimeType: string; // mime type of media
  }
  

• urn:cadmium:chats:message-types:audio:

  interface AudioMessageContent {
      url: string; // the url of audio message
  }
  

• urn:cadmium:chats:message-types:geolocation:

  interface GeolocationMessageContent {
      lat: number; // the GPS latitude
      lon: number; // the GPS longitude
  }
  

Receive message (urn:cadmium:chats:private:message)

interface ReceiveMessagePayload {
    messageID: string; // the id of received message
    originServerTimestamp: number; // unix timestamp of received message on the origin server
    type: string; // the type of message
    reply?: string; // message id on which this message is replying
    content: Content; // the payload of message (depends on type)
}

Read message (urn:cadmium:chats:private:read)

Request:

interface ReadMessagePayload {
    messageID: string; // the message id of read message
}

Response:

None.

Receive read message notification (urn:cadmium:chats:private:read)

interface ReceiveReadMessageNotifPayload {
    messageID: string; // the message id of read message
}

Typing message (urn:cadmium:chats:private:typing)

Request:

interface TypingMessagePayload {
    status: TypingStatus; // the status of the typing
}

enum TypingStatus {
    typing,
    paused
}

Response:

None.

Receive read message notification (urn:cadmium:chats:private:typing)

interface TypingMessageNotifPayload {
    status: TypingStatus; // the status of the typing
}