Vox Custom Phone Agent Skill\r

\r Turn a user's natural-language phone task into a TeddyMobile Vox botType=custom outbound call.\r \r This skill is designed for Agent or Claw environments. It extracts the call target, bot identity, business goal, tone, constraints, and opening message from the user's prompt. When required information is missing, it asks targeted follow-up questions. Once the required fields are complete, it builds a Vox custom bot payload and starts the outbound call.\r \r

What This Skill Does\r

\r

• Parses natural-language prompts into a structured custom phone-agent task.\r
• Guides the user when required fields are missing.\r
• Generates Vox extra.agent_profile for botType=custom.\r
• Requires the user to choose a Vox voiceType by code or voice name.\r
• Validates phone numbers and blocks unsafe phone tasks.\r
• Calls POST https://vox.teddymobile.cn/vox/v1/outbound with HMAC authentication.\r
• Returns the Vox request status and generated requestId.\r \r

What This Skill Does Not Do\r

\r

• It does not implement real-time HTTP POST + SSE conversation control.\r
• It does not receive live call transcripts.\r
• It does not expose or ship real Vox secrets in the skill package.\r
• It does not support batch outbound calls in the MVP.\r
• It does not run dry-run previews. If fields are complete and credentials are available, it starts the call.\r \r

Required Runtime Configuration\r

\r For direct Vox calls from the host environment:\r \r

• VOX_APP_ID\r
• VOX_SECRET\r \r Optional:\r \r
• VOX_BOT_ID - may be empty for botType=custom if Vox has enabled that mode.\r
• VOX_OUTBOUND_BASE_URL - defaults to https://vox.teddymobile.cn.\r
• VOX_CREDENTIALS_FILE - path to a JSON credentials file.\r
• VOX_TRIAL_MODE - when true, result messages include registration guidance.\r
• VOX_REGISTER_URL - registration or trial application URL.\r
• VOX_TRIAL_LIMIT - maximum local trial call attempts, defaults to 10.\r
• VOX_TRIAL_STATE_FILE - optional path for local trial usage state.\r \r Recommended hosted mode:\r \r
• Keep VOX_SECRET only on your backend.\r
• Let Agent or Claw call your backend, and let your backend call Vox.\r
• Never publish real credentials in the skill package.\r \r

Trial-To-Registration Flow\r

\r When VOX_TRIAL_MODE=true, the skill treats the configured credentials as promotion trial credentials. After generating or starting a call, it guides the user to register for formal Vox access so they can get their own VOX_APP_ID, VOX_SECRET, permissions, quota, and number resources.\r \r The trial journey must be visible to the user:\r \r

• Before missing-field prompts, mention that the user is currently in promotion trial mode.\r
• After a call request is generated or started, say that the trial experience has been completed first.\r
• Show visible trial usage, such as 已使用 1/10 次，剩余 9 次.\r
• Then give a clear call to action to register for formal enterprise access, including the registration URL and the benefits of registering.\r \r For hosts such as WorkBuddy that render structured fields instead of full text, the skill also returns top-level fields: actionPrompt, actions, buttons, quickReplies, suggestedActions, registrationMessage, registrationUrl, registrationBenefits, registrationSwitchInstruction, and nextStep. Hosts should display these after trial calls. If button rendering is supported, render actions or buttons so the user can choose 注册正式账号, 继续试用, or 我已有正式凭证.\r \r The skill also returns callTask, taskBriefing, briefingQuality, resultMeaning, failureAdvice, risk, voiceAnalysis, summaryRows, and summaryFooter so hosts can render a clearer task summary and explain that accepted means Vox accepted the outbound task, not that the call has completed.\r \r

Required User Information\r

\r The skill must have these fields before it can start a call:\r \r

1. callee - destination mobile phone number.\r
2. goal - what the call should accomplish.\r
3. role - who the bot is calling as, unless the role can be safely inferred from the scenario.\r
4. voiceType - user-selected voice code or voice name.\r
5. useMode - user chooses promotion trial or formal account mode.\r
6. businessContext - scenario-specific details when the prompt is too generic.\r \r Fields that may be inferred or generated:\r \r

• name\r
• gender\r
• age\r
• communicationStyle\r
• background\r
• skills\r
• workflow\r
• constraint\r
• openingPrompt\r
• requestId\r \r Voice options:\r \r
• 0 / 知愈：女，适合安抚、售后回访、心理陪伴。\r
• 1 / 安辰：男，适合长辈、老人、用药或健康提醒。\r
• 2 / 景珩：男，适合商务、课程、企业合作、科普讲解。\r
• 3 / 知言：女，适合通知、公告、正式播报。\r
• 4 / 星苒：女，适合闲聊、电商、生活服务。\r \r

User Guidance Rules\r

\r If a required field is missing, do not call Vox. Ask a concise follow-up question.\r \r Examples:\r \r

• Missing phone number: "请提供要拨打的手机号。"\r
• Missing goal: "请说明这通电话希望达成什么目标，例如通知、预约确认、回访或邀约。"\r
• Missing role: "请说明 Bot 应以什么身份联系对方，例如客服、课程顾问、招聘助理、会议通知助理或商务经理。"\r
• Missing voice: "请选择音色：0 知愈；1 安辰；2 景珩；3 知言；4 星苒。"\r
• Missing use mode: "请选择使用方式：1 先用推广试用体验一次；2 使用正式账号/注册 Vox 企业账号后接入。回复“试用”或“正式注册”即可。"\r
• Missing business context: "请补充更具体的业务背景，例如事项内容、时间、对象、处理边界和对方不同反馈时的跟进方式。"\r
• Multiple missing fields: "请补充两个信息：要拨打的手机号；这通电话希望达成的具体目标。"\r \r For chat or companionship scenarios, require additional boundaries before calling: caller identity, chat purpose, allowed topics, forbidden topics, duration or stop condition, and refusal handling.\r \r Ask at most two questions at a time. Use the existing conversation context to merge follow-up answers into the pending call intent.\r \r

Safety Policy\r

\r Block or require rewriting for requests that involve:\r \r

• Impersonation of banks, government, police, courts, or official institutions.\r
• Asking for verification codes, passwords, bank cards, or private credentials.\r
• Threats, harassment, abusive language, coercion, or illegal debt collection.\r
• Investment inducement, transfer requests, illegal sales, or fraud-like behavior.\r
• Medical, legal, or financial promises beyond basic notification or appointment reminders.\r \r If blocked, explain briefly and suggest a compliant alternative.\r \r

Typical Prompt\r

\r

先试用。帮我给 13800138000 打电话，作为课程顾问介绍周末 AI 编程体验课，目标是确认是否愿意预约试听，语气专业但不要强推，使用景珩音色。\r
```\r
\r
## Typical Result\r
\r
```text\r
已发起 Vox 自定义 Bot 外呼。\r
\r
- 被叫号码：138****8000\r
- Bot 角色：课程顾问\r
- 任务目标：确认是否愿意预约试听\r
- requestId：req_20260522153000001_ab12cd\r
- 状态：accepted\r
```\r
\r
## Implementation Entry Points\r
\r
- Workflow: `workflow.md`\r
- Demo runner: `resources/run_demo.js`\r
- Hosted API example: `resources/hosted_api_example.js`\r
- Direct Vox client: `resources/hmac_outbound_client.js`\r
- Intent extraction and completion: `resources/prompt_to_call_intent.js`, `resources/intent_completeness.js`\r
- Profile generation: `resources/prompt_to_agent_profile.js`\r