Docs

从一个 API Key，到可观测的实时通信

API 是 VoxBridge 的能力真源。REST、MCP、Skill 与 CLI 共用 Project、Agent、Task、Event、Result 和 Usage 语义。

OpenAPI

完整 API 参考以 OpenAPI 3.1 规范提供，可导入 Postman、Insomnia 或 Swagger UI。

快速开始

注册并完成手机号验证，系统自动创建个人 Project 和本人号码 5 分钟试用。
在 Console 创建只含 calls:write、calls:read 的 API Key，密钥只显示一次。
从官方模板创建 Agent，先向注册手机号发起受控电话。
使用返回的 Task ID 读取事件、结果、失败原因和费用。

curl https://api.voxbridge.cn/v1/calls \
  -H "Authorization: Bearer $VOXBRIDGE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-call-001" \
  -d '{
    "agent_id": "agent_xxx",
    "from": "已配置主叫号码",
    "customer": {"number": "注册手机号", "name": "本人"}
  }'

curl https://api.voxbridge.cn/v1/tasks/task_xxx \
  -H "Authorization: Bearer $VOXBRIDGE_API_KEY"

auth_required 请先登录或运行 voxbridge auth login；trial_restricted 表示试用被叫不是已验证本人号码；payment_required 表示权益不足，新任务已被阻止，在途电话不会被中断。

四种接入方式，一套任务语义

REST API唯一能力真源，适合服务端和硬件 Agent 直接接入。POST /v1/calls

MCP让支持 MCP 的 Agent 创建、观察、取消任务并读取结果。create_call · watch_task_events

CLI用于本地调试、CI 和运营排障，返回与 API 相同的 Task ID。voxbridge calls create

Skill只组织参数并调用 MCP 或 API，不保存密钥、不维护独立状态。skills/voxbridge

无论从哪一层发起，状态、错误码、事件、结果和用量都以 API 返回为准。硬件 Agent 默认使用 REST API，受限设备可通过边缘网关接入。

认证

公开注册通过阿里云短信验证手机号并创建个人项目；团队成员仍由 owner 或 admin 使用一次性邀请加入。邀请令牌放在 URL fragment 中，24 小时内只能使用一次。CLI、MCP 和 Skill 使用设备授权，不把 API Key 写入 prompt；API/CI 使用 Bearer API Key。生产环境必须启用 API_AUTH_REQUIRED=1。API Key 支持启用、停用和撤销，撤销后不能恢复。

Authorization: Bearer vxb_live_xxx
Content-Type: application/json

voxbridge auth login
# 浏览器打开 https://voxbridge.cn/activate 并确认一次性验证码

PATCH /v1/api-keys/key_xxx
{ "status": "inactive" }

PATCH /v1/api-keys/key_xxx
{ "status": "revoked" }

核心资源

Project租户、权限、配额和账单边界。project_id

Template官方或社区 Agent 配置预设，只创建草稿，不是运行主体。GET /v1/templates

Agent保存身份、首句、系统提示词、声音、TurnProfile 和结束策略。POST /v1/agents

API Key按项目创建带 scope 的密钥，可停用或撤销，所有变更写入审计日志。PATCH /v1/api-keys/{id}

AgentVersion发布后的不可变通话配置，每通电话都记录版本。POST /v1/agents/{id}/publish

Call / Task一次通信请求及其业务状态，所有接入面返回同一个 Task ID。GET /v1/tasks/{id}

VoiceSession / Event媒体会话、供应商状态、实时事件和延迟事实。GET /v1/calls/{id}/events

Structured Output定义通话结束后的业务 JSON 字段。POST /v1/structured-outputs

Scorecard把真人感和业务完成度变成可复盘评分。POST /v1/scorecards

Webhook接收结构化结果、评分和通话事件。POST /v1/webhooks

Compliance维护授权来源、退订名单和频控规则，Call API 发起前统一检查。POST /v1/compliance/check

Security配置数据留存策略，查看账号、账单、Agent 和合规变更的审计日志。GET /v1/security/audit-logs

模板与生产审核

官方公开模板在注册并完成手机号验证后可低配额试用。自定义模板和自定义 AgentVersion 在审核前只能用于沙箱及白名单号码；进入外部真实通信、提高并发或申请机构配额前必须审核。

POST /v1/template-reviews
{
  "agent_version_id": "agentv_xxx",
  "intended_use": "客户预约确认",
  "identity_disclosure": "开场说明品牌和来电目的",
  "number_source": "用户主动留资",
  "frequency_policy": "每人每天最多 1 次",
  "opt_out_policy": "识别拒绝后立即结束并加入退订名单"
}

POST /v1/template-reviews/{id}/submit

状态固定为 draft → sandbox_testing → pending_review → approved | rejected | suspended。审核结果绑定不可变 AgentVersion 和风险等级，不复制 Agent 配置。

Call API

POST /v1/api-keys

{
  "project_id": "proj_demo",
  "name": "production-call-api",
  "scopes": ["calls:write", "calls:read"]
}

常用 scope：calls:write/calls:read 用于发起和读取通话，usage:read 用于读取用量；开发接入再加 agents:write、tools:write、webhooks:write、evals:write；账号、成员、支付、发票、合规和 API Key 管理必须使用 admin:manage。

