跳转到内容

Agent 拨号(立即/定时外呼)

不通过外呼任务编排,直接为单个客户下单一次 AI 外呼。适用于 CRM 表单触发回访、紧急通知、客户咨询自动响应等场景。接口异步:响应立即返回 call_id + scheduled_at,实际拨号由后端调度器在 scheduled_at 之后 5 秒内发起;号码并发满时保持 pending 等下一轮。后续通过 GET /calls/scheduled/:call_id 或 Webhook 跟踪状态。

POST/api/open/calls/dial

立即发起单通 AI 外呼。被叫号码必须符合格式(国内手机 / 国内座机 / +国际号)。

请求体
agent_uuidstring必填
AI Agent UUID
calleestring必填
被叫号码;支持国内手机(1[3-9] 开头 11 位) / 国内座机(0+区号+号码,可带连字符) / +国际号。同时接受明文手机号或加密 token(22 / 44 字符的 base64url 字符串),加密算法见 Phone 加密 章节。
number_uuidstring可选
主叫号码 UUID;不传则后端从企业可用号码池随机选
extraobject可选
自由 JSON object,作为 Prompt 变量上下文;通话时可在 Agent Prompt 里用 {{key}} / {{customer.name}} 等占位符引用,详见 Prompt 变量章节;Webhook 投递通话事件时也会原样回推此字段,便于对回业务系统的 biz_id
scheduled_atstring可选
RFC3339 时间字符串(如 2026-07-24T15:00:00+08:00),表示希望发起呼叫的时间。空串或不传视为立即拨。必须在当前时间之后、30 天之内;不满足返回 scheduled_at_invalid / scheduled_at_too_far。

extra 中的保留字段(可选)

extra 中支持两个保留字段,用于按单通临时复写 Agent 配置:

保留字段
greeting_overridestring≤ 500 字节
替换本通通话的开场白文本。空串或不传视为不复写,沿用 Agent 配置。
prompt_overridestring≤ 20000 字节
替换本通通话的系统 Prompt 主体文本。空串或不传视为不复写,沿用 Agent 配置。
  • 长度按 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;其它错误码见 错误码 章节。

GET/api/open/calls/scheduled

列出企业的定时外呼排期(含立即拨已入表未拨的),按 scheduled_at 倒序,支持分页与筛选。

Query 参数
pageint
页码,默认 1
page_sizeint
每页条数,默认 10
statusstring
按状态过滤:pending / dispatching / dispatched / failed / cancelled
phonestring
被叫号码模糊匹配
agent_uuidstring
按 AI Agent UUID 过滤
scheduled_from / scheduled_tostring
呼叫时间范围(RFC3339)
GET/api/open/calls/scheduled/:call_id

查询单个排期详情,返回 item 完整字段(含 extra) + 关联 CallRecord 摘要(仅 dispatched 时非空)。call_id 不存在或跨企业返回 3001。

DELETE/api/open/calls/scheduled/:call_id

取消未拨的排期。仅 status=pending 可取消;其它状态返回 outbound_agent_not_cancellable。跨企业或不存在返回 3001。

POST/api/open/calls/:call_id/hangup

主动挂断进行中的 AI 通话,对所有来源生效(立即外呼 / 外呼任务 / 入站)。

路径参数
call_idstring必填
通话 ID,即 dial 接口或通话记录返回的 call_id

鄂ICP备2022005956号-2