发送事件 - WuKongIM

概述

发送各种类型的事件到频道，包括流式文本消息和自定义事件。支持AG-UI协议事件，用于实时流式通信。

查询参数

force

string

默认值:"0"

强制结束频道中现有的流，然后开始新流

0 - 不强制结束
1 - 强制结束现有流

请求体

必传参数

client_msg_no

string

必填

客户端消息编号，必须唯一且不重复。用于标识和跟踪消息/流。对于流式消息，同一流中的所有事件应使用相同的client_msg_no。建议使用UUID格式。

channel_id

string

必填

目标频道ID，事件将发送到此频道。对于个人频道，这应该是目标用户ID。对于群组频道，这应该是群组ID。

channel_type

integer

必填

频道类型

1 - 个人频道
2 - 群组频道

event

object

必填

事件对象

显示 event 字段

event.type

string

必填

事件类型，支持AG-UI协议事件和自定义事件AG-UI协议事件：

___TextMessageStart - 开始流式文本消息会话
___TextMessageContent - 发送流式内容块
___TextMessageEnd - 结束流式文本消息会话
___ToolCallStart - 开始工具/函数调用事件
___ToolCallArgs - 发送工具调用参数
___ToolCallEnd - 结束工具调用事件
___ToolCallResult - 返回工具执行结果

自定义事件： 任何不以 ___ 开头的字符串都被视为自定义事件类型

event.id

string

事件ID（可选，某些事件类型会自动生成）

event.timestamp

integer

事件时间戳（可选，Unix时间戳，毫秒）

event.data

string

事件数据内容。格式取决于事件类型：文本消息事件：

___TextMessageStart - 初始消息内容或元数据
___TextMessageContent - 流式文本块
___TextMessageEnd - 最终内容或完成标记

工具调用事件：

___ToolCallStart - 工具名称或元数据
___ToolCallArgs - 函数参数的JSON字符串
___ToolCallEnd - 完成状态
___ToolCallResult - 执行结果的JSON字符串

自定义事件： 与应用程序相关的任何字符串数据

可选参数

from_uid

string

发送者用户ID。如果未提供或为空，默认为系统UID。用于标识发送事件的用户。

curl -X POST "http://localhost:5001/event" \
  -H "Content-Type: application/json" \
  -d '{
    "client_msg_no": "msg_001_stream_start",
    "channel_id": "group_ai_chat",
    "channel_type": 2,
    "from_uid": "ai_assistant",
    "event": {
      "type": "___TextMessageStart",
      "data": "开始AI回复..."
    }
  }'

{
  "status": "ok"
}

响应字段

status

string

必填

操作状态，成功时返回 "ok"

状态码

状态码	说明
200	事件发送成功
400	请求参数错误或事件数据无效
500	服务器内部错误

流式消息机制

流式消息流程

开始流：发送 ___TextMessageStart 事件启动流
发送内容：发送多个 ___TextMessageContent 事件传输消息块
结束流：发送 ___TextMessageEnd 事件关闭流

重要注意事项

同一流中的所有事件必须使用相同的 client_msg_no
除非使用 force=1，否则每个频道只能有一个活跃流
对于个人频道，系统会自动处理虚假频道ID生成
事件会自动路由到适当的集群节点

事件类型详解

AG-UI协议事件

AG-UI协议事件用于实时流式通信，特别适用于AI应用：

事件类型	用途	数据格式
`___TextMessageStart`	启动流式文本消息会话	初始内容或元数据
`___TextMessageContent`	发送内容块	文本块内容
`___TextMessageEnd`	终止流式文本消息会话	完成标记
`___ToolCallStart`	开始工具调用事件	工具名称或元数据
`___ToolCallArgs`	发送工具调用参数	JSON格式的参数
`___ToolCallEnd`	结束工具调用事件	完成状态
`___ToolCallResult`	返回工具执行结果	JSON格式的结果

自定义事件

任何不以 ___ 开头的事件类型都被视为自定义事件，可用于：

用户状态更新
系统通知
业务逻辑事件
应用特定的交互

使用场景

AI聊天机器人

# 模拟AI打字效果
curl -X POST "/event" -d '{
  "client_msg_no": "ai_response_001",
  "channel_id": "user_123",
  "channel_type": 1,
  "from_uid": "ai_bot",
  "event": {
    "type": "___TextMessageStart",
    "data": "{\"type\":1,\"content\":\"思考中...\"}"
  }
}'

# 逐步发送回复内容
curl -X POST "/event" -d '{
  "client_msg_no": "ai_response_001",
  "channel_id": "user_123", 
  "channel_type": 1,
  "from_uid": "ai_bot",
  "event": {
    "type": "___TextMessageContent",
    "data": "根据您的问题，我建议..."
  }
}'

实时协作

# 文档编辑状态
curl -X POST "/event" -d '{
  "client_msg_no": "doc_edit_001",
  "channel_id": "doc_room_456",
  "channel_type": 2,
  "from_uid": "user_789",
  "event": {
    "type": "document_editing",
    "data": "{\"action\": \"start_edit\", \"section\": \"paragraph_1\"}"
  }
}'

系统通知

# 用户上线通知
curl -X POST "/event" -d '{
  "client_msg_no": "status_update_001",
  "channel_id": "group_general",
  "channel_type": 2,
  "from_uid": "system",
  "event": {
    "type": "user_online",
    "timestamp": 1640995200000,
    "data": "{\"user_id\": \"user_123\", \"status\": \"online\"}"
  }
}'

最佳实践

唯一标识：使用UUID格式的 client_msg_no 确保唯一性
流管理：及时结束不再使用的流，避免资源浪费
错误处理：处理流冲突和发送失败的情况
权限验证：确保发送者有频道的发送权限
数据格式：对于复杂数据使用JSON格式的字符串
性能优化：合理控制流式消息的发送频率

错误处理

常见错误

错误	原因	解决方案
事件类型不能为空	未提供event.type	确保提供有效的事件类型
频道中已有流正在运行	尝试在有活跃流的频道开始新流	使用 `force=1` 或等待现有流结束
流不存在	尝试向不存在的流发送内容	检查流是否已正确创建
流已关闭	向已关闭的流发送内容	重新开始新的流

重试机制

对于临时性错误，建议实现指数退避重试机制：

async function sendEventWithRetry(eventData, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch('/event', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(eventData)
      });
      
      if (response.ok) return await response.json();
      
      if (response.status >= 400 && response.status < 500) {
        // 客户端错误，不重试
        throw new Error(`Client error: ${response.status}`);
      }
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
    }
  }
}

​概述

​查询参数

​请求体

​必传参数

​可选参数

​响应字段

​状态码

​流式消息机制

​流式消息流程

​重要注意事项

​事件类型详解

​AG-UI协议事件

​自定义事件

​使用场景

​AI聊天机器人

​实时协作

​系统通知

​最佳实践

​错误处理

​常见错误

​重试机制

概述

查询参数

请求体

必传参数

可选参数

响应字段

状态码

流式消息机制

流式消息流程

重要注意事项

事件类型详解

AG-UI协议事件

自定义事件

使用场景

AI聊天机器人

实时协作

系统通知

最佳实践

错误处理

常见错误

重试机制