create-campaign

Vapi 外呼活动

如果需要统一管理持久化外呼任务的联系人、生命周期和结果，请使用 Campaigns。创建 Campaign 会立即启动或按计划时间启动；没有草稿状态或单独的启动操作。

当前公开 API 使用 /v2/campaign。未版本化的 /campaign 端点属于旧版，行为不同。新集成请使用 /v2/campaign；只有用户明确要求维护现有旧版集成时，才使用 /campaign。

来源与安全规则

• 请通过当前 Vapi 文档 MCP、Campaigns 文档或公开 API 参考核实实时负载。请勿在不说明的情况下，从 /v2/campaign 回退到旧版 /campaign 行为。
• 仅在可信服务器上使用私有 API 密钥。从 VAPI_API_KEY 读取密钥；切勿打印密钥、在聊天中索要密钥，或将密钥放入客户端代码、示例、日志或已提交的文件中。
• 请将电话号码、姓名、联系人变量、通话记录、转录文本和录音视为敏感信息。除非用户需要具体记录，否则只报告数量和已脱敏的样本。
• 切勿臆造资源 ID、收件人、同意、计划时间、时区、Campaign 状态、计数器或通话结果。请通过精确 ID 或明确无歧义的 API 结果解析已保存的资源。
• 启动 Campaign 可能会拨打真实且会产生费用的电话。在实时创建或复制之前，请确认确切的目标、外呼号码、受众数量、时间安排、并发量和 webhook 行为。除非用户当前的指令已明确授权启动该确切任务，否则请先征得确认。
• 请勿作出法律判断。告知用户应核实适用于每位收件人和每个目的地的同意、来电者身份识别、录音、退订、静默时段和电话营销要求。相关情况下，请参阅 Vapi 的 TCPA 同意指南。
• POST /v2/campaign 超时或响应不明确，并不能证明操作失败。重试前，请搜索目标 Campaign，避免向受众重复拨打电话。

流程

1. 选择 API 和执行模式。

   • 对于单次通话，或不需要 Campaign 级生命周期管理、报告、取消、复制或 webhooks 的简单一次性批次，请使用 POST /call 和 create-call skill。
   • 如果用户要求起草、说明、审核或准备，请返回计划、CSV、负载或实现方案，不要调用 Vapi。
   • 只有在用户要求创建、复制、取消或归档，且 VAPI_API_KEY 可用时，才执行实时 API 操作。

2. 确定呼叫方和外呼号码。

   • 只选择一个已保存的 assistantId 或 squadId。创建新 Campaign 时，请勿使用已弃用的 Workflows。
   • 确定一个支持外呼的 phoneNumberId。Vapi Free Numbers 无法启动 Campaign。当前 /v2/campaign API 不支持通过旧版 dialPlan 在多个外呼号码之间路由。
   • 启动前，请检查 assistant 或 squad。确保其提示词、工具、变量、通话结束行为和已发布配置符合此类外呼场景。
   • 为所有可能处理 Campaign 通话的 assistant 配置一种语音信箱处理方式：由 assistant 驱动的语音信箱工具，或内置语音信箱检测，二者不可同时使用。扩大量级前，请测试具有代表性的语音信箱和通话筛选场景。

3. 准备并验证联系人。

   • 允许 1 到 10,000 个联系人。优先使用 E.164 格式的号码，例如 +14155550100。在 API 请求中，如需有意指定非 E.164 格式的 SIP 中继目标号码，必须在该客户上设置 numberE164CheckEnabled: false；但号码仍只能包含可选的前导 +，后跟字母或数字。Dashboard CSV 导入器无法设置此客户级标志，因此通过该方式导入时请使用 E.164 格式的号码。
   • 对于 Dashboard CSV，必须包含小写的 number；小写的 name 为可选项。其他所有非空列都会成为区分大小写的动态变量。建议使用小写的 snake_case 表头。
   • CSV 文件不得超过文档说明的 Dashboard 5 MB 限制。拒绝空白或格式错误的行，并将重复项列出以供审核；不得静默丢弃或合并接收者。
   • 对于 API 请求，将每个联系人的值放入助手活动的 assistantOverrides.variableValues，或团队活动的 squadOverrides.variableValues。不要将任意来源列复制到无关的配置字段中。
   • 每个联系人的变量数据序列化后总长度须小于 100,000 个字符。确认呼叫方引用的每个变量均已提供，或具有预期的回退行为。

