upload_group_forward_msg

上传或发送群合并转发。

此接口在已认证的服务连接中调用，账号须属于当前框架且处于在线状态。self_id 与 protocol_id 共同选择账号。

messages 是转发节点数组，每项使用 user_id、nickname、time、message，或用 source_message_id 引用缓存消息。节点可包含 text、at、image、voice、video、face、ark；不支持的段会使整个请求失败，不会丢弃节点。跨会话媒体需先上传到目标会话。send 默认为 false，仅上传并返回转发卡片；设为 true 后实际发送并等待消息确认，才返回消息编号。

每次 1–200 个节点。返回 message 是可发送的 Ark 消息段数组；message_id、msg_seq、msg_random、client_seq 仅在 send=true 且发送获确认后出现。

适用协议

Android（手机 / 平板）/ Linux QQ。

调用方式

向已认证的 WebSocket 连接发送：

{
  "type": "action",
  "id": "example-1",
  "action": "upload_group_forward_msg",
  "params": {
    "self_id": 123456789,
    "protocol_id": 0,
    "group_id": 987654321,
    "messages": [
      {
        "user_id": 123456789,
        "nickname": "示例账号",
        "time": 1760000000,
        "message": [
          {
            "type": "text",
            "data": {
              "text": "你好"
            }
          }
        ]
      }
    ]
  }
}

响应通过相同 id 对应请求。连接、HTTP 调用与错误处理见通信协议。

参数

参数	类型	必填	说明
self_id	integer	是	当前框架内的账号 QQ 号
protocol_id	integer	是	账号协议配置 ID；从 get_protocol_list 获取，必须显式传入，0 也是有效 ID
group_id	integer	是	目标群号
send	boolean	否	是否在上传后发送转发消息；默认 false
messages	object[]	是	转发节点数组，详见下方结构
messages[].source_message_id	integer	见说明	当前账号消息缓存中的引用编号，与 message 二选一
messages[].user_id	integer	见说明	目标 QQ 号
messages[].nickname	string	见说明	昵称
messages[].message	object[]	见说明	消息段数组，结构见消息段参考
messages[].time	integer	见说明	业务时间戳

返回值

以下为成功响应的 data，错误通过 ok: false 与 error 返回。

字段	类型	说明
success	boolean	操作是否成功
res_id	string	合并转发资源标识
message	object[]	消息段数组，结构见消息段参考
uploaded_messages	integer	已上传的转发节点数
discarded_messages	integer	丢弃节点数；成功时为 0
discarded_segments	integer	丢弃消息段数；成功时为 0
message_id	integer	消息事件或发送结果中的框架消息编号
msg_seq	integer	上游消息序列号
msg_random	integer	上游消息随机数
client_seq	integer	客户端序列号