cadmium-docs-legacy/CPPs/proposed/CPP3 - Private user messages.md

CPP#3 - Private user messages

Introduction

This proposal introduces the concept of chats (this proposal describes only private chats) and a mechanism for sending/receiving messages in the chat.

Message type identifiers

• chat:create: create chat action
• chat:created: notification about creating new chat by some user
• message:send: send message to chat
• message:receive: receive message from chat
• message:read: read a message
• message:receive:read: receive notification about read message

Glossary

• Chat (the so-called "room") - the entity in which communication occurs between users (participants).
• Chat history - an ordered by time list of messages of chat

Use Cases

Note: C - client, S - server

Creating private chat

1. C1:

{
    "id": "abcd",
    "type": "chat:create",
    "from": "@user1@cadmium.im",
    "to": "@user2@cadmium.im",
    "payload": {
        "chatType": "user"
    }
}

2. S to C1:

{
    "id": "abcd",
    "type": "chat:create",
    "from": "cadmium.im",
    "to": "@user1@cadmium.im",
    "ok": true,
    "payload": {
        "roomId": "!22c5d942-22bc-45b3-9541-ec2b49afe5ec@cadmium.im"
    }
}

Error response (S):

{
    "id": "abcd",
    "type": "chat:create",
    "from": "cadmium.im",
    "to": "@user1@cadmium.im",
    "ok": false,
    "payload": {
        "errCode": "blacklistedUser",
        "errText": "You are blacklisted for this user"
    }
}

3. S to C2:

{
    "id": "abcd",
    "type": "chat:created",
    "from": "@user1@cadmium.im",
    "to": "@user2@cadmium.im",
    "ok": true,
    "payload": {
        "roomId": "!22c5d942-22bc-45b3-9541-ec2b49afe5ec@cadmium.im"
    }
}

Sending message to chat

1. C1:

{
    "id": "abcd",
    "type": "message:send",
    "from": "@user1@cadmium.im",
    "to": "!22c5d942-22bc-45b3-9541-ec2b49afe5ec@cadmium.im",
    "payload": {
        "messageType": "text",
        "messageText": "Hello world!"
    }
}

2. S to C1:

{
    "id": "abcd",
    "type": "message:send",
    "from": "!22c5d942-22bc-45b3-9541-ec2b49afe5ec@cadmium.im",
    "to": "@user1@cadmium.im",
    "ok": true,
    "payload": {
        "messageTimestamp": 1577988125,
        "messageId": "ee55b940-0f2f-46dc-8c8e-e6ea5874c3c2"
    }
}

3. S to C2:

{
    "id": "abcd",
    "type": "message:receive",
    "from": "!22c5d942-22bc-45b3-9541-ec2b49afe5ec@cadmium.im",
    "to": "@user2@cadmium.im",
    "ok": true,
    "payload": {
        "messageType": "text",
        "messageId": "ee55b940-0f2f-46dc-8c8e-e6ea5874c3c2",
        "messageText": "Hello world!"
    }
}

Reading message

1. C2:

{
    "id": "abcd",
    "type": "message:read",
    "from": "@user2@cadmium.im",
    "to": "!22c5d942-22bc-45b3-9541-ec2b49afe5ec@cadmium.im",
    "payload": {
        "messageId": "ee55b940-0f2f-46dc-8c8e-e6ea5874c3c2"
    }
}

2. S to C2:

{
    "id": "abcd",
    "type": "message:read",
    "from": "!22c5d942-22bc-45b3-9541-ec2b49afe5ec@cadmium.im",
    "to": "@user2@cadmium.im",
    "ok": true,
    "payload": {}
}

3. S to C1:

{
    "id": "abcd",
    "type": "message:receive:read",
    "from": "!22c5d942-22bc-45b3-9541-ec2b49afe5ec@cadmium.im",
    "to": "@user1@cadmium.im",
    "ok": true,
    "payload": {
        "messageId": "ee55b940-0f2f-46dc-8c8e-e6ea5874c3c2",
        "readUserId": "@user2@cadmium.im"
    }
}

Errors

• Ratelimit system: enabled
• Authentication required: true
• blacklistedUser: user 1, who is trying to create a chat, is blacklisted by user 2

Business Rules

• Every message MUST be recorded in chat message history
• Timestamp MUST be in UTC timezone
• Server MUST store read state of message as list of user IDs which read this message

Security Considerations

None.

JSON Schema

Creating chat payload

• Request for creating chat:

interface CreatePrivateChatRequestPayload {
    /**
     * Type of chat which need to create
     */
    chatType: ChatType,

    /**
     * Second chat member ID (first member is who trying to create this chat) in
     * case when chatType is "user"
     */
    receiverUserId: EntityID
}

• Response for creating chat:

interface CreatePrivateChatResponsePayload {
    /**
     * Identifier of newly created chat
     */
    roomId: EntityID
}

• Notification for second member of newly created chat about the fact of creating this chat

interface CreatePrivateChatNotificationPayload {
    /**
     * Identifier of newly created chat
     */
    roomId: EntityID
}

Sending message to chat payload

• Send message action request payload

interface SendMessageRequestPayload {
    /**
     * Type of the message
     */
    messageType: MessageType,

    /**
     * Text of the message
     */
    messageText: string,


    /**
     * URL of file/image/voice which attached to this message (in case of
     * appropriate message type)
     */
    fileUrl?: string
}

• Send message action response payload

interface SendMessageResponsePayload {
    /**
     * UNIX Timestamp of newly sent message
     */
    messageTimestamp: number,

    /**
     * Message identifier in chat history of newly sent message
     */
    messageId: string
}

• Notification about new message in the chat

interface NewMessageNotificationPayload {
    /**
     * Identifier of received message in chat history
     */
    messageId: string,

    /**
     * UNIX timestamp of received message
     */
    messageTimestamp: number,

    /**
     * Text of received message
     */
    messageText: string
}

Reading message payload

• Read message action request payload

interface ReadMessageRequesPayload {
    /**
     * Identifier of message which need mark as read
     */
    messageId: string,
}

• Notification about reading message

interface ReadMessageRequesPayload {
    /**
     * Identifier of message which was read
     */
    messageId: string,

    /**
     * Identifier of user which read this message
     */
    readUserId: EntityID
}