AI语音外呼供应商接入需求

本文定义消息网关一期新增的首家 AI 语音外呼供应商接入要求。供应商资料来源为本目录下《AI外呼系统 - API 接口文档.pdf》。一期只接入还款提醒外呼，不把供应商能力扩展成完整催收系统或营销编排平台。测试环境已提供 APP KEY 和 APP Secret，本文只记录可识别账号信息，密钥明文必须进入安全配置或配置中心，不写入 Markdown。

1. 接入目标

消息网关封装 AI 外呼供应商接口，对 FCS 提供统一语音提醒能力。
FCS 只提交还款提醒业务变量，不直接调用供应商，不保存供应商密钥。
消息网关负责把还款提醒请求转换为供应商名单导入请求。
消息网关接收供应商实时拨打结果回调，标准化外呼结果。
外呼未接通、忙线、拒接、不可达、线路异常或超时未回执时，一期在消息网关内标记为可降级候选；自动短信或 WhatsApp 降级作为二期跨类型路由能力启用。

2. 一期范围

2.1 包含范围

能力	一期要求
鉴权签名	支持 `appKey`、`timestamp`、`sign` 请求头
名单导入	调用 `/ai/details/import` 提交还款提醒外呼名单
批次幂等	按 `batch_id` 和网关发送明细控制重复导入
外呼取消	支持调用 `/ai/details/cancel` 取消未拨打或未完成外呼
取消查询接口	按供应商要求预留用户侧取消查询接口，返回是否取消
实时回调	接收供应商拨打结果回调，按 `call_id` 幂等
结果映射	将供应商 `call_result` 映射为消息网关标准状态
降级候选	对未接通、忙线、拒接、不可达、线路异常、超时回调标记可降级候选
结果查询	在消息网关消息查询中展示外呼结果、意向、摘要和录音 URL
监控告警	输出导入成功率、回调延迟、接通率、线路异常等指标

2.2 不包含范围

不建设催收案件管理、承诺还款管理、人工坐席分案。
不自动根据 AI 意向标签调整客户账务、逾期状态、减免或催收策略。
不接入多家语音供应商，不做语音供应商自动切换。
不管理供应商后台的话术配置、轮次排期和 AI 模型训练。
不下载和长期保存完整录音文件；一期只保存 record_url 和必要摘要。
不把供应商多轮任务能力抽象成通用营销旅程编排。

3. 供应商接口概览

项目	说明
供应商名称	AI 外呼系统
测试环境 Endpoint	`https://ai-testing.xloans.co`
测试环境 APP KEY	`ak_93j7jdbn23gsk`
测试环境 APP Secret	已提供，必须写入安全配置或配置中心，不在文档和代码中明文保存
一期还款提醒策略 ID	`50`
生产环境 Endpoint	由运营 / 供应商提供，配置化管理
协议	HTTP
请求方法	统一 POST
请求格式	`application/json;charset=utf-8`
响应格式	`application/json;charset=utf-8`
编码	UTF-8

4. 鉴权与签名

4.1 请求头

调用供应商接口时，消息网关需在 HTTP Header 中传入：

Header	必填	说明
`appKey`	是	供应商提供的客户服务 key
`timestamp`	是	当前时间戳，毫秒
`sign`	是	HMAC-SHA1 签名后 Base64 编码

4.2 签名算法

签名规则：

sign = Base64(HmacSHA1(appKey + timestamp, appSecret))

要求：

appSecret 由供应商提供，只允许服务端安全配置。
timestamp 使用毫秒时间戳。
调用前需校验 appKey、appSecret、timestamp 不为空。
签名失败、HTTP 401 / 403 或供应商鉴权错误需记录为 provider_auth_failed 并告警。

5. 名单导入接口

5.1 接口

POST {api-endpoint}/ai/details/import

5.2 供应商请求字段

字段	必填	说明
`batch_id`	是	批次 ID。重复批次不会重复导入，供应商会返回失败
`strategy_id`	是	供应商策略 ID，对应一组外呼任务排期
`details`	是	外呼案件列表

details 字段：

字段	必填	说明
`ref_id`	是	调用方业务编号，最多 50 字符，供应商回调原样返回
`phone_number`	是	用户电话号码。供应商要求不带国家码 `234`，前面不带 `0`
`name`	是	客户名称
`gender`	否	`male` / `female`，允许为空
`brand`	是	品牌名称，例如 `EasyBuy`
`extra`	是	业务扩展字段

还款提醒 extra 字段：

字段	必填	说明
`outstanding_amount`	是	本次提醒金额
`due_date`	是	到期日，格式 `yyyy-MM-dd`
`loan_amount`	否	贷款本金
`loan_date`	否	贷款日期，格式 `yyyy-MM-dd`
`product_name`	否	产品名称
`term`	否	第几期
`debtor_name`	否	债务人姓名

