SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsbyted-vms-voice-notify

byted-vms-voice-notify

Office & productivity

View repository

Updated 10-15 17:30

About this skill

byted-vms-voice-notify · Volcengine Cloud Communication Voice Notification

Encapsulates the Volcengine Cloud Communication TOP voice notification API, supporting "single send", "batch task", "number pool query", "full lifecycle management of TTS templates (create / update / delete / query)", "recording file management (create / query / delete / direct upload)", and "general resource management (list / available / rename / delete)".

When to use

When the user expresses the following:

  • "Send a voice notification to 138xxxxxxxx", "call to remind by voice", "voice broadcast"
  • "Make outbound reminder calls to a batch of numbers", "create a voice notification task"
  • "Check my voice files / TTS templates", "what numbers are in my number pool"
  • "Create / update / delete / query TTS templates"
  • "Upload a recording (public URL)", "list my recordings", "delete this recording", "direct recording upload"
  • "List recording / IVR resources", "check available resources", "rename a recording", "delete a certain resource"

By default use SingleBatchAppend single send. Switch to CreateTask.

The only entry point for TTS / recordings / general resources: all TTS template operations (open_create_tts / delete_tts / list_resource --type 1) and all recording / general resource operations (create_voice / query_voice / delete_voice / get_upload_url / submit_upload / list_usable / update_resource / delete_resource) are within this skill. byted-vms-configure no longer provides any TTS / recording / resource entry point; it only retains cross-business query_risk_deny / query_can_call / query_auth.

Environment variables

Resolve authentication in the following priority order:

  1. ARK_SKILL_API_KEY + ARK_SKILL_API_BASE → Volcengine arkclaw Enterprise Edition. Please first configure AK/SK in the Volcengine backend 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 authenticate directly to this gateway using Bearer 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 ordinary agents; the user directly tells the agent the AK/SK, and the script performs local HMAC-SHA256 (Volc V4) signing;
  3. Otherwise, report an error and prompt the user to enter AK/SK.

Core commands

# 1. 查可用语音资源 (录音 type=0 / TTS 模板 type=1 / IVR type=2)
#    支持 --resource-key 精确过滤, 可替代独立的 query_tts.
python3 scripts/send_voice_notify.py list_resource \
    [--type 0|1|2] [--keyword 欠费] [--resource-key <ResourceKey>]

# 2. 查号码池
python3 scripts/send_voice_notify.py list_number_pool [--keyword 北京]

# 3. 单次发送语音通知 (SingleBatchAppend)
python3 scripts/send_voice_notify.py single_append \
    --phone <Phone> \
    --resource <ResourceKey> \
    --number-pool-no <NumberPoolNo> \
    [--type 0|1|2] \
    [--phone-param '{"name":"<UserName>"}'] \
    [--ring-again-times 1] [--ring-again-interval 5] \
    [--ext "biz=<BizTag>"]

# 4. 批量任务 (CreateTask)
python3 scripts/send_voice_notify.py create_task \
    --name "<TaskName>" \
    --type 1 \
    --resource <ResourceKey> \
    --number-pool-no <NumberPoolNo> \
    --start-time "2026-05-28 10:00:00" \
    --end-time   "2026-05-28 18:00:00" \
    --concurrency 5 \
    [--select-number-rule 1]   # 服务端必填: 1=随机 (默认) / 2=轮询 / 3=尾号匹配
    --phone-list-json '[{"Phone":"<Phone>","PhoneParam":{"name":"<UserName>"}}]'

# 5. TTS 模板生命周期 (本 skill 是 TTS 唯一入口)
#    5.1 创建 (审核后才能用)
python3 scripts/send_voice_notify.py open_create_tts \
    --content "您好, <模板文案>" --name "<模板名称>" [--lang zh] [--remark "..."]