4. 设置时间安排和并发数。

   • 对于应在有可用容量时立即发起的新活动，请省略 schedulePlan。
   • 对于计划时间窗口，请将 schedulePlan.earliestAt 和可选的 latestAt 设为 ISO 8601 日期时间。当用户提供本地时间时，请确定 IANA 时区，将时间转换为 ISO 格式，并同时显示本地时间和 ISO 值。
   • 确认 latestAt 晚于 earliestAt。Dashboard 最多支持提前七天安排，并以 15 分钟为间隔；在 Dashboard 之外实现时，请重新检查当前 API 限制。
   • 将 maxConcurrency 设为不超过组织的可用并发数。它仅限制此活动，不会预留名额，也不会增加组织共享的通话容量。
   • 为目标受众留出充足时间。等待可用容量的联系人最多可重试一小时，但在达到 latestAt 时会提前停止重试。

5. 仅在需要时配置活动 Webhook。

   • 使用 predialPlan 或 serverMessages 前，先设置 server。优先使用已保存的凭据，而非内联密钥，并设置合理的超时和退避方案。
   • 使用 predialPlan: { "enabled": true } 在拨打每个联系人之前立即执行阻塞检查。端点必须返回包含布尔值 eligible 的 JSON；若值为 false，则跳过该联系人；若发生超时、返回非 2xx 状态码或 JSON 无效，则会产生 contact.predial-failed。
   • 使用 serverMessages 接收选定的异步活动和联系人生命周期事件。接收端应确保幂等，不要依赖事件顺序。
   • 活动事件不包含完整的通话记录。若集成还需要文字记录、录音或分析结果，请在相关助手上配置 end-of-call-report，并通过 callId 关联记录。

6. 构建并审核请求。

   • 对于全新活动，请包含 name、assistantId 或 squadId（且只能二选一）、phoneNumberId、非空的 customers 数组以及 maxConcurrency。
   • 对于副本，请包含 name 和 duplicateFromCampaignId，然后仅发送有意替换的字段。省略 customers 可继承源受众；若提供 customers 数组，则会替换源受众。
   • 仅在确有需要时添加活动级 assistantOverrides 或 squadOverrides、schedulePlan、server、serverMessages 和 predialPlan。
   • 请阅读活动 API 参考，了解经过验证的 REST 请求结构、副本语义、分页和生命周期请求。
   • 正式启动前，请展示解析后的呼叫方和电话号码、受众人数及脱敏样例、本地时间和 ISO 时间、最大并发数、Webhook 副作用，以及是否会立即开始拨打。常规确认输出中不要公开完整的联系人载荷。

7. 创建后立即验证。

   • 发送一次 POST /v2/campaign。将返回的 campaign ID 视为持久标识符。
   • 在确认创建成功前，使用 GET /v2/campaign/{id}?includeCounters=true 重新获取该 campaign。报告实际状态和计划安排；创建成功并不能证明已联系到任何联系人。
   • 如果创建请求返回不明确的超时或 5xx 错误，使用 GET /v2/campaign 配合范围较窄的受支持筛选条件和创建时间信息查找该 campaign。不要自动重复发送 POST 请求。

