Chat21 HTTP API 应用镜像

镜像概述和主要用途

Chat21 HTTP API应用镜像是Chat21的原生REST API服务器，用于提供聊天功能的后端接口服务。该镜像支持多租户环境，通过REST API实现消息发送、群组管理、对话管理等核心聊天功能，适用于需要集成实时聊天能力的各类应用系统。

核心功能和特性

• 消息交互：支持发送文本消息和图片消息，区分直接消息（一对一）和群组消息两种渠道类型
• 群组管理：提供完整的群组生命周期管理，包括创建群组、加入群组、离开群组及群组成员设置
• 对话管理：支持对话的归档和永久删除操作，满足用户对对话记录的管理需求
• 多租户支持：通过APP_ID参数实现多租户环境隔离，默认使用"default"作为租户标识
• 安全认证：所有API接口需通过JWT令牌（JWT-TOKEN）进行身份验证

使用场景和适用范围

适用于需要集成实时聊天功能的各类应用场景，包括但不限于：

• 社交应用的用户间实时聊天功能
• 企业内部通讯工具的消息交互模块
• 在线教育平台的师生/生生交流系统
• 客服系统的客户对话后端服务

详细使用方法和配置说明

REST API

认证

使用所有API接口前，需先获取有效的JWT授权令牌（JWT-TOKEN）。

JWT认证

具体实现细节即将推出。

发送消息

通过POST请求发送消息，支持直接消息和群组消息：

curl --location --request POST 'http://localhost:8004/api/APP_ID/messages' \
--header 'Authorization: JWT-TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
 "sender_fullname": "发送者全名",
 "recipient_id": "接收者UUID",
 "recipient_fullname": "接收者全名",
 "text": "hello",
 "type": "text",
 "channel_type": "direct"
}'

参数说明：

• JWT-TOKEN：授权JWT令牌（必填）
• APP_ID：多租户环境的应用ID，默认值为"default"（必填）
• sender_fullname：发送者全名，例如："张三"（必填）
• recipient_id：接收者ID，直接消息为用户ID，群组消息为群组ID（必填）
• recipient_fullname：接收者全名，例如："李四"（必填）
• text：消息文本内容（文本消息必填）
• channel_type：消息渠道类型，可选值："direct"（默认，一对一直接消息）、"group"（群组消息）（选填）
• type：消息类型，可选值："text"（默认，文本消息）、"image"（图片消息，需同时设置metadata字段）（选填）
• attributes：消息自定义属性，格式示例：{"custom_attribute1": "value1"}（选填）
• metadata：图片消息属性（仅type为"image"时必填），包含：src（图片绝对路径）、width（宽度）、height（高度），格式示例：{"src": "[***]", "width": 200, "height": 200}（选填）

创建群组

通过POST请求创建新群组：

curl -X POST \
  -H 'Content-Type: application/json' \
  -H "Authorization: JWT-TOKEN" \
  -d '{"group_name": "<群组名称>", "group_members": {"<成员ID>":1}}' \
  'http://localhost:8004/api/<APP_ID>/groups'

参数说明：

• GROUP_NAME：新群组的名称（必填）
• MEMBER_ID：群组成员的用户ID，格式为{"用户ID":1}（必填）
• APP_ID：多租户环境的应用ID，默认值为"default"（必填）

加入群组

通过POST请求让用户加入指定群组：

curl -X POST \
  -H 'Content-Type: application/json' \
  -H "Authorization: JWT-TOKEN" \
  -d '{"member_id": "<成员ID>"}' \
  'http://localhost:8004/api/<APP_ID>/groups/<群组ID>/members'

参数说明：

• MEMBER_ID：要加入群组的用户ID（必填）
• APP_ID：多租户环境的应用ID，默认值为"default"（必填）
• GROUP_ID：目标群组的ID（必填）

离开群组

通过DELETE请求让用户离开指定群组：

curl -X DELETE \
  -H 'Content-Type: application/json' \
  -H "Authorization: JWT-TOKEN" \
  -d '{"member_id": "<成员ID>"}' \
  'http://localhost:8004/api/<APP_ID>/groups/<群组ID>/members/<成员ID>'

参数说明：

• APP_ID：多租户环境的应用ID，默认值为"default"（必填）
• GROUP_ID：目标群组的ID（必填）
• MEMBER_ID：要离开群组的用户ID（必填）

设置群组成员

通过PUT请求更新群组的成员列表：

curl -X PUT \
  -H 'Content-Type: application/json' \
  -H "Authorization: JWT-TOKEN" \
  -d '{"members": {"<成员ID1>":1}, {"<成员ID2>":1}}' \
  'http://localhost:8004/api/<APP_ID>/groups/<群组ID>/members'

参数说明：

• MEMBER_IDs：群组成员的用户ID列表，格式为{"用户ID":1}（必填）
• APP_ID：多租户环境的应用ID，默认值为"default"（必填）
• GROUP_ID：目标群组的ID（必填）

归档或删除对话

通过DELETE请求对指定接收者的对话进行归档或永久删除：

curl -X DELETE \
  -H 'Content-Type: application/json' \
  -H "Authorization: JWT-TOKEN" \
  http://localhost:8004/api/<APP_ID>/conversations/<接收者ID>?delete=<布尔值>

参数说明：

• APP_ID：多租户环境的应用ID，默认值为"default"（必填）
• RECIPIENT_ID：对话接收者的ID（必填）
• delete（可选）：布尔值，true表示永久删除对话，false表示归档对话，未指定时默认归档