Describe private chats system

This commit is contained in:
ChronosX88 2020-09-05 23:00:22 +04:00
parent 01233f774a
commit 8e028e1171
Signed by: ChronosXYZ
GPG Key ID: 085A69A82C8C511A

View File

@ -0,0 +1,373 @@
# 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:
```json
{
"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**:
```json
{
"id": "abcd",
"type": "urn:cadmium:chats:private:message",
"from": "cadmium.org",
"ok": true,
"payload": {
"messageID": "3b5135a5-aff5-4396-a629-a254f383e82f",
"originServerTimestamp": 1599327584
}
}
```
**Error response**:
```json
{
"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:
```json
{
"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:
```json
{
"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**:
```json
{
"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:
```json
{
"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
```json
{
"id": "abcd",
"type": "urn:cadmium:chats:private:read",
"to": ["@user1@cadmium.org"],
"payload": {
"messageID": "7a1b9a72-1677-4476-9b22-ef7fdbcff52e",
}
}
```
Response:
```json
{
"id": "abcd",
"type": "urn:cadmium:chats:private:read",
"from": "cadmium.im",
"ok": true,
"payload": {}
}
```
2. Receive notification about message reading on other side:
```json
{
"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
```json
{
"id": "abcd",
"type": "urn:cadmium:chats:private:typing",
"to": ["@user1@cadmium.org"],
"payload": {
"status": "typing",
}
}
```
2. Receive notification about typing message on other side:
```json
{
"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)
```json
{
"id": "abcd",
"type": "urn:cadmium:chats:private:typing",
"to": ["@user1@cadmium.org"],
"payload": {
"status": "paused",
}
}
```
4. Receive notification pausing typing message on other side:
```json
{
"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**:
```typescript
interface SendMessagePayload {
type: string; // the type of message
content: Content // the payload of message (depends on type)
}
```
**Response**:
```typescript
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`:
```typescript
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`:
```typescript
interface AudioMessageContent {
url: string; // the url of audio message
}
```
- `urn:cadmium:chats:message-types:geolocation`:
```typescript
interface GeolocationMessageContent {
lat: number; // the GPS latitude
lon: number; // the GPS longitude
}
```
### Receive message (`urn:cadmium:chats:private:message`)
```typescript
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
content: Content // the payload of message (depends on type)
}
```
### Read message (`urn:cadmium:chats:private:read`)
**Request**:
```typescript
interface ReadMessagePayload {
messageID: string; // the message id of read message
}
```
**Response**:
None.
### Receive read message notification (`urn:cadmium:chats:private:read`)
```typescript
interface ReceiveReadMessageNotifPayload {
messageID: string; // the message id of read message
}
```
### Typing message (`urn:cadmium:chats:private:typing`)
**Request**:
```typescript
interface TypingMessagePayload {
status: TypingStatus; // the status of the typing
}
enum TypingStatus {
typing,
paused
}
```
**Response**:
None.
### Receive read message notification (`urn:cadmium:chats:private:typing`)
```typescript
interface TypingMessageNotifPayload {
status: TypingStatus; // the status of the typing
}
```