cadmium-im/cadmium-docs-legacy
1
0
Fork 0
mirror of https://github.com/cadmium-im/cadmium-docs-legacy.git synced 2024-11-25 11:52:22 +00:00
Code Issues Projects Releases Wiki Activity
f78c12a8b0
cadmium-docs-legacy/CPEs/proposed/CPE4 - Basic chats.md
ChronosX88 8a83844dfc
Slightly restructure message entity in CPE4
2020-12-26 23:22:47 +04:00

9.3 KiB
Raw Blame History

CPE#4 - 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:geolocation - message with geolocation (coordinates)

5.1. Media types

  • urn:cadmium:chats:media:photo - a photo
  • urn:cadmium:chats:media:audio - an audio or voice message
  • urn:cadmium:chats:media:video - a video or rounded video message
  • urn:cadmium:chats:media:file - any other file type
  • urn:cadmium:chats:media:sticker - a sticker
  • urn:cadmium:chats:media:gif - an animated GIF

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 Content Service (explanation out of scope of this document)

  2. Send message containing the metadata of uploaded media:

     {
     "id": "abcd",
     "type": "urn:cadmium:chats:message",
     "to": ["@user2@cadmium.im"],
     "payload": {
         "type": "urn:cadmium:chats:message-types:general",
         "content": {
             "text": "",
             "media": [
                 {
                     "id": "4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67@content.cadmium.im"
                 }
             ]
         }

     }
 }

    Response:

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

    Note: The Cadmium server will validate media ID which was provided by client. If it doesn't exist or invalid, server will respond with corresponding error.

  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": [
                 {
                     "id": "4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67@content.cadmium.im",
                     "type": "urn:cadmium:chats:media:photo",
                     "attrs": {
                         "width": 512,
                         "height": 512 
                     },
                     "size": 96413, // 96kb
                 }
             ]
         }
     }
 }

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:typing",
    "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.

7.2. Message/Media ID

  • This is typically Federated Entity ID of message/media (as described and reserved in core specs) which was stored in server's database/content service storage.

8. JSON Schema

Message (urn:cadmium:chats:message)

Request:

interface MessagePayload {
    messageID?: EntityID; // the message id (stored in chat timeline) - not required when sending
    type: string; // the type of message
    replyTo?: EntityID; // message id to which this message is replying
    originServerTimestamp?: number; // unix timestamp of received message on the origin server (not required when sending)
    forwardedFrom?: EntityID | string; // entity from which this message was forwarded (may be hidden, so instead client need to show the display name of entity)
    content: Content // the payload of message (depends on type)
}

Response:

interface SendMessageResponsePayload {
    messageID: EntityID; // 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
    mentioned?: boolean; // is current entity was mentioned in this message
    media?: Media[]; // media content
}

interface Media {
    id: string; // media ID
    type: string; // type of media
    size: number; // size of media in bytes
    fileName?: string; // filename of media (with optional extension by dot)
    attrs: MediaAttrs; // media payload (additional attributes)
}

// Media attributes definitions

interface MediaAttrs {}

// urn:cadmium:chats:media:audio
interface AudioAttrs : MediaAttrs {
    voice: bool; // whether it is voice message
    duration: number; // duration of audio
    title?: string; // audio title
    artist?: string; // audio artist
    voiceWaveForm?: []byte; // voice wave form
}

// urn:cadmium:chats:media:sticker
interface StickerAttrs : MediaAttrs {
    associatedEmoji: string; // the associated emoji with this 
    stickerSetID: string; // id of sticker set which is associated with this sticker
    isAnimated: boolean; // is client need to animate this sticker
}

// urn:cadmium:chats:media:video
interface VideoAttrs : MediaAttrs {
    isVideoMessage: bool; // is this a rounded video message
    duration: number; // duration of video
    width: number; // width of video
    height: number; // height of video
}

// urn:cadmium:chats:media:photo
interface PhotoAttrs : MeditAttrs {
    width: number; // width of photo
    height: number; // height of photo
}

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

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

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

interface ReadMessageNotifPayload {
    messageID: EntityID; // the message id of read message
}