5.3 网关字段映射

消息网关字段	供应商字段	说明
`attempt.provider_batch_id`	`batch_id`	建议格式：`{scene}-{yyyyMMdd}-{sequence}` 或按任务批次生成
`scene_route.provider_strategy_id`	`strategy_id`	由场景路由配置提供
`attempt_id` 或稳定派生 ID	`ref_id`	必须能反查消息网关发送明细，长度不超过 50
`receiver_phone`	`phone_number`	将 `+2348012345678` 转为 `8012345678`，去掉国家码和前导 0
`variables.customer_name`	`name`	客户姓名
`variables.gender`	`gender`	可为空
`variables.brand`	`brand`	品牌名，由场景配置或上游传入
`variables.due_amount`	`extra.outstanding_amount`	本次应提醒金额
`variables.due_date`	`extra.due_date`	到期日
`variables.loan_amount`	`extra.loan_amount`	可选
`variables.loan_date`	`extra.loan_date`	可选
`variables.product_name`	`extra.product_name`	可选
`variables.term`	`extra.term`	可选

5.4 响应处理

供应商通用响应：

{
  "code": 0,
  "message": "success"
}

处理要求：

code=0 视为名单导入成功，通道发送明细状态更新为 accepted。
code=1001 表示重复批次，消息网关需按自身幂等记录判断是否已有成功导入；已有成功则不重复发送，没有成功记录则标记异常待人工排查。
code=400 视为参数错误，记录 provider_param_error。
code=500 视为供应商请求失败，记录 provider_failed；一期标记可降级候选，二期按场景触发跨类型降级。
HTTP 超时或网络异常记录为 provider_timeout。

6. 外呼取消接口

6.1 推送取消

POST {api-endpoint}/ai/details/cancel

请求字段：

字段	必填	说明
`strategy_id`	是	供应商策略编号
`ref_id_list`	是	需要取消的外呼引用编号列表

使用场景：

客户已还款，FCS 通知消息网关取消未完成外呼。
还款提醒任务被人工取消。
发现手机号或客户信息错误，需停止继续拨打。

要求：

只允许取消状态为 accepted、sending、not_connected 且供应商仍可能继续拨打的任务。
已收到最终接通、空号或最终失败结果的任务，不再调用取消。
取消请求和响应需落库，便于追踪。

6.2 供应商查询取消

供应商文档要求用户提供“是否取消外呼”的查询接口。消息网关需预留：

POST /message-gateway/api/v1/provider-callback/ai-voice/cancel-query

供应商请求字段：

字段	必填	说明
`strategy_id`	是	策略编号
`ref_id`	是	引用编号
`phone_number`	是	手机号

响应：

{
  "code": 0,
  "message": "success",
  "data": {
    "is_cancel": 1
  }
}

规则：

消息网关根据 ref_id 查询通道发送明细。
如果消息已取消、客户已还款、借据已结清或业务侧标记不再触达，返回 is_cancel=1。
其他情况返回 is_cancel=0。
接口必须支持高并发和幂等，不在查询时做复杂业务计算。

7. 实时拨打结果回调

7.1 回调入口

POST /message-gateway/api/v1/provider-callback/ai-voice/call-result

供应商在拨打完成或任务阶段完成后回调该接口。消息网关接收成功后返回 HTTP 200 和业务 code=0。

7.2 回调字段

字段	必填	说明
`call_id`	是	外呼编号，64 字符内，用于回调幂等
`ref_id`	是	引用编号，用于反查网关发送明细
`phone_number`	是	电话号码
`name`	是	客户名称
`gender`	是	性别
`extra`	是	业务扩展字段
`batch_id`	是	导入名单批次号
`strategy_id`	是	策略编号
`task_id`	是	任务编号
`task_name`	是	任务名称
`call_result`	是	外呼拨打结果
`call_begin_time`	是	拨打开始时间，0 时区，格式 `yy-MM-dd HH:mm:ss`
`answer_time`	否	接通时间
`hangup_time`	否	挂断时间
`ring_time`	是	振铃时长，供应商示例为毫秒；落库需统一单位
`talk_duration`	是	通话时长，秒
`intention`	是	意向标签
`intention_description`	是	意向描述
`summary`	否	AI 通话总结
`record_url`	否	通话录音 URL
`round`	是	第几轮拨打
`is_end_round`	是	是否完成拨打，1 是，0 否
`transfer_reasons_when_end_round`	否	转人工原因列表

7.3 回调幂等