#    注意: 仅当用户明确给出全部模板参数 (文案 + 语速/音调/音量等) 时才允许直接调用;
#    若用户仅提模糊的「定制化模板」诉求, 必须先引导跳转控制台手工配置, 见下文「定制化模板诉求」章节.

#    5.2 删除 (内部走 OpenDeleteResource; TOP 没有独立 OpenDeleteTts)
python3 scripts/send_voice_notify.py delete_tts --resource-key <ResourceKey>

#    注: TTS 模板平台不支持 OpenAPI 改文案 / 改名 / 改语速音调等;
#         如需调整请前往控制台手工修改并重审: https://console.volcengine.com/cloud_vms/voice-file

#    5.3 查询 (统一走 list_resource --type 1)
python3 scripts/send_voice_notify.py list_resource --type 1 \
    [--resource-key <ResourceKey>] [--keyword <Name关键字>]

# 6. 单次发送结果查询 (按 SingleOpenId)
python3 scripts/send_voice_notify.py query_single --single-open-id <SingleOpenId>

# 7. 单次发送取消 (尚未拨打前可取消)
python3 scripts/send_voice_notify.py cancel_single --single-open-id <SingleOpenId>

# 8. 批量任务追加号码 (BatchAppend, 单次 ≤ 1 万)
python3 scripts/send_voice_notify.py batch_append \
    --task-open-id <TaskOpenId> \
    --phones <PhoneA>,<PhoneB>
# 或用 JSON, 支持每个号码携带 PhoneParam:
python3 scripts/send_voice_notify.py batch_append \
    --task-open-id <TaskOpenId> \
    --phone-list-json '[{"Phone":"<Phone>","PhoneParam":{"name":"<UserName>"}}]'

# 9. 任务生命周期控制
python3 scripts/send_voice_notify.py pause_task  --task-open-id <TaskOpenId>
python3 scripts/send_voice_notify.py resume_task --task-open-id <TaskOpenId>
python3 scripts/send_voice_notify.py stop_task   --task-open-id <TaskOpenId>

# 10. 更新任务参数 (执行窗口 / 并发 / 重呼策略 / 禁呼时段)
python3 scripts/send_voice_notify.py update_task \
    --task-open-id <TaskOpenId> \
    [--start-time "2026-05-28 10:00:00"] [--end-time "2026-05-28 18:00:00"] \
    [--concurrency 5] \
    [--ring-again-times 1] [--ring-again-interval 5] \
    [--forbid-time-list-json '[{"BeginTime":"12:00","EndTime":"13:30"}]'] \
    [--recall true]

# 11. 录音文件管理
#     11.1 上传录音 (TOP 没有 OpenCreateVoice, 必须走直传两步法)
#          step1: 申请直传 URL
python3 scripts/send_voice_notify.py get_upload_url \
    --file-name hello.wav --content-type audio/wav --sub-service-type 102
#          step2: 用返回的 UploadUrl 直接 PUT 文件 (curl/客户端自行完成)
#          step3: 提交注册
python3 scripts/send_voice_notify.py submit_upload \
    --upload-id <UploadId> --name "欢迎语" --sub-service-type 102
#          (旧的 create_voice 子命令已弃用, 调用会返回 ApiNotSupported 引导文案)
#     11.2 查录音 (按 ResourceKey 精确 / Name 模糊本地过滤)
python3 scripts/send_voice_notify.py query_voice \
    [--sub-service-type 102] [--resource-key <Key>] [--name 关键词] [--limit 20]
#     11.3 删除录音
python3 scripts/send_voice_notify.py delete_voice --resource-key <ResourceKey>

# 12. 通用资源管理
#     12.1 查可用 (审核通过) 资源
python3 scripts/send_voice_notify.py list_usable --type 0   # 0录音 1TTS 2IVR
#     12.2 改资源 Name (录音/IVR; TTS 模板不支持改名)
python3 scripts/send_voice_notify.py update_resource --resource-key <Key> --name "新名字"
#     12.3 通用资源删除 (TTS 请用 delete_tts)
python3 scripts/send_voice_notify.py delete_resource --resource-key <Key>

