byted-vms-number-pool

byted-vms-number-pool · number pools / numbers / qualifications

Environment variables

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

ARK_SKILL_API_KEY + ARK_SKILL_API_BASE → Volcano Engine arkclaw enterprise edition. Please first configure AK/SK on the Volcano backend page, and arkclaw will inject these two environment variables (ARK_SKILL_API_KEY is the API key, ARK_SKILL_API_BASE is the API base address), the script connects directly to this gateway with Bearer for authentication, no local signature needed;
VOLC_ACCESS_KEY + VOLC_SECRET_KEY (compatible with VOLCENGINE_ACCESS_KEY/VOLCENGINE_SECRET_KEY) → ordinary agents such as personal edition arkclaw / openclaw / coco / aime / claudecode, where the user directly tells the agent the AK/SK, and the script performs local HMAC-SHA256 (Volc V4) signing;
Otherwise report an error and prompt the user to enter AK/SK.

Commands

# 1. 查号码池 (默认 SubServiceType=102 语音通知, 智能外呼填 104, 隐私号填 201~206)
#    完整枚举见 references/vms-fundamentals.md §1
python3 scripts/number_pool.py list_pool [--sub-service-type 102] [--name 北京]

2. Create a number pool

python3 scripts/number_pool.py create_pool
--name "Voice Notification-Default Pool" --sub-service-type 102
--qualification-id [--choose-pretty false]

2.1. Update a number pool (rename/change remark/change qualification)

python3 scripts/number_pool.py update_pool
--number-pool-no
[--name "New name"] [--remark "New remark"] [--qualification-id ]

3. Query numbers under a number pool

python3 scripts/number_pool.py list_number --number-pool-no

3.0. Reverse lookup of the number pool a mobile number belongs to + number details (the entry point for business layer skills when only a number is available) If --sub-service-type is not passed, it defaults to 101108 / 201206 default sequential traversal; On hit returns { ok:true, NumberPoolNo, SubServiceType, Pool, Number }, On miss returns { ok:false, errorCode:"NUMBER_NOT_FOUND" }.

python3 scripts/number_pool.py query_number --phone [--sub-service-type 201]

3.1. Apply for a number (buy number / add to pool) The platform has not opened OpenAPI write access; the command only returns console guidance information. Please go to the https://console.volcengine.com/cloud_vms/number page and click the "Apply for Number" action.

python3 scripts/number_pool.py apply_number
[--number-pool-no ] [--count 5] [--qualification-id ]

3.2. Query application records (QueryNumberApplyRecordList, to see review progress/number ownership/quantity, etc.)

python3 scripts/number_pool.py query_apply_record
[--number-pool-no ] [--sub-service-type 102]
[--apply-status 7] [--limit 20] [--offset 0]

4. Enable/disable numbers

python3 scripts/number_pool.py toggle_number
--number-pool-no --phone-list , --enable true

5. Submit a qualification

python3 scripts/number_pool.py add_qualification
--payload '{"Name":"xx Co., Ltd.","QualificationType":0,"BusinessType":1,...}'

5.1. Upload qualification materials (images or PDFs such as business license/ID card, FileUrl must be publicly accessible)

python3 scripts/number_pool.py upload_qualification_file
--file-url "https://your-tos.com/license.jpg"
--qualification-id
--file-type 1 --file-name "Business License"

6. Query a qualification (single detailed query)

python3 scripts/number_pool.py query_qualification [--status 1]

6.1. Query the qualification list (QueryQualificationList, recommended, doc=173331) Supports filtering by entity name/status/qualification type/business type, with normalized Items fields

python3 scripts/number_pool.py list_qualification
[--status 1] [--name "Guangzhou"]
[--qualification-type 0] [--business-type 3]
[--limit 20] [--offset 0]

7. Update a qualification

python3 scripts/number_pool.py update_qualification
--qualification-id --payload '{"BusinessType":2}'


## 何时被业务层 Skill 调用

- `byted-vms-voice-notify` 预检号码池 → `list_pool --sub-service-type 102`
- `byted-vms-aicall` 预检 → `list_pool --sub-service-type 104`
- `byted-vms-secret-number` 预检 → `list_pool --sub-service-type 201` (或其他隐私号子类型 202~206)
- 业务层只拿到号码 (例如 X 号、A 号) 需要 NumberPoolNo 时 → `query_number --phone <X>`,
  Agent 拿到返回里的 `NumberPoolNo` 后再去调用业务层接口 (如
  `byted-vms-secret-number query_subscription_list` / `unbind_*`).

业务层 Skill 通过 Agent 触发本 Skill 执行命令, 拿回结果后再决定下一步, **不直接 import 本包的 python**.

## 错误兜底

- 资质 `Status=0` (待审核) → 提示用户审核约 1 工作日, 期间不能创建号码池.
- 资质 `Status=2` (驳回) → 引导用户用 `update_qualification` 修改后重新提交.
- 没有任何号码池 → 引导用户先 `add_qualification` → `create_pool` → 在控制台购号 https://console.volcengine.com/cloud_vms/number .
- **申请号码 / 购号**: 平台 **未开放 OpenAPI 写入**, 用户调 `apply_number` 时
  返回控制台引导, **必须前往 https://console.volcengine.com/cloud_vms/number
  页面点击「申请号码」操作**, 提交申请单等待平台审核, 审核通过后号码自动入池.
  申请进度可用 `query_apply_record` 接口查询.
- 鉴权失败: 提示检查 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` 已注入.

## 📚 基础知识 / 参数传递参考

`add_qualification` 的 `payload` 字段对资质类型 (QualificationType) /
业务类型 (BusinessType) / 主体材料字段有强约束, `create_pool` /
`update_pool` 的 SubServiceType (101/102/103/104/201~206) 不能混用.
这些通用规范沉淀在本 skill 内置的本地基础知识文档:

> `references/vms-fundamentals.md`

所有 vms-* skill 共用同一份内容. 本地加载无外网依赖, 比拉飞书更快更稳.
飞书原文 (可选): https://bytedance.sg.larkoffice.com/docx/Mv32dc0yooBn7txDxW8lsDdDgYb

About this skill

Environment variables

Commands