唯一键：provider_code + call_id。
同一个 call_id 重复回调时，只允许更新同一条回调记录和同一条通道发送明细。
重复回调不得重复标记可降级候选；二期启用跨类型降级后，不得重复触发短信或 WhatsApp。
回调无法通过 ref_id 匹配发送明细时，落异常表并告警，不直接丢弃。

供应商重试规则：

供应商仅在 HTTP 状态非 200 时重试。
最多重试 5 次。
间隔为 3s、6s、12s、24s、48s。

8. 结果映射

8.1 外呼结果

供应商 `call_result`	说明	网关标准状态	一期处理
`ANSWERED`	已接听	`connected`	不标记降级候选
`NO_ANSWER`	手机响铃但没人接	`not_connected`	标记可降级候选
`NO_USER_RESPONSE`	不可达，手机离线、信号差、SIP 无响应	`unreachable`	标记可降级候选
`USER_BUSY`	用户忙	`not_connected`	标记可降级候选
`UNALLOCATED_NUMBER`	空号	`unreachable`	不标记降级候选
`CALL_REJECTED`	用户拒接	`rejected_by_user`	标记可降级候选
`NETWORK_FAILED`	线路异常	`line_failed`	标记可降级候选

8.2 意向标签

标签	供应商说明	一期处理
A	表明已还款用户	记录，不自动改账
B	承诺今日还款客户	记录，不自动生成承诺还款
C	未表明明确同意或拒绝	记录
D	拒绝还款客户	记录
E	未接通，含占线、未接、拒接、关机、无法接通	可作为降级依据
F	未接通，含欠费、线路故障、呼叫失败、改号	可作为降级依据；改号需人工核实
G	承诺将来还款客户	记录
H	语音信箱	记录，可按未接通处理
I	需要人工帮助	记录，后续可转人工
J	抱怨投诉	记录，后续可转客服 / 投诉流程

一期不根据意向标签自动修改账务、催收队列或客户状态。

8.3 转人工原因

供应商可能返回：

原因	说明
`third_party`	第三方接听，非目标客户
`no_response`	无应答 / 静默
`voicemail`	语音信箱
`identity_not_verified`	身份未确认，客户质疑来电身份
`poor_audio`	音频质量差
`customer_request`	客户主动要求转人工
`angry_customer`	客户愤怒 / 投诉
`complex_issue`	复杂问题 AI 无法处理

一期只记录和查询，是否生成工单或人工跟进任务由后续催收 / 客服需求定义。

9. 数据落库要求

9.1 通道配置

字段	说明
`provider_code`	固定为 `ai_voice_provider` 或研发确认后的供应商编码
`api_endpoint`	供应商环境地址
`app_key`	加密存储
`app_secret`	加密存储
`enabled`	是否启用
`timeout_seconds`	请求超时时间

9.2 场景策略配置

字段	说明
`scene`	例如 `repayment_voice_reminder`
`provider_code`	AI 外呼供应商编码
`strategy_id`	供应商策略 ID；一期测试环境还款提醒使用 `50`
`brand`	供应商话术中使用的品牌
`callback_ttl_minutes`	超过该时间未收到结果，视为超时
`fallback_channel`	sms / whatsapp / none
`enabled`	是否启用

9.3 外呼结果扩展字段

字段	说明
`call_id`	供应商外呼编号
`batch_id`	供应商批次号
`strategy_id`	策略编号
`task_id`	任务编号
`task_name`	任务名称
`call_result`	原始外呼结果
`standard_status`	网关标准状态
`call_begin_time`	拨打开始时间
`answer_time`	接通时间
`hangup_time`	挂断时间
`ring_time_ms`	振铃时长，统一毫秒
`talk_duration_seconds`	通话时长，秒
`intention`	意向标签
`intention_description`	意向描述
`summary`	通话总结
`record_url`	录音 URL
`round`	第几轮
`is_end_round`	是否完成拨打
`transfer_reasons`	转人工原因

10. 业务流程

10.1 发起还款语音提醒

sequenceDiagram
    participant FCS as FCS
    participant MSG as 消息网关
    participant AI as AI外呼供应商

    FCS->>MSG: sendMessage(scene=repayment_voice_reminder, bizId, phone, variables)
    MSG->>MSG: 幂等和频控校验
    MSG->>MSG: 查询 scene 对应 strategy_id=50
    MSG->>AI: /ai/details/import
    AI-->>MSG: code=0
    MSG-->>FCS: messageId + accepted

10.2 外呼结果回调与降级

sequenceDiagram
    participant AI as AI外呼供应商
    participant MSG as 消息网关
    participant SMS as 短信通道
    participant WA as WhatsApp通道
    participant FCS as FCS

    AI->>MSG: call-result(call_id, ref_id, call_result)
    MSG->>MSG: 按 call_id 幂等
    MSG->>MSG: 映射标准状态
    alt 已接听
        MSG->>MSG: 标记 final_success
    else 未接通或线路异常
        MSG->>MSG: 一期标记 fallback_candidate
    end
    FCS->>MSG: 查询 messageId / bizId 状态

