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

Basic chats

1. Introduction

This extension is intended for organizing chats between some entities.

2. Requirements

• Exchanging text messages
• Typing status
• Message reading
• Sharing files/media
• Forwards and replies to messages
• Stickers/GIF
• Message reactions

3. Message type identifiers

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

4. Errors

• Ratelimit system: disabled
• Authorization: enabled

4.1. Error types

• urn:cadmium:chats:private:banned - Sending messages to user is prohibited, because he banned the sender of current message - in case if we send the message to user entity.

5. 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)

6. Use cases

6.1. Exchanging messages

1. Sending message:

   {
       "id": "abcd",
       "type": "urn:cadmium:chats: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:message",
       "from": "cadmium.org",
       "ok": true,
       "payload": {
           "messageID": "3b5135a5-aff5-4396-a629-a254f383e82f",
           "originServerTimestamp": 1599327584
       }
   }
   

   Error response:

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

2. Receiving message on other side:

   {
       "id": "abcd",
       "type": "urn:cadmium:chats: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",
           }
       }
   }
   

6.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: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: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: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"
                    }
                ]
            }
        }
    }
   

6.3. Read messages

1. Read message

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

   Response:

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

2. Receive notification about message reading on other side:

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

6.4. Typing message

1. Typing message

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

2. Receive notification about typing message on other side:

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

7. Business Rules

7.1. Typing message notification

• Client sends typing notification message every second when he is typing. If there is no notifications about typing more than one second then consider that user is stopped the typing.

8. JSON Schema

Send message (urn:cadmium:chats: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: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:read)

Request:

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

Response:

None.

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

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