SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsbyted-vms-cdr-record

byted-vms-cdr-record

Data & analytics

View repository

Updated 10-15 17:30

About this skill

byted-vms-cdr-record · Volcano Cloud Communication CDR/Recording Query

Environment Variables

Resolve authentication in the following priority order (consistent with other vms-* skills):

  1. ARK_SKILL_API_KEY + ARK_SKILL_API_BASE → Volcano Engine arkclaw Enterprise Edition. Please first configure AK/SK on the Volcano console page; arkclaw will inject these two environment variables (ARK_SKILL_API_KEY is the API key, ARK_SKILL_API_BASE is the API base address), and the script will use Bearer to authenticate and connect directly to this gateway, with no local signing required;
  2. VOLC_ACCESS_KEY + VOLC_SECRET_KEY (compatible with VOLCENGINE_ACCESS_KEY/VOLCENGINE_SECRET_KEY) → Personal Edition arkclaw / openclaw / coco / aime / claudecode and other regular agents, where the user directly tells the agent the AK/SK, and the script performs HMAC-SHA256 (Volc V4) signing locally;
  3. Otherwise, report an error and prompt the user to enter AK/SK.

Important Prerequisite Notes (TOP Limitations)

QueryCallRecordMsg / QueryAudioRecordFileUrl These two APIs have the following hard constraints on the TOP gateway (as tested):

  • Must pass CallIdList (form-urlencoded), otherwise the server-side validation directly reports Required List parameter 'CallIdList' is not present;
  • Does not accept reverse lookup by phone number / time range / SingleOpenId;
  • SingleBatchAppend returns SingleOpenId rather thannot CallId; these two are different fields and cannot be converted into each other.

Therefore, to obtain CallId , you must rely on one of the following two:

  1. Platform asynchronous callback: Volcano Communication will push the CDR containing CallId to the callback address configured by the business party when the call ends;
  2. Business-side persistence: When the business backend receives the callback, it stores the single_open_id ↔ call_id mapping in its own storage, and later reverse-looks up the CallId by SingleOpenId.

If the user only has SingleOpenId or the called number, without CallId, do not attempt to call this skill's query_cdr; instead, clearly inform the user of this limitation and guide them to check it in the console https://console.volcengine.com/cloud_vms/cdrList , or reverse-look up the CallId by SingleOpenId on the business side, or switch to query_sip_record (query the list by called/calling number + time window).

Command

# 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,...>

Standard Procedure

  1. User provides callId → directly query_cdr single-record exact query + if necessary query_record_url to fetch the recording.
  2. Useronlyprovides SingleOpenId / phone number / time range → follow the "Fallback" section, and do not blindly call this skill.
  3. URLs have an expiration time; by default follow the platform value, which can be overridden with --expire-time .

Key Fields

Returned fields generally include: CallId / StartTime / RingTime / AnswerTime / EndTime / Duration / BillSec / CallStatus / Direction / PhoneA / PhoneX / PhoneB / SubsId. Recording fields include RecordFileUrl / RecordDuration / FileSize.

Determine connected: AnswerTime non-empty / BillSec > 0 / CallStatus == ANSWERED.

Error Fallback

  • Required List parameter 'CallIdList' is not present → you forgot to pass --call-id or used SingleOpenId as CallId; see the limitations above.
  • Result: [] → CallId does not exist / does not belong to this account / was queried before the CDR callback was stored (there is a second-level delay).
  • Recording does not exist → recording was not enabled for this call; check the binding relationship's RecordFlag.
  • Console fallback: https://console.volcengine.com/cloud_vms/cdrList .
  • Authentication failed: prompt to check AK/SK. For regular agents (Personal Edition arkclaw / openclaw / coco / aime / claudecode), check VOLC_ACCESS_KEY/VOLC_SECRET_KEY; for Volcano Engine arkclaw Enterprise Edition, first configure AK/SK on the Volcano console page, then confirm that ARK_SKILL_API_KEY/ARK_SKILL_API_BASE has been injected.

📚 Basic knowledge / Parameter passing reference

Construct CallIdList / BusinessType / Before the time range / encrypted fields, please first read this skill's built-in local basic knowledge document:

references/vms-fundamentals.md

This document covers general specifications such as the SubServiceType enum (101/102/103/104/201~206) / number status mapping / CallId business prefixes / recording CDN host / egress IP whitelist, etc. All vms-* skills share the same content, loaded locally with no external network dependency. Feishu original text (optional): https://bytedance.sg.larkoffice.com/docx/Mv32dc0yooBn7txDxW8lsDdDgYb