11. 异常与补偿

异常	处理
供应商鉴权失败	标记 `provider_auth_failed`，触发告警，不重试业务请求
名单导入参数错误	标记 `provider_param_error`，不降级，待修复数据
名单导入超时	标记 `provider_timeout`，可按配置重试一次；一期只标记降级候选，二期触发跨类型降级
重复批次	根据网关发送明细判断是否已有成功导入，避免重复外呼
回调无法匹配 `ref_id`	落异常表并告警
回调重复	按 `call_id` 幂等处理
超过 TTL 未回调	标记 `callback_timeout` 和 `fallback_candidate=true`；自动短信或 WhatsApp 降级二期启用
空号	标记 `unreachable`，不对同号码继续降级触达
客户已还款	调用取消接口或在取消查询接口返回 `is_cancel=1`

12. 监控指标

指标	说明
`ai_voice_import_total`	名单导入请求数
`ai_voice_import_success_rate`	名单导入成功率
`ai_voice_duplicate_batch_total`	重复批次数
`ai_voice_callback_total`	回调数量
`ai_voice_callback_delay_seconds`	从导入到收到结果的延迟
`ai_voice_connected_rate`	接通率
`ai_voice_no_answer_total`	未接、忙线、拒接、不可达数量
`ai_voice_network_failed_total`	线路异常数量
`ai_voice_callback_timeout_total`	超过 TTL 未回调数量
`ai_voice_fallback_candidate_total`	外呼失败后标记可降级候选的数量

告警建议：

名单导入连续失败或成功率低于阈值，P1。
回调超时数量持续增长，P1。
NETWORK_FAILED 明显升高，P1。
鉴权失败，P1。

13. 联调用例

用例	预期
正常导入 1 个还款提醒客户	供应商返回 `code=0`，网关状态为 `accepted`
重复提交同一业务请求	网关返回原 `messageId`，不重复导入
供应商返回重复批次	网关能识别已有批次并给出明确状态
回调 `ANSWERED`	网关状态为 `connected` / `final_success`，不触发降级
回调 `NO_ANSWER`	网关状态为 `not_connected`，标记可降级候选
回调 `USER_BUSY`	网关状态为 `not_connected`，标记可降级候选
回调 `CALL_REJECTED`	网关状态为 `rejected_by_user`，标记可降级候选
回调 `NO_USER_RESPONSE`	网关状态为 `unreachable`，标记可降级候选
回调 `UNALLOCATED_NUMBER`	网关状态为 `unreachable`，不触发同号码降级
回调 `NETWORK_FAILED`	网关状态为 `line_failed`，标记可降级候选
重复回调同一 `call_id`	不重复标记候选状态；二期不重复触发降级
客户已还款后取消外呼	网关调用取消接口或取消查询返回 `is_cancel=1`
超过 TTL 未收到回调	标记 `callback_timeout` 和 `fallback_candidate=true`

14. 验收标准

AI 外呼供应商测试环境 Endpoint、appKey、appSecret 可配置，密钥不明文暴露。
签名算法按 Base64(HmacSHA1(appKey + timestamp, appSecret)) 生成，供应商鉴权通过。
消息网关能将 FCS 还款提醒请求转换为 /ai/details/import 请求。
手机号能从 +234 规范格式转换为供应商要求的不带国家码、不带前导 0 格式。
strategy_id 由场景配置提供，不由 FCS 临时传入；一期测试环境还款提醒策略 ID 为 50。
ref_id 能反查消息网关通道发送明细。
名单导入成功、失败、重复批次、超时均有标准状态和失败码。
取消外呼接口可按 strategy_id + ref_id_list 调用并记录结果。
供应商取消查询接口可返回 is_cancel=1/0。
实时回调可按 call_id 幂等处理。
ANSWERED、NO_ANSWER、USER_BUSY、CALL_REJECTED、NO_USER_RESPONSE、UNALLOCATED_NUMBER、NETWORK_FAILED 均能映射到消息网关标准状态。
未接通、忙线、拒接、不可达、线路异常或超时未回调时，能按配置标记可降级候选；自动短信或 WhatsApp 降级二期启用。
空号或手机号非法不触发同号码降级触达。
回调中的意向标签、通话总结、录音 URL 能在消息查询中追踪。
基础监控指标可按供应商、场景、结果拆分。
一期不自动根据 AI 意向标签修改账务、催收案件或客户状态。

袋鼠金融蓝图

探索