Agent 拨号(立即/定时外呼)
不通过外呼任务编排,直接为单个客户下单一次 AI 外呼。适用于 CRM 表单触发回访、紧急通知、客户咨询自动响应等场景。接口异步:响应立即返回 call_id + scheduled_at,实际拨号由后端调度器在 scheduled_at 之后 5 秒内发起;号码并发满时保持 pending 等下一轮。后续通过 GET /calls/scheduled/:call_id 或 Webhook 跟踪状态。
/api/open/calls/dial立即发起单通 AI 外呼。被叫号码必须符合格式(国内手机 / 国内座机 / +国际号)。
agent_uuidstring必填calleestring必填number_uuidstring可选extraobject可选{{key}} / {{customer.name}} 等占位符引用,详见 Prompt 变量章节;Webhook 投递通话事件时也会原样回推此字段,便于对回业务系统的 biz_idscheduled_atstring可选extra 中的保留字段(可选)
extra 中支持两个保留字段,用于按单通临时复写 Agent 配置:
greeting_overridestring≤ 500 字节prompt_overridestring≤ 20000 字节- 长度按 UTF-8 字节计算:1 个中文字符约 3 字节,500 字节约可容纳 166 个中文字符,20000 字节约 6666 个中文字符。
- prompt_override 中即使包含工具占位符(如 ${tool:hangup|xxx}$),也不会启用 Agent 未授权的工具,工具能力始终以 Agent 配置为准。
- Prompt 变量(
{{name}}等)和知识库检索照常生效;两个保留字段本身也可作为 Prompt 变量(如{{greeting_override}})被引用。 - 每通使用不同的 prompt_override 会绕过 LLM Prompt Caching,首字延迟略增;稳定文案下复用可命中缓存。
- 参数校验失败(非字符串 / 超过上限)返回 code 2001。
跟踪通话状态
接口异步:响应返回 call_id 时通话尚未发起,由调度器在 scheduled_at 之后 5 秒内进入实际拨号,再创建 CallRecord。跟踪通话进展的方式:
GET /api/open/calls/scheduled/:call_id查询排期详情(status / caller / dispatched_at / call 摘要)GET /api/open/call-records/:call_id调度器实际发起后,查询完整通话详情- 订阅 Webhook 接收
call.ended事件,payload 包含 extra 字段可对回业务 biz_id
可能的错误响应:被叫号码命中企业黑名单时,接口返回 HTTP 400,响应体为 {“error”:“phone_blocked”,“message”:“号码在黑名单”}(不包含通用 code 字段),不落表;scheduled_at 不合法返回 scheduled_at_invalid,超过 30 天返回 scheduled_at_too_far;其它错误码见 错误码 章节。
定时排期列表
Section titled “定时排期列表”/api/open/calls/scheduled列出企业的定时外呼排期(含立即拨已入表未拨的),按 scheduled_at 倒序,支持分页与筛选。
pageintpage_sizeintstatusstringphonestringagent_uuidstringscheduled_from / scheduled_tostring/api/open/calls/scheduled/:call_id查询单个排期详情,返回 item 完整字段(含 extra) + 关联 CallRecord 摘要(仅 dispatched 时非空)。call_id 不存在或跨企业返回 3001。
/api/open/calls/scheduled/:call_id取消未拨的排期。仅 status=pending 可取消;其它状态返回 outbound_agent_not_cancellable。跨企业或不存在返回 3001。
/api/open/calls/:call_id/hangup主动挂断进行中的 AI 通话,对所有来源生效(立即外呼 / 外呼任务 / 入站)。
call_idstring必填