upload_friend_voice

上传语音并取得可用于发送消息的 voice 消息段。上传完成不会自动发送消息。支持当前框架内的在线 Android 与 Linux QQ 账号。

不传 group_id 时按普通好友上传，目标必须在当前账号的好友列表中。传 group_id 时按群临时会话上传，返回段只能用于该群与该目标的 send_group_temp_msg。

适用协议

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

调用方式

先将示例文件放入框架的允许目录，再向已认证 WebSocket 发送：

{
  "type": "action",
  "id": "upload_friend_voice-1",
  "action": "upload_friend_voice",
  "params": {
    "self_id": 123456789,
    "protocol_id": 0,
    "user_id": 234567890,
    "file_path": "data/media-downloads/example.wav"
  }
}

收到 ok: true 后，把响应的 data 原样放入 send_friend_msg 的 message 数组，并使用相同 self_id、protocol_id 和目标：

// uploadResult 为上面上传请求对应的 action_result。
if (uploadResult.ok) {
  ws.send(JSON.stringify({
    type: "action",
    id: "send-media-1",
    action: "send_friend_msg",
    params: {
      self_id: 123456789,
      protocol_id: 0,
      user_id: 234567890,
      message: [uploadResult.data]
    }
  }))
}

群临时会话上传时，在上传参数增加 group_id；发送改用 send_group_temp_msg，并传相同 group_id 与 user_id。

参数

参数	类型	必填	说明
self_id	integer	是	当前框架内的在线 QQ 账号。
protocol_id	integer	是	账号协议 ID，须显式提供；0 是有效 ID。
user_id	integer	是	目标 QQ 号，不能用 UID 替代。
group_id	integer	否	普通好友会话省略或传 0；群临时会话传共同群号，此时发送方与目标须在该群且具有临时会话权限。
file_path	string	二选一	本地允许目录中的文件、HTTP(S) URL、file:// 路径，或本插件服务已经完成的 transfer:// 引用。
base64	string	二选一	完整音频的 Base64，与 file_path 不能同时提供。支持纯 Base64、base64:// 前缀和 Base64 data URL。

文件来源

本地相对路径以框架工作目录为基准，不是插件进程目录。允许读取的目录是 data/media-downloads、data/plugin-downloads 和 data/stream-temp；文件必须已经存在，不能读取其他框架数据或系统文件。

外部插件不方便写入这些目录时，可先用 file_transfer 上传，完成后将返回的 file（transfer:// 引用）作为 file_path。此引用只能由创建它的同一插件服务使用。

音频支持 MP3、WAV 和可解析的 SILK V3；MP3/WAV 会转换为语音所需的 SILK，并生成时长与波形。文件扩展名不能代替真实格式，不支持的音频会返回错误。file_path 也可使用 base64:// 或 Base64 data URL，此时不要再传 base64。

返回值

成功响应的 data 本身就是消息段：

字段	类型	说明
type	string	固定为 voice
data.file_id	string	本次上传取得的媒体引用，不是 file_transfer 的 token
data.duration	integer	语音时长，单位秒

错误通过外层 ok: false 和 error 返回。媒体引用绑定当前账号、协议和目标会话；不能跨账号、跨协议或跨目标复用，也不能将群媒体用于好友消息。普通好友与群临时会话、不同群的临时会话之间也不能混用。账号重连或缓存失效后应重新上传。