Chat

Provides API and WebSocket channels for real-time interaction between members and platform agents.

Auth Requirement: All HTTP requests and WebSocket connections require a Token. Unauthenticated guests should use the BaseToken alongside a self-generated guest_id, while logged-in members use the formal MemberToken.

1. Establish WebSocket Connection

The client must use this WebSocket channel to receive agent replies and maintain a long-connection heartbeat.

Connection Information

• Endpoint: ws://<domain>/chat/ws
• Params: ?token=<BaseToken_or_MemberToken>&guest_id=<UUID>

Communication Payload Format

All communication data must be wrapped in the following JSON structure:

{
  "type": "Type Identifier",
  "data": { ... }
}

2.1 Heartbeat (Ping/Pong)

• Client Sends: {"type": "ping"}
• Server Replies: {"type": "pong"}
• Description: The client must send a ping every 30 seconds to keep the connection alive.

2.2 Send Message (Client -> Server)

{
  "type": "chat_message",
  "data": {
    "msg_type": "text", 
    "content": "Hello, I need some help."
  }
}

Note: If sending an image, the frontend must first call the system's general image upload API (global public upload API) to get a URL, then send via WS with msg_type: "image" and the URL. Images must be compressed by the frontend using Canvas (max width 1080px, auto height) before uploading to ensure high definition while saving bandwidth.

2.3 Recall Message (Client -> Server)

{
  "type": "recall_message",
  "data": {
    "message_id": "msg_67890"
  }
}

Note: You can only recall your own messages sent within the last 30 minutes. Images can be recalled.

2.4 Edit Message (Client -> Server)

{
  "type": "edit_message",
  "data": {
    "message_id": "msg_67890",
    "new_content": "Edited text content"
  }
}

Note: You can only edit your own text messages sent within the last 30 minutes. Images cannot be edited.

2.5 Receive Message (Server -> Client)

{
  "type": "new_message",
  "data": {
    "message_id": "msg_67890",
    "sender_type": "agent", // "agent" or "system"
    "sender_name": "Agent Alice", // Must be displayed on UI
    "msg_type": "text", 
    "content": "Sure, please wait a moment.",
    "created_at": "2026-06-14T17:35:00Z"
  }
}

2.6 Receive Message Update (Server -> Client)

When a message (from the agent or the user) is edited or recalled, the server pushes this event. The client should update the corresponding message bubble in real-time based on the message_id:

{
  "type": "update_message",
  "data": {
    "message_id": "msg_67890",
    "conversation_id": "conv_12345",
    "content": "Edited content or original content",
    "is_recalled": true, // Whether it has been recalled (Boolean)
    "is_edited": true,   // Whether it has been edited (Boolean)
    "msg_type": "text"
  }
}

3. Get Chat History

Used to fetch chat history when opening the chat window for the first time or pulling to load more. This interface must use cursor-based pagination.

Interface Definition

• Endpoint: GET /chat/history
• Auth: Token required
• Query Params:

  Parameter	Type	Required	Default	Description
  limit	int	No	50	Number of records to return
  last_message_id	string	No	""	Used for cursor pagination, pass the message_id of the oldest message in the current list

Response Example

{
  "code": 0,
  "data": {
    "list": [
      {
        "id": "msg_001",
        "sender_type": "member",
        "msg_type": "text",
        "content": "Hello",
        "is_recalled": false,
        "is_edited": false,
        "created_at": "2026-06-14T17:34:00Z"
      }
    ],
    "has_more": true
  },
  "msg": "success"
}

4. Get Unread Message Count

Used to display the unread count of agent replies on non-chat pages (e.g., floating button or notification bar).

Interface Definition

• Endpoint: GET /chat/unread
• Auth: Token required

Response Example

{
  "code": 0,
  "data": {
    "unread_count": 2
  },
  "msg": "success"
}

5. Mark Message as Read

When the user opens the chat window and sees new messages, this interface should be called to clear the unread notification.

Interface Definition

• Endpoint: POST /chat/read
• Auth: Token required

Request Parameters

{
  "message_id": "msg_001" // Optional. If not provided, it clears all unread messages for the conversation.
}

6. Image Upload Instructions

To ensure the security and permission isolation of the chat system, the chat plugin provides a dedicated image upload interface. The frontend can directly call this interface to upload compressed images, obtain the URL, and then send it via WebSocket.

Interface Definition

• Endpoint: POST /chat/upload
• Auth: Token required (Must be a logged-in member's MemberToken. Guests are not allowed to upload images.)
• Content-Type: application/json

Request Parameters (JSON)

Parameter	Type	Required	Description
file	string	Yes	The Base64 encoded string of the image (can include the data:image/jpeg;base64, prefix).
classId	int	No	Category ID, defaults to 0.
folder	string	No	Upload directory, defaults to the chat directory if not provided.

Send Image Flow

1. The user selects or takes a photo in the chat interface.
2. The frontend uses Canvas to resize and compress the image (max width 1080px, proportionally scaled height) to ensure high definition without consuming too much server bandwidth. Then, export it as a Base64 string.
3. Call the dedicated interface POST /chat/upload, submitting the Base64 string as the file field in the JSON payload.
4. After retrieving the remote URL from the response's data.file.url, send the message to the agent via WebSocket: {"type": "chat_message", "data": {"msg_type": "image", "content": "REMOTE_URL"}}.