# CPE#4 - Basic chats ## 0. Table of content - [CPE#4 - Basic chats](#cpe4---basic-chats) - [0. Table of content](#0-table-of-content) - [1. Introduction](#1-introduction) - [2. Requirements](#2-requirements) - [3. Message type identifiers](#3-message-type-identifiers) - [4. Errors](#4-errors) - [4.1. Error types](#41-error-types) - [5. Event types](#5-event-types) - [5.1. Media types](#51-media-types) - [6. Use cases](#6-use-cases) - [6.1. Exchanging messages](#61-exchanging-messages) - [6.2. Exchanging media](#62-exchanging-media) - [6.3. Read messages](#63-read-messages) - [6.4. Typing message](#64-typing-message) - [6.5. Message history API](#65-message-history-api) - [6.5.1. History retrieving](#651-history-retrieving) - [7. Business Rules](#7-business-rules) - [7.1. Typing message notification](#71-typing-message-notification) - [7.2. Message/Media ID](#72-messagemedia-id) - [8. JSON Schema](#8-json-schema) - [Event Entity](#event-entity) - [Content sections](#content-sections) - [Send message (`urn:cadmium:chat:message`)](#send-message-urncadmiumchatmessage) - [Request](#request) - [Response](#response) - [Read message notification (`urn:cadmium:chat:read`)](#read-message-notification-urncadmiumchatread) - [Request](#request-1) - [Edit message notification (`urn:cadmium:chat:message:edit`)](#edit-message-notification-urncadmiumchatmessageedit) - [Request](#request-2) - [Delete message notification (`urn:cadmium:chat:message:delete`)](#delete-message-notification-urncadmiumchatmessagedelete) - [Request](#request-3) - [Sync history of user chats (`urn:cadmium:chat:history:sync`)](#sync-history-of-user-chats-urncadmiumchathistorysync) - [Request](#request-4) - [Response](#response-1) ## 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:chat:message` - regular message - `urn:cadmium:chat:read` - read message notification - `urn:cadmium:chat:typing` - typing message notification - `urn:cadmium:chat:message:edit` - edit message notification - `urn:cadmium:chat:message:delete` - delete message notification - `urn:cadmium:chat:history:sync` - sync history of user chats ## 4. Errors - Ratelimit system: disabled - Authorization: enabled ### 4.1. Error types - `urn:cadmium:chat: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. Event types - `urn:cadmium:chat:event:message` - message with text and optional media ### 5.1. Media types - `urn:cadmium:chat:media:photo` - a photo - `urn:cadmium:chat:media:audio` - an audio or voice message - `urn:cadmium:chat:media:video` - a video or rounded video message - `urn:cadmium:chat:media:file` - any other file type - `urn:cadmium:chat:media:sticker` - a sticker - `urn:cadmium:chat:media:gif` - an animated GIF ## 6. Use cases ### 6.1. Exchanging messages 1. C1->S - Sending message: ```json { "id": "abcd", "type": "urn:cadmium:chat:message", "to": ["@user2@cadmium.org"], "payload": { "type": "urn:cadmium:chat:event:message", "content": { "text": "hello world", } } } ``` S->C1 - Successful response: ```json { "id": "abcd", "type": "urn:cadmium:chat:message", "from": "cadmium.org", "ok": true, "payload": { "eventID": "3b5135a5-aff5-4396-a629-a254f383e82f", "originServerTimestamp": 1599327584 } } ``` S->C1 - **Error** response: ```json { "id": "abcd", "type": "urn:cadmium:chat:message", "from": "cadmium.org", "ok": false, "payload": { "errID": "urn:cadmium:chat:private:banned", "errText": "The user has banned you" } } ``` 2. S->C2: ```json { "id": "abcd", "type": "urn:cadmium:chat:message", "from": "@user1@cadmium.im", "ok": true, "payload": { "eventID": "3b5135a5-aff5-4396-a629-a254f383e82f", "originServerTimestamp": 1599327584, "type": "urn:cadmium:chat:event:message", "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: C1->S: ```json { "id": "abcd", "type": "urn:cadmium:chat:message", "to": ["@user2@cadmium.im"], "payload": { "type": "urn:cadmium:chat:event:message", "content": { "text": "", "media": [ { "id": "4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67@content.cadmium.im" } ] } } } ``` S->C1: ```json { "id": "abcd", "type": "urn:cadmium:chat: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: S->C2: ```json { "id": "defg", "type": "urn:cadmium:chat:message", "from": "@user1@cadmium.im", "ok": true, "payload": { "messageID": "7a1b9a72-1677-4476-9b22-ef7fdbcff52e", "originServerTimestamp": 1599329232, "type": "urn:cadmium:chat:event:message", "content": { "text": "", "media": [ { "id": "4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67@content.cadmium.im", "type": "urn:cadmium:chat:media:photo", "attrs": { "width": 512, "height": 512 }, "size": 96413, // 96kb } ] } } } ``` ### 6.3. Read messages 1. Read message ```json { "id": "abcd", "type": "urn:cadmium:chat:read", "to": ["@user1@cadmium.org"], "payload": { "messageID": "7a1b9a72-1677-4476-9b22-ef7fdbcff52e", } } ``` Response: ```json { "id": "abcd", "type": "urn:cadmium:chat:read", "from": "cadmium.im", "ok": true, "payload": {} } ``` 2. Receive notification about message reading on other side: ```json { "id": "defg", "type": "urn:cadmium:chat:read", "from": "@user2@cadmium.im", "ok": true, "payload": { "messageID": "7a1b9a72-1677-4476-9b22-ef7fdbcff52e" } } ``` ### 6.4. Typing message 1. Typing message ```json { "id": "abcd", "type": "urn:cadmium:chat:typing", "to": ["@user1@cadmium.org"], } ``` 2. Receive notification about typing message on other side: ```json { "id": "defg", "type": "urn:cadmium:chat:typing", "from": "@user2@cadmium.im", "ok": true } ``` ### 6.5. Message history API #### 6.5.1. History retrieving ## 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 ### Event Entity ```typescript interface Event { id: EntityID; // the message id (stored in chat timeline) - not required when sending type: string; // the type of event originServerTimestamp: number; // unix timestamp of received message on the origin server (not required when sending) content: Content; // the payload of message (depends on type) } interface Content {} ``` #### Content sections - `urn:cadmium:chat:events:types:message`: ```typescript interface MessageContent : Content { text: string; // the text (body) of message mentioned?: boolean; // is current entity was mentioned in this message media?: Media[]; // media content forwardedFrom?: EntityID | string; // entity from which this message was forwarded (may be hidden, so instead client need to show the display name of entity) replyTo?: EntityID; // message id to which this message is replying } 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 } interface GeolocationAttrs : MediaAttrs { lat: number; // the GPS latitude lon: number; // the GPS longitude } ``` ### Send message (`urn:cadmium:chat:message`) #### Request ```typescript interface SendMessageReq { type: string; content: Content; } ``` #### Response ```typescript interface SendMessageResponsePayload { id: EntityID; // the message id (stored in chat timeline) originServerTimestamp: number; // unix timestamp of sent message on the origin server } ``` ### Read message notification (`urn:cadmium:chat:read`) #### Request ```typescript interface ReadMessageNotif { eventID: EntityID; // the read message id } ``` ### Edit message notification (`urn:cadmium:chat:message:edit`) #### Request ```typescript interface EditMessageNotif { eventID: EntityID; // edited message id updatedContent: Content; // new content of message } ``` ### Delete message notification (`urn:cadmium:chat:message:delete`) #### Request ```typescript interface DeleteMessageNotif { eventID: EntityID; // deleted message id } ``` ### Sync history of user chats (`urn:cadmium:chat:history:sync`) #### Request ```typescript interface ChatsHistorySyncReq { since: EntityID; // event from which need to sync the history limit: number; // count of events which need to return includeChatInfo: boolean; // include chat/user info mentioned in events into response chatID?: EntityID; // get history of specific chat direction?: SyncDirection; // in case of getting history of specific chat } enum SyncDirection { Up = "UP", // previous events from 'since' event Down = "DOWN" // next events from 'since' event } ``` #### Response ```typescript interface ChatsHistorySyncResp { nextBatch: EntityID; // next 'since' value for client events: Event[]; // synced events chats?: Chat[]; // chats mentioned in events users?: User[]; // users mentioned in events } interface Event { eventID: EntityID; // event id in timeline from: EntityID; // event author chatID: EntityID; // related chat id type: string; // type of event timestamp: number; // origin timestamp of event originServer: EntityID; // origin server author of event content: Content; // content of event } ```