POST /v1/calls
Authorization: Bearer vxb_live_xxx

{
  "agent_id": "agent_xxx",
  "customer": { "number": "18612109527", "name": "王先生" },
  "from": "09713884378",
  "variables": {
    "name": "王先生",
    "brand": "青海康养中心",
    "service": "健康回访"
  },
  "metadata": { "template_id": "service-followup" },
  "recording_enabled": false,
  "webhook_url": "https://example.com/voxbridge/callback"
}

常用后续操作：读取详情 GET /v1/calls/{id}，读取事件 GET /v1/calls/{id}/events，控制台结束测试通话 POST /v1/calls/{id}/hangup，导出证据包 GET /v1/calls/{id}/evidence。

结果与评分

通话结束后先生成结构化结果，再运行评分卡。两者都会写入 Call Detail，并可触发 Webhook。

POST /v1/calls/{call_id}/structured-output-runs
{ "structured_output_id": "out_xxx" }

POST /v1/calls/{call_id}/scorecard-runs
{ "scorecard_id": "score_xxx" }

服务回访模板默认输出 satisfaction、issue、needs_follow_up、summary；其他 7 个大陆场景模板也包含各自的业务字段。

Webhook

建议监听 structured_output.completed、scorecard.completed、call.completed、call.failed 和转写事件。每次投递都会记录状态码、签名和耗时。

有两种接入方式：项目级 Webhook 适合长期接入；单通 webhook_url 适合把某次 API 调用的结果回传到指定业务任务。

X-VoxBridge-Event: structured_output.completed
X-VoxBridge-Delivery: whd_xxx
X-VoxBridge-Timestamp: 1782200000
X-VoxBridge-Signature: v1=...

签名算法为 HMAC-SHA256：对 {timestamp}.{raw_body} 使用 Webhook secret 计算摘要。业务侧应校验时间戳和签名，写操作再做二次确认。

号码线路

中国大陆第一版聚焦授权服务电话。被叫建议使用 11 位手机号；主叫使用已配置并放行的固话或特服号码，例如 09713884378。

控制台的 Phone & Route 只开放已配置线路，后续再把电信、联通、移动 trunk 统一接入路由策略。

账单发票

Billing API 覆盖 Alpha 基础版与 Pro、Credit、用量、付款单、不可变账本和发票。Alpha 个人用户统一使用支付宝，机构客户可联系销售并使用对公转账。通话按接通后的实际秒数写入 UsageRecord，只对超出套餐的部分扣减 Credit；余额不足阻止新任务，但允许在途通话结束。跨通话记忆、周期提醒和共享呼入按类型化权益执行，不能仅靠前端隐藏。

GET /v1/entitlements
GET /v1/catalog/plans
GET /v1/catalog/credit-packs
GET /v1/contacts
GET /v1/reminders
GET /v1/billing/transactions

POST /v1/reminders
Idempotency-Key: reminder-001
{
  "agent_id": "agent_xxx",
  "reminder": "带上体检报告",
  "rule": "weekly",
  "timezone": "Asia/Shanghai",
  "next_run_at": "2026-08-19T10:00:00+08:00"
}

POST /v1/billing/orders
Idempotency-Key: demo-order-1
{ "plan_id": "basic", "provider": "alipay" }

POST /v1/billing/orders
Idempotency-Key: demo-order-2
{ "credit_pack_id": "credit-1000", "provider": "alipay" }

POST /v1/billing/webhooks/alipay

PATCH /v1/billing/invoice-profile
{
  "title": "大陆测试工作区",
  "tax_id": "91110108MA0000000X",
  "invoice_type": "electronic_vat_general",
  "email": "finance@example.cn"
}

POST /v1/billing/invoice-requests
{ "payment_record_id": "pay_xxx", "note": "6 月订阅开票" }

支付状态只能由验签后的支付宝/微信回调或受控财务流程更新，浏览器不能自行确认已付款。商户证书未配置时回调接口 fail closed，不产生账本入账。

信任控制

服务电话应记录授权来源，并提供退订、黑名单、频控、审计和数据留存配置入口。当前版本已经支持授权来源、退订/黑名单、频控检查、审计日志和留存策略；命中硬阻断后 Call API 会在拨号前返回错误，不进入线路。

POST /v1/compliance/do-not-call
{
  "phone_number": "18612109527",
  "reason": "用户退订",
  "source": "user_opt_out"
}

POST /v1/compliance/consents
{
  "phone_number": "18612109527",
  "source": "contract",
  "reference": "线下服务协议",
  "status": "active"
}

POST /v1/compliance/frequency-rules
{
  "name": "默认频控",
  "max_calls": 3,
  "window_hours": 24,
  "enabled": true
}

POST /v1/compliance/check
{ "phone_number": "18612109527" }

PATCH /v1/security/retention
{
  "call_record_days": 180,
  "transcript_days": 90,
  "recording_days": 30,
  "evidence_days": 180,
  "pii_masking_enabled": true
}

GET /v1/security/audit-logs?project_id=proj_demo

明确拒绝、忙碌或“不方便”时，Agent 应短句结束，不继续追问。