8. 根据联系人证据检查并诊断。

   • 获取带有 includeCounters=true 的 campaign。使用 contactCounters 查看待处理、已派发、已完成、失败、已跳过和拨号前失败的总数；使用 callMetrics.dialed 和 callMetrics.connected 分析接听情况。
   • 获取 GET /v2/campaign/{id}/contacts，并在需要时进行分页。每位受众成员的状态才是事实依据。
   • 被跳过或拨号前失败的联系人可能没有 call ID，因为并未拨打电话。如果存在实际的 callId，则获取对应通话，并检查结束原因、转录、录音、分析和日志，然后再提出根本原因。
   • 区分 campaign 派发问题、拨号前资格检查失败、电信连接失败、语音信箱结果和助手行为。仅凭计数器无法确定原因。

9. 复制 campaign 以重新运行或替换兼容配置。

   • Campaign 创建后不可修改。不要更改呼叫方、联系人、计划安排、并发数或 webhook 配置。
   • 使用 duplicateFromCampaignId 和新的 name 创建 campaign。省略的配置和联系人会从源 campaign 复制；提供的字段会覆盖源 campaign，提供的 customers 会替换复制的联系人。源 campaign 也必须使用当前的 /v2/campaign API。
   • 复制操作无法取消继承的所有字段。尤其是在 assistantId 和 squadId 之间切换时，会继承旧的互斥呼叫方，导致请求无效。更改呼叫方类型或需要移除而非替换继承选项时，请创建全新的 campaign。
   • 启动前检查所有继承字段。若要让副本几乎立即运行，而不是继承已过期的计划安排，请在发送请求前立即生成 schedulePlan.earliestAt，并留出足够的未来时间，确保它在传输和服务器验证期间仍然有效，例如设置为当前 UTC 时间加 60 秒。说明由此产生的延迟。
   • 将副本视为另一次正式启动；它与全新 campaign 一样，必须遵守相同的授权和防止重复拨号措施。

10. 谨慎取消或归档。

• 若要停止已计划或正在运行的 campaign，仅发送包含 { "status": "cancelled" } 的 PATCH /v2/campaign/{id}。待处理工作会停止；已经开始的通话可能会继续完成。取消对该 campaign 来说是最终操作。
• 重新获取并验证终止状态和 endedReason。不要将取消描述为撤销已经拨出的电话。
• DELETE /v2/campaign/{id} 会归档记录，而非永久删除 campaign 记录。如果 campaign 处于活动状态，会先将其取消。只有当用户另外要求将其从活动 campaign 视图中移除时，才进行归档。

故障处理

• 400：报告被拒绝的字段，并与当前 /v2/campaign 架构进行比较。修正一个明确无误的请求格式问题后，最多安全重试一次。
• 401 或 403：如果是身份验证、权限范围、使用权限、订阅被冻结或权限问题，请停止操作。
• 404：报告确切缺失的 campaign、助手、squad 或电话号码 ID。
• 409：重新获取 campaign；如果是不可变更或终止生命周期冲突，则需要创建副本或不再采取操作，而非重复发送 patch。
• 429 或 5xx：报告服务状况。在排除重复创建可能性之前，绝不要重试 campaign 创建。
• 部分完成：保留 campaign，并报告实际联系人结果。不要自动删除、重新拨号或替换剩余受众。

输出约定

仅返回请求所需的内容：

• 模式：计划、负载、启动、检查、复制、取消、归档或诊断
• 已解析的呼叫方、外呼号码、联系人数量和脱敏样例
• 本地和 ISO 格式的计划时间、最大并发数及共享容量注意事项
• 仍需用户核实的同意情况和呼叫时段假设
• Webhook 和拨号前行为，包括仍会产生的实时副作用
• 按需提供可直接保存的 CSV、JSON 或代码
• 实时操作后的 Campaign ID、验证状态、计数器、联系人结果和呼叫 ID
• 未解决的失败、证据和最小安全后续操作

公开来源

• Campaigns overview
• Campaigns quickstart
• Campaign contact data
• Campaign scheduling and lifecycle
• Campaign voicemail and call screening
• Campaign webhooks
• Campaign API reference