Standard execution flow (SingleBatchAppend)

  1. Pre-check 1: resource. When the user has not specified Resource , first list_resource --keyword <用户语义>. If not found:
    • If the user expresses a "customized template" requirement (for example, requesting adjustments to speech rate / pitch / volume / voice timbre / pauses / multi-variable substitution or any other template details, butwithout providing specific parameter values), do notdirectly open_create_tts, instead guide the user to jump to the console to configure manually: https://console.volcengine.com/cloud_vms/voice-file , on that page click "File to Voice Template"; when adding a template, you can edit parameters such as "speech rate / pitch / volume"; after submission, wait for review;
    • Only when the user has explicitly provided complete template parameters (script text + speech rate + pitch + volume, etc.) is it allowed to directly help the user proceed with open_create_tts automatic creation; the template requires review, and returns ResourceKey Have the user follow up on the review status later;
    • If the user simply did not find a suitable ready-made resource and has no customization requirements, you can also direct them to https://console.volcengine.com/cloud_vms/voice-file add a resource.
  2. Pre-check 2: Number pool. When the user has not specified NumberPoolNo , call list_number_pool to take the first NumberCount > 0 pool. If there is none, prompt the user to purchase a number: https://console.volcengine.com/cloud_vms/number.
  3. Formal call: assemble parameters → single_append. SingleOpenId is generated internally by the script using uuid.uuid4().hex , achieving idempotency.
  4. Result normalization: on failure, the script outputs errorCode + suggest, and the Agent translates it directly for the user; on success it returns MessageId / RequestId.

Cross-skill collaboration (business layer ↔ general layer)

This skill (byted-vms-voice-notify) isthe business layer, and at the same time is the TTS / recording / general resources sole management entry point. Other general configurations such as number pools / qualifications / call records are explicitly dispatched by the Agent to the correspondinggeneral-layer skill:

