mirror of
https://github.com/cadmium-im/cadmium-docs-legacy.git
synced 2024-11-09 20:21:03 +00:00
Describe private chats system
This commit is contained in:
parent
01233f774a
commit
8e028e1171
373
protocol-spec/private-chats.md
Normal file
373
protocol-spec/private-chats.md
Normal 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
|
||||||
|
}
|
||||||
|
```
|
Loading…
Reference in New Issue
Block a user