跳转到主要内容
POST
/
message
/
send
curl -X POST "http://localhost:5001/message/send" \
  -H "Content-Type: application/json" \
  -d '{
    "header": {
      "no_persist": 0,
      "red_dot": 1,
      "sync_once": 0
    },
    "client_msg_no": "client_msg_123",
    "from_uid": "user123",
    "channel_id": "group123",
    "channel_type": 2,
    "expire": 0,
    "payload": "SGVsbG8gV29ybGQ=",
    "tag_key": "important"
  }'

{
  "message_id": 123456789,
  "message_seq": 1001,
  "client_msg_no": "client_msg_123"
}

​
概述

向指定频道发送消息，支持文本、图片、文件等多种消息类型。

​
请求体

​
必传参数

​
payload
string
required
Base64 编码的消息内容
​
from_uid
string
required
发送者用户 ID
​
channel_id
string
required
目标频道 ID
​
channel_type
integer
required
频道类型 (1=个人频道, 2=群组频道)

​
可选参数

​
header
object
消息头部信息
​
client_msg_no
string
客户端消息编号，用于去重和状态跟踪
​
stream_no
string
流消息编号
​
expire
integer
消息过期时间（秒），0 表示不过期
​
subscribers
array
指定接收消息的订阅者列表（此参数只有CMD消息才有效）
​
subscribers[]
string
订阅者用户 ID
curl -X POST "http://localhost:5001/message/send" \
  -H "Content-Type: application/json" \
  -d '{
    "header": {
      "no_persist": 0,
      "red_dot": 1,
      "sync_once": 0
    },
    "client_msg_no": "client_msg_123",
    "from_uid": "user123",
    "channel_id": "group123",
    "channel_type": 2,
    "expire": 0,
    "payload": "SGVsbG8gV29ybGQ=",
    "tag_key": "important"
  }'

{
  "message_id": 123456789,
  "message_seq": 1001,
  "client_msg_no": "client_msg_123"
}

​
响应字段

​
message_id
integer
required
服务器生成的消息 ID
​
message_seq
integer
required
消息序列号
​
client_msg_no
string
required
客户端消息编号（回显）

​
状态码

状态码说明
200消息发送成功
400请求参数错误
403没有发送权限
500服务器内部错误

​
消息类型示例

根据 WuKongIM 协议规范，以下是推荐的 Payload 结构示例：

​
普通消息

​
文本消息

{
    "type": 1,
    "content": "这是一条文本消息"
}

​
文本消息（带@功能）

{
    "type": 1,
    "content": "这是一条文本消息",
    "mention": {
        "all": 0,
        "uids": ["1223", "2323"]
    }
}
  • mention.all: 是否@所有人 (0=@用户, 1=@所有人)
  • mention.uids: 如果 all=1，此字段为空

​
文本消息（带回复）

{
    "type": 1,
    "content": "回复了某某",
    "reply": {
        "root_mid": "xxx",
        "message_id": "xxxx",
        "message_seq": 123,
        "from_uid": "xxxx",
        "from_name": "xxx",
        "payload": {}
    }
}

​
图片消息

{
    "type": 2,
    "url": "http://xxxxx.com/xxx",
    "width": 200,
    "height": 320
}

​
GIF 消息

{
    "type": 3,
    "url": "http://xxxxx.com/xxx",
    "width": 72,
    "height": 72
}

​
语音消息

{
    "type": 4,
    "url": "http://xxxxx.com/xxx",
    "timeTrad": 10
}
timeTrad: 语音时长（秒）

​
文件消息

{
    "type": 8,
    "url": "http://xxxxx.com/xxx",
    "name": "xxxx.docx",
    "size": 238734
}
size: 文件大小，单位为 byte

​
命令消息

{
    "type": 99,
    "cmd": "groupUpdate",
    "param": {}
}

​
系统消息

系统消息的 type 必须大于 1000

​
创建群聊

消息设置：NoPersist:0, RedDot:0, SyncOnce:1 
{
    "type": 1001,
    "creator": "xxx",
    "creator_name": "张三",
    "content": "{0}邀请{1}、{2}加入群聊",
    "extra": [
        {"uid": "xxx", "name": "张三"},
        {"uid": "xx01", "name": "李四"},
        {"uid": "xx02", "name": "王五"}
    ]
}

​
添加群成员

消息设置：NoPersist:0, RedDot:0, SyncOnce:1 
{
    "type": 1002,
    "content": "{0}邀请{1}、{2}加入群聊",
    "extra": [
        {"uid": "xxx", "name": "张三"},
        {"uid": "xx01", "name": "李四"},
        {"uid": "xx02", "name": "王五"}
    ]
}

​
移除群成员

消息设置：NoPersist:0, RedDot:0, SyncOnce:1 
{
    "type": 1003,
    "content": "{0}将{1}移除群聊",
    "extra": [
        {"uid": "xxx", "name": "张三"},
        {"uid": "xx01", "name": "李四"}
    ]
}

​
群成员被踢

消息设置：NoPersist:0, RedDot:1, SyncOnce:0 
{
    "type": 1010,
    "content": "你被{0}移除群聊",
    "extra": [
        {"uid": "xxx", "name": "张三"}
    ]
}

​
更新群名称

消息设置：NoPersist:0, RedDot:0, SyncOnce:1 
{
    "type": 1005,
    "content": "{0}修改群名为\"测试群\"",
    "extra": [
        {"uid": "xxx", "name": "张三"}
    ]
}

​
更新群公告

消息设置：NoPersist:0, RedDot:0, SyncOnce:1 
{
    "type": 1005,
    "content": "{0}修改群公告为\"这是一个群公告\"",
    "extra": [
        {"uid": "xxx", "name": "张三"}
    ]
}

​
撤回消息

消息设置：NoPersist:0, RedDot:0, SyncOnce:1 
{
    "type": 1006,
    "message_id": "234343435",
    "content": "{0}撤回了一条消息",
    "extra": [
        {"uid": "xxx", "name": "张三"}
    ]
}

​
命令类消息

​
基础命令消息

消息设置：SyncOnce:1 
{
    "type": 99,
    "cmd": "cmd",
    "param": {}
}

​
群成员信息更新

收到此消息客户端应该增量同步群成员信息 
{
    "type": 99,
    "cmd": "memberUpdate",
    "param": {
        "group_no": "xxxx"
    }
}

​
红点消除

收到此命令客户端应将对应的会话信息的红点消除 
{
    "type": 99,
    "cmd": "unreadClear",
    "param": {
        "channel_id": "xxxx",
        "channel_type": 2
    }
}

​
使用示例

// 发送文本消息
const textMessage = {
    type: 1,
    content: "这是一条文本消息"
};

const payload = btoa(JSON.stringify(textMessage));

const response = await fetch('/message/send', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        from_uid: "user123",
        channel_id: "group123",
        channel_type: 2,
        payload: payload
    })
});

​
最佳实践

  1. 消息去重：使用唯一的 client_msg_no 避免重复发送
  2. 消息队列：对于发送失败的消息，加入重试队列
  3. 内容编码：确保 payload 正确进行 Base64 编码
  4. 权限检查：发送前检查用户是否有发送权限
  5. 消息类型：严格按照协议规范使用正确的消息类型编号
  6. 系统消息：系统消息类型必须大于 1000，并设置正确的消息标志位
  7. 命令消息：命令类消息应设置 SyncOnce:1 标志位