create-phone-number

Vapi 电话号码设置

默认提供请求载荷或实施计划。只有用户明确要求执行实际变更时，才配置、导入、路由或释放号码。在配置号码或执行其他可能产生费用的操作前，必须立即再次获得用户的明确确认。

安全与来源规则

• 切勿在聊天中索要运营商密码、身份验证令牌、API 密钥、API 密文或私钥。
• 如果当前公开架构支持使用现有 Vapi credentialId，则在导入服务商号码时使用它。如果所需凭据不存在，请停止操作并说明该 API 前置条件。
• 如果公开 API 要求提供运营商原始密钥，且没有基于凭据的替代方案，请从本地环境变量中读取密钥，不要显示密钥、将其写入请求载荷文件，也不要记录请求正文。
• 根据当前的 Create Phone Number API 或公开的 OpenAPI 架构核实服务商字段。
• 切勿编造电话号码、SIP 域、凭据、资源 ID、区号可用性或路由目标。

流程

1. 确定执行模式。

   • 如果用户要求草稿，或未明确授权执行实时变更，则返回有效载荷或计划。
   • 对于实时请求，确认已设置 VAPI_API_KEY，但不要打印其值。

2. 选择传输路径。

   • 对于普通号码的非技术请求，优先使用文档所述的 Vapi 托管美国 PSTN 路径。
   • 只有用户明确要求 SIP 时才使用 SIP。要求用户提供准确且受支持的 SIP URI，或从当前公开 API 文档中获取；如果无法获取，则停止并说明缺少的前提条件。不要编造区域 realm。
   • 只有当用户拥有该号码且具备所需的安全凭证路径时，才使用运营商导入方式。

3. 在变更前解析路由。

   • 通过公开端点列出或获取助手和 squads。将用户提供的名称匹配到一个资源。
   • 如果有多个可能的资源，请用户选择。绝不要猜测 ID。
   • 路由到一个 assistantId 或一个 squadId；更改现有路由时，清除冲突的目标字段。

4. 安全检查库存。

   • 使用 GET /phone-number 检查现有电话号码，避免重复配置。
   • 当前公开的 OpenAPI 接受 numberDesiredAreaCode，但未提供公开的可用区号库存端点。向用户说明无法保证能满足需求后，接受其指定的三位美国区号。
   • 不要为了测试可用性而购买号码。不要根据一次号码配置响应推断全球范围内都不可用。

5. 确认并执行。

   • 显示提供商、区号或确切的自有号码、路由目标，以及该操作是否可能产生运营商或使用费用。
   • 在执行 POST /phone-number 或其他可能产生费用的变更前，立即获取用户明确确认。
   • 验证响应中的 id、提供商、号码或 SIP URI、存在时的状态，以及已解析的路由。

6. 更新时不破坏配置。

   • 先执行 GET /phone-number/{id}。
   • 构建特定于提供商的更新 DTO。仅更改用户要求的可写字段，并根据公开 schema 的要求，通过省略或原样带上当前提供商、hooks、server、备用目标和特定于提供商的设置来保留它们。
   • 不要发送仅用于响应的字段，例如 id、时间戳或组织元数据。
   • 重新获取号码，并验证所请求的路由或设置。

7. 准确处理失败。

   • 400：报告被拒绝的字段或不可用的请求；先修正文档所述的格式错误，最多重试一次。
   • 401/403：Vapi 身份验证或权限问题，停止操作。
   • 404：报告缺失的电话号码、助手、squad 或凭证。
   • 5xx：报告 Vapi 服务故障，不要声称操作成功。
   • 将运营商侧的所有权、凭证、号码配置或传输故障与 Vapi 路由配置问题区分开。

Vapi 免费号码限制

Vapi 托管的免费号码仅供美国境内使用，每个账户最多可申请五个。无需支付方式即可申请第一个免费号码。申请其他免费号码需要账户中留有支付方式，但号码本身仍然免费。

Vapi 免费号码仅支持向美国 +1 目的地拨打出站电话，不支持国际通话。国际使用请采用导入的提供商号码或受支持的 SIP／运营商路径。不要将免费号码描述为可无限使用的生产级电话服务。

仅含有效载荷的示例

此模板不会配置任何内容：

{
  "provider": "vapi",
  "numberDesiredAreaCode": "<confirmed-three-digit-area-code>",
  "assistantId": "<verified-assistant-id>",
  "name": "Main Support Line"
}

阅读 提供商 API 流程，了解 Vapi 托管、Twilio、Vonage、Telnyx、自带运营商和路由示例。用户要求 TypeScript、Python 或 cURL 实现代码时，请阅读 电话号码 API 示例。不要在实时请求中使用占位符。

公开资料

• 电话呼叫和电话快速入门
• 创建电话号码 API
• 免费 Vapi 电话号码
• 导入 Twilio 号码