mirror of
https://github.com/cadmium-im/cadmium-docs-legacy.git
synced 2024-11-09 12:11:03 +00:00
Restructurize Basic Chat document, describe history sync
This commit is contained in:
parent
f78c12a8b0
commit
18f52fcfde
@ -1,5 +1,42 @@
|
|||||||
# CPE#4 - Basic chats
|
# 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
|
## 1. Introduction
|
||||||
|
|
||||||
This extension is intended for organizing chats between some entities.
|
This extension is intended for organizing chats between some entities.
|
||||||
@ -16,9 +53,12 @@ This extension is intended for organizing chats between some entities.
|
|||||||
|
|
||||||
## 3. Message type identifiers
|
## 3. Message type identifiers
|
||||||
|
|
||||||
- `urn:cadmium:chats:message` - regular message
|
- `urn:cadmium:chat:message` - regular message
|
||||||
- `urn:cadmium:chats:read` - read message system
|
- `urn:cadmium:chat:read` - read message notification
|
||||||
- `urn:cadmium:chats:typing` - typing message system
|
- `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
|
## 4. Errors
|
||||||
|
|
||||||
@ -27,35 +67,34 @@ This extension is intended for organizing chats between some entities.
|
|||||||
|
|
||||||
### 4.1. Error types
|
### 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.
|
- `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. Chat message types
|
## 5. Event types
|
||||||
|
|
||||||
- `urn:cadmium:chats:message:types:general` - message with text and optional media
|
- `urn:cadmium:chat:event:message` - message with text and optional media
|
||||||
- `urn:cadmium:chats:message:types:geolocation` - message with geolocation (coordinates)
|
|
||||||
|
|
||||||
### 5.1. Media types
|
### 5.1. Media types
|
||||||
|
|
||||||
- `urn:cadmium:chats:media:photo` - a photo
|
- `urn:cadmium:chat:media:photo` - a photo
|
||||||
- `urn:cadmium:chats:media:audio` - an audio or voice message
|
- `urn:cadmium:chat:media:audio` - an audio or voice message
|
||||||
- `urn:cadmium:chats:media:video` - a video or rounded video message
|
- `urn:cadmium:chat:media:video` - a video or rounded video message
|
||||||
- `urn:cadmium:chats:media:file` - any other file type
|
- `urn:cadmium:chat:media:file` - any other file type
|
||||||
- `urn:cadmium:chats:media:sticker` - a sticker
|
- `urn:cadmium:chat:media:sticker` - a sticker
|
||||||
- `urn:cadmium:chats:media:gif` - an animated GIF
|
- `urn:cadmium:chat:media:gif` - an animated GIF
|
||||||
|
|
||||||
## 6. Use cases
|
## 6. Use cases
|
||||||
|
|
||||||
### 6.1. Exchanging messages
|
### 6.1. Exchanging messages
|
||||||
|
|
||||||
1. Sending message:
|
1. C1->S - Sending message:
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"id": "abcd",
|
"id": "abcd",
|
||||||
"type": "urn:cadmium:chats:message",
|
"type": "urn:cadmium:chat:message",
|
||||||
"to": ["@user2@cadmium.org"],
|
"to": ["@user2@cadmium.org"],
|
||||||
"payload": {
|
"payload": {
|
||||||
"type": "urn:cadmium:chats:message:types:general",
|
"type": "urn:cadmium:chat:event:message",
|
||||||
"content": {
|
"content": {
|
||||||
"text": "hello world",
|
"text": "hello world",
|
||||||
}
|
}
|
||||||
@ -63,48 +102,48 @@ This extension is intended for organizing chats between some entities.
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
**Successful response**:
|
S->C1 - Successful response:
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"id": "abcd",
|
"id": "abcd",
|
||||||
"type": "urn:cadmium:chats:message",
|
"type": "urn:cadmium:chat:message",
|
||||||
"from": "cadmium.org",
|
"from": "cadmium.org",
|
||||||
"ok": true,
|
"ok": true,
|
||||||
"payload": {
|
"payload": {
|
||||||
"messageID": "3b5135a5-aff5-4396-a629-a254f383e82f",
|
"eventID": "3b5135a5-aff5-4396-a629-a254f383e82f",
|
||||||
"originServerTimestamp": 1599327584
|
"originServerTimestamp": 1599327584
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
**Error response**:
|
S->C1 - **Error** response:
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"id": "abcd",
|
"id": "abcd",
|
||||||
"type": "urn:cadmium:chats:message",
|
"type": "urn:cadmium:chat:message",
|
||||||
"from": "cadmium.org",
|
"from": "cadmium.org",
|
||||||
"ok": false,
|
"ok": false,
|
||||||
"payload": {
|
"payload": {
|
||||||
"errID": "urn:cadmium:chats:private:banned",
|
"errID": "urn:cadmium:chat:private:banned",
|
||||||
"errText": "The user banned you"
|
"errText": "The user has banned you"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
2. Receiving message on other side:
|
2. S->C2:
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"id": "abcd",
|
"id": "abcd",
|
||||||
"type": "urn:cadmium:chats:message",
|
"type": "urn:cadmium:chat:message",
|
||||||
"from": "@user1@cadmium.im",
|
"from": "@user1@cadmium.im",
|
||||||
"ok": true,
|
"ok": true,
|
||||||
"payload": {
|
"payload": {
|
||||||
"messageID": "3b5135a5-aff5-4396-a629-a254f383e82f",
|
"eventID": "3b5135a5-aff5-4396-a629-a254f383e82f",
|
||||||
"originServerTimestamp": 1599327584,
|
"originServerTimestamp": 1599327584,
|
||||||
"type": "urn:cadmium:chats:message:types:general",
|
"type": "urn:cadmium:chat:event:message",
|
||||||
"content": {
|
"content": {
|
||||||
"text": "hello world",
|
"text": "hello world",
|
||||||
}
|
}
|
||||||
@ -117,13 +156,14 @@ This extension is intended for organizing chats between some entities.
|
|||||||
1. Upload the media to Content Service (explanation out of scope of this document)
|
1. Upload the media to Content Service (explanation out of scope of this document)
|
||||||
2. Send message containing the metadata of uploaded media:
|
2. Send message containing the metadata of uploaded media:
|
||||||
|
|
||||||
|
C1->S:
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"id": "abcd",
|
"id": "abcd",
|
||||||
"type": "urn:cadmium:chats:message",
|
"type": "urn:cadmium:chat:message",
|
||||||
"to": ["@user2@cadmium.im"],
|
"to": ["@user2@cadmium.im"],
|
||||||
"payload": {
|
"payload": {
|
||||||
"type": "urn:cadmium:chats:message-types:general",
|
"type": "urn:cadmium:chat:event:message",
|
||||||
"content": {
|
"content": {
|
||||||
"text": "",
|
"text": "",
|
||||||
"media": [
|
"media": [
|
||||||
@ -137,12 +177,11 @@ This extension is intended for organizing chats between some entities.
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
**Response**:
|
S->C1:
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"id": "abcd",
|
"id": "abcd",
|
||||||
"type": "urn:cadmium:chats:message",
|
"type": "urn:cadmium:chat:message",
|
||||||
"from": "cadmium.im",
|
"from": "cadmium.im",
|
||||||
"ok": true,
|
"ok": true,
|
||||||
"payload": {
|
"payload": {
|
||||||
@ -156,22 +195,24 @@ This extension is intended for organizing chats between some entities.
|
|||||||
|
|
||||||
3. Receive message with media on other side:
|
3. Receive message with media on other side:
|
||||||
|
|
||||||
|
S->C2:
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"id": "defg",
|
"id": "defg",
|
||||||
"type": "urn:cadmium:chats:message",
|
"type": "urn:cadmium:chat:message",
|
||||||
"from": "@user1@cadmium.im",
|
"from": "@user1@cadmium.im",
|
||||||
"ok": true,
|
"ok": true,
|
||||||
"payload": {
|
"payload": {
|
||||||
"messageID": "7a1b9a72-1677-4476-9b22-ef7fdbcff52e",
|
"messageID": "7a1b9a72-1677-4476-9b22-ef7fdbcff52e",
|
||||||
"originServerTimestamp": 1599329232,
|
"originServerTimestamp": 1599329232,
|
||||||
"type": "urn:cadmium:chats:message:types:general",
|
"type": "urn:cadmium:chat:event:message",
|
||||||
"content": {
|
"content": {
|
||||||
"text": "",
|
"text": "",
|
||||||
"media": [
|
"media": [
|
||||||
{
|
{
|
||||||
"id": "4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67@content.cadmium.im",
|
"id": "4a771ac1-f0b2-4a4a-9700-f2a26fa2bb67@content.cadmium.im",
|
||||||
"type": "urn:cadmium:chats:media:photo",
|
"type": "urn:cadmium:chat:media:photo",
|
||||||
"attrs": {
|
"attrs": {
|
||||||
"width": 512,
|
"width": 512,
|
||||||
"height": 512
|
"height": 512
|
||||||
@ -191,7 +232,7 @@ This extension is intended for organizing chats between some entities.
|
|||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"id": "abcd",
|
"id": "abcd",
|
||||||
"type": "urn:cadmium:chats:read",
|
"type": "urn:cadmium:chat:read",
|
||||||
"to": ["@user1@cadmium.org"],
|
"to": ["@user1@cadmium.org"],
|
||||||
"payload": {
|
"payload": {
|
||||||
"messageID": "7a1b9a72-1677-4476-9b22-ef7fdbcff52e",
|
"messageID": "7a1b9a72-1677-4476-9b22-ef7fdbcff52e",
|
||||||
@ -204,7 +245,7 @@ This extension is intended for organizing chats between some entities.
|
|||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"id": "abcd",
|
"id": "abcd",
|
||||||
"type": "urn:cadmium:chats:read",
|
"type": "urn:cadmium:chat:read",
|
||||||
"from": "cadmium.im",
|
"from": "cadmium.im",
|
||||||
"ok": true,
|
"ok": true,
|
||||||
"payload": {}
|
"payload": {}
|
||||||
@ -216,7 +257,7 @@ This extension is intended for organizing chats between some entities.
|
|||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"id": "defg",
|
"id": "defg",
|
||||||
"type": "urn:cadmium:chats:read",
|
"type": "urn:cadmium:chat:read",
|
||||||
"from": "@user2@cadmium.im",
|
"from": "@user2@cadmium.im",
|
||||||
"ok": true,
|
"ok": true,
|
||||||
"payload": {
|
"payload": {
|
||||||
@ -232,9 +273,8 @@ This extension is intended for organizing chats between some entities.
|
|||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"id": "abcd",
|
"id": "abcd",
|
||||||
"type": "urn:cadmium:chats:typing",
|
"type": "urn:cadmium:chat:typing",
|
||||||
"to": ["@user1@cadmium.org"],
|
"to": ["@user1@cadmium.org"],
|
||||||
"payload": {}
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
@ -243,13 +283,20 @@ This extension is intended for organizing chats between some entities.
|
|||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"id": "defg",
|
"id": "defg",
|
||||||
"type": "urn:cadmium:chats:typing",
|
"type": "urn:cadmium:chat:typing",
|
||||||
"from": "@user2@cadmium.im",
|
"from": "@user2@cadmium.im",
|
||||||
"ok": true,
|
"ok": true
|
||||||
"payload": {}
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### 6.5. Message history API
|
||||||
|
|
||||||
|
#### 6.5.1. History retrieving
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## 7. Business Rules
|
## 7. Business Rules
|
||||||
|
|
||||||
### 7.1. Typing message notification
|
### 7.1. Typing message notification
|
||||||
@ -262,39 +309,30 @@ This extension is intended for organizing chats between some entities.
|
|||||||
|
|
||||||
## 8. JSON Schema
|
## 8. JSON Schema
|
||||||
|
|
||||||
### Message (`urn:cadmium:chats:message`)
|
### Event Entity
|
||||||
|
|
||||||
**Request**:
|
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
interface MessagePayload {
|
interface Event {
|
||||||
messageID?: EntityID; // the message id (stored in chat timeline) - not required when sending
|
id: EntityID; // the message id (stored in chat timeline) - not required when sending
|
||||||
type: string; // the type of message
|
type: string; // the type of event
|
||||||
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)
|
||||||
originServerTimestamp?: number; // unix timestamp of received message on the origin server (not required when sending)
|
content: Content; // the payload of message (depends on type)
|
||||||
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 Content {}
|
||||||
|
|
||||||
```typescript
|
|
||||||
interface SendMessageResponsePayload {
|
|
||||||
messageID: EntityID; // the message id (stored in chat timeline)
|
|
||||||
originServerTimestamp: number; // unix timestamp of sent message on the origin server
|
|
||||||
}
|
|
||||||
```
|
```
|
||||||
|
|
||||||
#### Content sections
|
#### Content sections
|
||||||
|
|
||||||
- `urn:cadmium:chats:message:types:general`:
|
- `urn:cadmium:chat:events:types:message`:
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
interface GeneralMessageContent {
|
interface MessageContent : Content {
|
||||||
text: string; // the text (body) of message
|
text: string; // the text (body) of message
|
||||||
mentioned?: boolean; // is current entity was mentioned in this message
|
mentioned?: boolean; // is current entity was mentioned in this message
|
||||||
media?: Media[]; // media content
|
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 {
|
interface Media {
|
||||||
@ -338,21 +376,101 @@ interface SendMessageResponsePayload {
|
|||||||
width: number; // width of photo
|
width: number; // width of photo
|
||||||
height: number; // height of photo
|
height: number; // height of photo
|
||||||
}
|
}
|
||||||
```
|
|
||||||
|
|
||||||
- `urn:cadmium:chats:message:types:geolocation`:
|
interface GeolocationAttrs : MediaAttrs {
|
||||||
|
|
||||||
```typescript
|
|
||||||
interface GeolocationMessageContent {
|
|
||||||
lat: number; // the GPS latitude
|
lat: number; // the GPS latitude
|
||||||
lon: number; // the GPS longitude
|
lon: number; // the GPS longitude
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### Read message notification (`urn:cadmium:chats:read`)
|
|
||||||
|
### Send message (`urn:cadmium:chat:message`)
|
||||||
|
|
||||||
|
#### Request
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
interface ReadMessageNotifPayload {
|
interface SendMessageReq {
|
||||||
messageID: EntityID; // the message id of read message
|
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
|
||||||
}
|
}
|
||||||
```
|
```
|
Loading…
Reference in New Issue
Block a user