Vox Hosted Phone Agent

Vox Hosted Phone Agent is a zero-install hosted phone skill. It does not provide local runtime code. Use the hosted HTTPS endpoint declared in skill.json or openapi.yaml.

When To Use

Use this skill when the user asks to:

• make a phone call or outbound call
• send a phone notification
• remind someone by phone
• invite, confirm, or follow up by phone
• create a custom phone agent for a trial call

Chinese trigger examples:

• 帮我给客户打电话
• 给 13800138000 打电话通知会议改期
• 电话回访一下客户满意度
• 打电话提醒对方明天下午参加演示

Safety Rules

Outbound calls have real side effects. Follow these rules:

• Do not set confirmed=true unless the user explicitly confirms the call.
• Do not set noCall=false unless the user explicitly confirms the phone number, call purpose, and message content.
• Use noCall=true for preview and discovery flows.
• If the response status is preview_ready, ask the user to confirm before placing the call.
• If the response status is needs_input, ask for the missing fields.
• If the response status is blocked or failed, explain the reason and do not retry automatically.
• Never expose API credentials, signatures, or internal logs to the user.
• Do not place calls for fraud, harassment, impersonation, illegal requests, or requests that ask for passwords, verification codes, or money transfers.

Invocation

Send an HTTPS POST request to the hosted endpoint:

POST https://vox-test.teddymobile.net/portal-api/api/hosted-skills/vox/custom-phone-agent/invoke
Content-Type: application/json

Promotion mode currently does not require an API key. If a future deployment enables API key auth, the platform should inject:

X-Vox-Hosted-Skill-Key: hsk_xxx

Request Shape

{
  "prompt": "帮我给 13800138000 打电话，通知他明天下午三点会议改到四点，地点不变，用知言音色。",
  "context": {
    "source": "skillhub",
    "host": "generic-agent",
    "sessionId": "sess_xxx",
    "userId": "user_xxx",
    "tenantId": "tenant_xxx",
    "locale": "zh-CN"
  },
  "mode": "trial",
  "confirmed": false,
  "noCall": true,
  "idempotencyKey": "agent_sess_xxx_preview_001"
}

Response Handling

Handle statuses as follows:

Real Call Flow

Recommended sequence:

1. First request with noCall=true and confirmed=false.
2. Show the preview to the user.
3. Ask the user to confirm the phone number and call content.
4. Only after explicit confirmation, send a second request with confirmed=true and noCall=false.

Notes For Agent Platforms

• This is a hosted capability, not a downloadable runtime skill.
• Do not look for resources/index.js; this package intentionally has no executable resources.
• Use openapi.yaml if your platform supports OpenAPI tools.
• Use examples/ for request body samples.