byted-vms-cdr-record

name	byted-vms-cdr-record
version	2.0.0
description	火山云通信话单 / 录音查询 Skill. 用户问「查一下 callId xxx 的话单」「下载 xxx 的录音」时调用. 注意TOP 接口仅支持按 CallId 精确查询, 不支持按 SingleOpenId/手机号/时间区间反查.
license	Apache-2.0
metadata	{"author":"[e-mail]","homepage":"https://www.volcengine.com/docs/6358/166398?lang=zh","knowledge_base":"references/vms-fundamentals.md","openclaw":{"emoji":"📋","requires":{"env":["VOLC_ACCESS_KEY","VOLC_SECRET_KEY"]},"os":["darwin","linux"],"triggers":["查话单","查询话单","通话记录","下载录音","录音文件","录音下载链接","callId.*话单"]}}

byted-vms-cdr-record · 火山云通信话单/录音查询

环境变量

按以下优先级解析鉴权 (与其他 vms-* skill 一致):

1. ARK_SKILL_API_KEY + ARK_SKILL_API_BASE → 火山引擎 arkclaw 企业版. 请先在火山后台页面配置好 AK/SK, 由 arkclaw 注入这两个环境变量 (ARK_SKILL_API_KEY 为 API 密钥, ARK_SKILL_API_BASE 为 API 基础地址), 脚本以 Bearer 鉴权直连该网关, 无需本地签名;
2. 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) 签名;
3. 否则报错并提示用户填入 AK/SK.

重要前置说明 (TOP 限制)

QueryCallRecordMsg / QueryAudioRecordFileUrl 这两个接口在 TOP 网关上有以下硬约束 (实测):

• 必须传 CallIdList (form-urlencoded), 服务端校验直接报 Required List parameter 'CallIdList' is not present;
• 不接受按手机号 / 时间区间 / SingleOpenId 反查;
• SingleBatchAppend 返回的是 SingleOpenId 而不是 CallId, 这两者是不同字段, 无法相互转换.

因此, 想拿到 CallId 必须依赖以下两条之一:

1. 平台异步回调: 火山通信会在通话结束时把含 CallId 的话单 push 到业务方配置的回调地址;
2. 业务侧持久化: 业务后端在收到回调时把 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,...>

标准流程

1. 用户给 callId → 直接 query_cdr 单条精查 + 必要时 query_record_url 拉录音.
2. 用户只给 SingleOpenId / 手机号 / 时间区间 → 走「兜底」一节, 不要盲目调本 skill.
3. 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