bytedance byted-vms-cdr-record · 火山云通信话单/录音查询
环境变量
按以下优先级解析鉴权 (与其他 vms-* skill 一致):
ARK_SKILL_API_KEY+ARK_SKILL_API_BASE→ 火山引擎 arkclaw 企业版. 请先在火山后台页面配置好 AK/SK, 由 arkclaw 注入这两个环境变量 (ARK_SKILL_API_KEY为 API 密钥,ARK_SKILL_API_BASE为 API 基础地址), 脚本以Bearer鉴权直连该网关, 无需本地签名;VOLC_ACCESS_KEY+VOLC_SECRET_KEY(兼容VOLCENGINE_ACCESS_KEY/VOLCENGINE_SECRET_KEY) → 个人版 arkclaw / openclaw / coco / aime / claudecode 等普通 agent, 用户直接把 AK/SK 告诉 agent, 脚本本地做 HMAC-SHA256 (Volc V4) 签名;- 否则报错并提示用户填入 AK/SK.
重要前置说明 (TOP 限制)
QueryCallRecordMsg / QueryAudioRecordFileUrl 这两个接口在 TOP 网关上有以下硬约束 (实测):
- 必须传
CallIdList(form-urlencoded), 服务端校验直接报Required List parameter 'CallIdList' is not present; - 不接受按手机号 / 时间区间 / SingleOpenId 反查;
SingleBatchAppend返回的是SingleOpenId而不是CallId, 这两者是不同字段, 无法相互转换.
因此, 想拿到 CallId 必须依赖以下两条之一:
- 平台异步回调: 火山通信会在通话结束时把含
CallId的话单 push 到业务方配置的回调地址; - 业务侧持久化: 业务后端在收到回调时把
single_open_id ↔ call_id映射存到自己的存储中, 后续按 SingleOpenId 反查 CallId.
如果用户只有 SingleOpenId 或被叫号码, 没有 CallId, 不要尝试调用本 skill 的 query_cdr, 应明确告知用户该限制并引导其去控制台 https://console.volcengine.com/cloud_vms/cdrList 查看, 或在业务侧用 SingleOpenId 反查 CallId, 又或者改用 query_sip_record (按被叫/主叫 + 时间窗) 查列表.
命令
# 1. 按 callId 精确查话单 (V1, CallIdList 必填, 实际走 form-urlencoded)
python3 scripts/cdr_record.py query_cdr --call-id <CallId> \
[--business-type voiceNotify|privacyNumber|aicall] \
[--limit 20] [--offset 0]
# 1.1. 按 callId 批量查话单 (V2, JSON body, 单次最多 100 条)
python3 scripts/cdr_record.py query_cdr_v2 --call-id <CallId1,CallId2,...>
# 2. 按被叫/主叫 + 时间窗列表查话单 (QuerySipRecord, 不需要 CallId)
python3 scripts/cdr_record.py query_sip_record \
[--callee <CalleePhone>] [--caller <CallerPhone>] \
[--begin-time-lower "2026-05-22 00:00:00"] \
[--begin-time-upper "2026-05-28 23:59:59"] \
[--sub-service-type 102] [--number-pool-no <NumberPoolNo>] \
[--call-status ANSWERED] [--limit 20] [--offset 0]
# 3. 获取录音文件下载 URL (顶层返回 DownloadUrl, 可直接复制下载)
python3 scripts/cdr_record.py query_record_url --call-id <CallId> \
[--business-type privacyNumber] [--expire-time 3600] \
[--save-to ~/Downloads/<CallId>.wav] # 可选: 直接落到本地
# 4. 获取录音 ASR 转文本下载 URL (V2, 单次最多 100 条)
python3 scripts/cdr_record.py query_asr_url --call-id <CallId1,CallId2,...>
标准流程
- 用户给
callId→ 直接query_cdr单条精查 + 必要时query_record_url拉录音. - 用户只给
SingleOpenId/ 手机号 / 时间区间 → 走「兜底」一节, 不要盲目调本 skill. - URL 有过期时间, 默认遵循平台值, 可用
--expire-time覆盖.
关键字段
返回字段一般包含: CallId / StartTime / RingTime / AnswerTime / EndTime / Duration / BillSec / CallStatus / Direction / PhoneA / PhoneX / PhoneB / SubsId. 录音字段包含 RecordFileUrl / RecordDuration / FileSize.
判断接通: AnswerTime 非空 / BillSec > 0 / CallStatus == ANSWERED.
错误兜底
Required List parameter 'CallIdList' is not present→ 你忘了传--call-id或 SingleOpenId 当 CallId 用了, 见上方限制.Result: []→ CallId 不存在 / 不属于本账号 / 在话单回调入库前就被查 (有秒级延迟).- 录音不存在 → 该次通话未开启录音, 检查绑定关系的
RecordFlag. - 控制台兜底: https://console.volcengine.com/cloud_vms/cdrList .
- 鉴权失败: 提示检查 AK/SK. 普通 agent (个人版 arkclaw / openclaw / coco / aime / claudecode) 检查
VOLC_ACCESS_KEY/VOLC_SECRET_KEY; 火山引擎 arkclaw 企业版需先在火山后台页面配置好 AK/SK, 再确认ARK_SKILL_API_KEY/ARK_SKILL_API_BASE已注入.
📚 基础知识 / 参数传递参考
构造 CallIdList / BusinessType / 时间区间 / 加密字段前, 请先阅读本 skill
内置的本地基础知识文档:
references/vms-fundamentals.md
该文档覆盖 SubServiceType 枚举 (101/102/103/104/201~206) / 号码状态映射 / CallId 各业务前缀 / 录音 CDN host / 出口 IP 白名单等通用规范. 所有 vms-* skill 共用同一份内容, 本地加载无外网依赖. 飞书原文 (可选): https://bytedance.sg.larkoffice.com/docx/Mv32dc0yooBn7txDxW8lsDdDgYb