User request Dispatched skill Command example
Create / delete TTS byted-vms-voice-notify (this skill) open_create_tts / delete_tts (renaming/editing text is not supported; use the console)
Query TTS templates byted-vms-voice-notify (this skill) list_resource --type 1 [--resource-key <Key>]
Upload / delete / query recordings byted-vms-voice-notify (this skill) create_voice / query_voice / delete_voice
Direct recording upload (large files) byted-vms-voice-notify (this skill) get_upload_url → client PUT → submit_upload
List recordings / IVR / TTS byted-vms-voice-notify (this skill) `list_resource --type 0
Query available resources / rename resources / general deletion byted-vms-voice-notify (this skill) list_usable / update_resource / delete_resource
Risk control blacklist / reachability / caller authentication byted-vms-configure query_risk_deny / query_can_call / query_auth
Create / query number pool byted-vms-number-pool create_pool / list_pool
Submit / query qualification byted-vms-number-pool add_qualification / query_qualification
Query call records / query recording file URL byted-vms-cdr-record query_cdr / query_record_url

Important: All TTS / recording / general resource operations are handled by this skill without exception. Do notdispatch byted-vms-configure. byted-vms-configure again. It no longer encapsulates these interfaces, and only retains cross-business number risk control / reachability / authentication queries.

Standard execution flow (CreateTask)

Use only when the user explicitly says "create task / batch task / scheduled outbound call". The flow is the same as above, with additional requirements:

  • Name: if the user does not specify one, automatically name it based on semantics;
  • StartTime / EndTime: task execution window;
  • Concurrency: concurrency, default 1;
  • PhoneList: pass in an array via --phone-list-json (Phone is required; PhoneParam / TtsContent / Ext are optional).

Standard execution flow (recording file / direct recording upload)

TOP does not have OpenCreateVoice this kind of open interface for "creating a recording by public URL". Recording registration uniformly uses the two-step direct upload method. The old create_voice subcommand is retained as a compatibility entry; calling it will return ApiNotSupported + guidance, and will not actually send a request.

Direct recording upload (unified flow, applicable to both large and small files)

  1. Call get_upload_url to get UploadId + UploadUrl;
  2. The client uploads the file by itself using PUT to UploadUrl;
  3. Call submit_upload using UploadId to register it as a formal recording resource and enter the review process;
  4. Afterward, use query_voice to query AuditStatus.

Custom TTS template requirements (hard constraints)

When the user raises acustom voice notification template-related request, for example:

  • "Help me make a slow-broadcast template / a template with higher volume / a template with a different timbre"
  • "I want the template to control speech rate, pitch, and volume"
  • "Make a voice template suitable for elderly people to listen to"

Default behavior: Do notdirectly call open_create_tts to automatically create it for the user. You must first guide the user to jump to the console for manual configuration:

It is recommended to go to the Volcano Cloud Communication console to manually create a template and visually set the parameters:

https://console.volcengine.com/cloud_vms/voice-file

After entering, click "File to Voice Template" -> "Add Template", and you can edit in the same form:

  • Speech rate (Speed): -0.5x ~ 5.0x (default 1.0x, i.e. normal speech rate; less than 1.0x slows it down, greater than 1.0x speeds it up)
  • Pitch (Pitch): -50% ~ 50% (default 0%; negative values are deep, positive values are sharp)
  • Volume (Volume): 0 ~ 30 (default 15; the larger the value, the louder the sound)
  • Copy / placeholder variables / remarks, etc.

After submission, wait for review (AuditStatus=1) to pass before it can be used.

Exception (automatic creation allowed): if and only if the user in the requesthas explicitly provided all necessary parameters—at least including "copy + speech rate + pitch + volume"—the Agent may schedule open_create_tts to directly implement it. If any parameter is missing, it is regarded as "no specific parameters provided", and you must return to the jump guidance above.

Determination process:

用户提到「定制 / 自定义 / 调语速 / 调音量 / 调音调 / 换音色 / 个性化模板」?
  ├─ 是 → 用户给出了「文案 + 语速 + 音调 + 音量」全部具体值?
  │        ├─ 是 → 可调用 open_create_tts (附带各参数)
  │        └─ 否 → 引导跳转 https://console.volcengine.com/cloud_vms/voice-file 手工配置
  └─ 否 → 走标准 list_resource / open_create_tts 流程

Error fallback

  • Account not real-name verified: guide the user to go to https://console.volcengine.com/user/authentication/enterprise/.
  • Qualification not passed / missing number pool / missing resources: see scripts/_topclient.py of ERROR_MAP, when all commands fail, the suggest field will be attached.
  • Authentication failed: prompt to check AK/SK. For ordinary agents (personal edition arkclaw / openclaw / coco / aime / claudecode), check VOLC_ACCESS_KEY/VOLC_SECRET_KEY; for the Volcano Engine arkclaw enterprise edition, you need to first configure AK/SK on the Volcano backend page, then confirm that ARK_SKILL_API_KEY/ARK_SKILL_API_BASE has been injected.

Reference interfaces

📚 Basic knowledge / parameter passing reference

SingleBatchAppend of PhoneParam field needs to align with the template placeholders, CreateTask of the PhoneList array structure,open_create_tts speech rate / pitch / volume values, as well as the UploadId flow for direct recording upload, are all explained in the local basic knowledge document built into this skill:

references/vms-fundamentals.md

This document covers general specifications such as SubServiceType=102 / number status mapping / CallId business prefix (V) / recording CDN host / egress IP whitelist, etc. It is shared by all vms-* skills, loaded locally with no external network dependency. Feishu original text (optional): https://bytedance.sg.larkoffice.com/docx/Mv32dc0yooBn7txDxW8lsDdDgYb