语音通知接口 API 技术规范

概述

本文档定义了语音通知业务向第三方平台开放的标准 HTTP API，用于实现自动外呼、播放语音通知、接收呼叫事件及话单的完整闭环。适用于产品设计、研发联调和测试验证阶段。

适用场景

验证码 / 取件码语音播报
系统告警电话通知
会议提醒、预约确认
批量客户回访

通信模型

语音通知业务的交互涉及三方：第三方业务平台、语音能力平台和终端用户。整体流程分为两个通道：

API 请求通道：第三方平台 → 能力平台（HTTP POST + JSON）
事件回调通道：能力平台 → 第三方平台（HTTP POST + JSON，异步推送）

语音通知系统架构

通用规范

1. 名词解释

名词	说明
`vccId`	企业标识 ID，由平台在业务开通时分配
`chargeExt`	计费分机号码，与企业账户一一对应
`displayNumber`	外呼显示号码，终端用户手机来电显示
`callId`	呼叫唯一标识，贯穿一次外呼的全部生命周期
`sid`	服务端会话标识，用于关联请求与回调
`TTS`	Text-to-Speech，文本转语音合成

2. API 请求规范

第三方平台发起的所有请求均遵循以下约定：

请求方法：POST
内容格式：application/json
字符编码：UTF-8
请求头：必须携带 Content-Type: application/json

3. 事件推送规范

能力平台主动推送至第三方平台的事件消息遵循相同格式约定。调试阶段建议使用 Hoppscotch 搭建本地 Mock Server 验证回调逻辑。。第三方平台收到推送后须回复 HTTP 200，否则能力平台将按策略重试。

4. 鉴权机制

每次 API 调用须在 URL 中携带鉴权参数 token 和 timestamp。token 基于 vccId、password 和时间戳通过 MD5 计算得到：

1	token = upper(md5(vccId + password + timestamp))

其中 + 表示字符串拼接（不参与哈希运算），upper() 表示将 MD5 十六进制字符串转为大写。

参数	说明
`vccId`	企业标识 ID
`password`	密钥，由平台分配
`timestamp`	请求时间戳，格式 `YYYYMMDDHHmmss`，与服务端系统时间偏差不得超过 1 小时

示例：vccId=100100，password=666000，timestamp=20200101101010，则 token = UPPER(MD5(10010066600020200101101010)) = 075078E01DA4DE8A6D4F6EA597271C50。

API 接口

一、语音通知外呼

接口描述

向目标用户发起外呼，接通后播放指定提示音。单次请求最多支持 100 个被叫号码，HTTP 消息体总大小不超过 2 MB。

请求 URL

1	POST https://{host}:{port}/cincc/apicall/{vccId}/voicenotify?token={token}&timestamp={timestamp}

请求参数

参数	类型	必填	说明
`clientId`	String	N	客户端请求标识，用于关联回调，允许空字符串
`vccId`	String	Y	企业标识 ID
`method`	String	Y	请求方法，固定值 `call`
`chargeExt`	String	Y	计费分机号码，由平台提供
`number`	String	Y	外呼目的号码，多个号码以英文逗号分隔，最多 100 个
`displayNumber`	String	N	外呼显示号码，为空时使用平台默认配置
`prompt`	String	Y	通知语音描述（详见下方 Prompt 格式说明）
`argv`	Object	C	语音变量组，键为号码-变量值映射；条件必填：prompt 含变量时
`repeat`	String	N	播放次数，默认 `1`
`callData`	String	N	随路数据，透传至回调消息
`callBackUrl`	String	N	事件推送 URL，优先于企业默认回调地址
`recordType`	String	N	录音标识：`0`=不录音，`1`=接通后录音
`speaker`	String	N	TTS 音色，默认 `siyue`
`volume`	String	N	TTS 音量，范围 0–100，默认 `50`
`speed`	String	N	TTS 语速，范围 -500–500，默认 `0`
`pitch`	String	N	TTS 语调，范围 -500–500，默认 `0`
`collectParam`	Object	N	收号参数（详见收号控制说明）
`collectAction`	Object	N	收号后继操作定义

Prompt 格式说明

prompt 支持三种表达方式：

固定语音文件：直接填写文件名（如 welcome.wav）
纯 TTS 文本：直接填写文字内容
XML 扩展格式（推荐）：混合固定语音与 TTS 动态合成

<msg>
  <file>greeting.wav</file>
  <var>7_张三你好，您的取件码是 123456</var>
  <file>goodbye.wav</file>
</msg>

其中 <var> 标签的格式为 {vartype}_{var}，vartype 支持以下类型：

vartype	含义	示例
`1`	整数	`1_42`
`2`	数字	`2_10086`
`3`	HHMM 格式时间	`3_1430`
`4`	YYYYMMDD 格式日期	`4_20260101`
`5`	YYYYJJF 格式价格	`5_20251200`
`6`	HHMMSS 格式时间	`6_143000`
`7`	TTS 语音合成	`7_您好`

带变量模板示例：

1	prompt: <msg><var>7_$$你好，$$是你的取件码</var></msg>

$$ 为占位符，由 argv 中的变量值按序替换。

收号控制（collectParam）

参数	说明	默认值
`active`	收号开关：`0`=不收号，`1`=收号	`0`
`ini`	按键打断：`0`=不可打断，`1`=可打断	`0`
`fto`	首个按键超时（秒），范围 0–300	`10`
`ito`	键间间隔超时（秒），范围 1–300	`5`
`min`	最小收号长度	`1`
`max`	最大收号长度	`16`
`end`	收号终止符（`0-9`、`*`、`#`）	`#`
`cel`	收号取消键（`0-9`、`*`、`#`）	`*`

收号后继操作（collectAction）

定义收号完成后的动作与提示音。keyN 和 opN 中 N 可取 0–9 或 Null（无按键）：

参数	说明
`errCnt`	允许按键错误次数，超出后结束
`errContinue`	按键错误后重收号提示音
`errEnd`	按键错误结束提示音
`keyN`	按键 N 对应的播放文件
`opN`	按键 N 的动作：`0`=放音后结束，`1`=重播提示音

请求示例

{
  "vccId": "666666",
  "method": "call",
  "chargeExt": "1000",
  "number": "13800138001,13800138002",
  "prompt": "<msg><var>7_$$你好，$$是你的取件码</var></msg>",
  "argv": {
    "13800138001": ["张三", "123456"],
    "13800138002": ["李四", "345678"]
  }
}

响应参数

参数	类型	必填	说明
`clientId`	String	Y	回显请求中的 clientId
`sid`	String	N	服务端会话标识
`vccId`	String	Y	企业标识 ID
`callId`	String	N	呼叫唯一标识
`seq`	String	Y	消息序列号
`method`	String	Y	请求方法，固定 `call`
`chargeExt`	String	Y	计费分机号码
`result`	String	Y	结果码（见下表）

结果码定义：

结果码	含义
`0000`	请求成功
`1000`	无呼叫成员
`1001`	vccId 格式错误
`1002`	chargeExt 格式错误
`1003`	不是企业配置的 displayNumber
`1004`	成员电话号码不能为空
`1005`	呼叫已结束
`1006`	媒体资源异常
`1007`	已达用户最大呼叫并发数
`1008`	已达平台最大呼叫并发数
`1009`	IP 鉴权与密码鉴权至少须有一项
`1010`	IP 鉴权错误
`1011`	密码鉴权错误
`1012`	VCC 不存在或状态异常
`1013`	userId 不匹配
`1100`	release 参数错误
`1101`	分机不存在或状态不正常
`1102`	集团不存在或状态不正常
`1999`	其他未知错误

响应示例

{
  "clientId": "",
  "sid": "S20210316093614941989AC11000C02386591",
  "vccId": "666666",
  "chargeExt": "1000",
  "callId": "C20210316093614AC11000C02386588",
  "seq": "1",
  "method": "call",
  "result": "0000"
}

二、呼叫事件推送

接口描述

呼叫生命周期中的状态变更事件由能力平台主动推送至第三方。事件类型包括：开始外呼、振铃、应答、挂机、呼叫不可达、放音失败等。

推送 URL

由外呼请求中的 callBackUrl 参数指定。未携带时，回退至企业默认回调地址；若企业也未配置默认回调，则不推送。

请求参数

参数	类型	必填	说明
`clientId`	String	Y	客户端请求标识
`sid`	String	Y	服务端会话标识
`vccId`	String	Y	企业标识 ID
`method`	String	Y	请求方法，固定 `event`
`chargeExt`	String	Y	计费分机号码
`callId`	String	Y	呼叫标识
`code`	String	Y	事件码（见下表）
`callResult`	String	N	详细原因值（code=`20` 时）
`reason`	String	N	预留字段
`callData`	String	N	随路数据
`msServer`	String	N	媒体服务器名称
`filePath`	String	N	录音文件路径
`userList`	Object	N	外呼用户信息列表

事件码（code）：

code	含义
`10`	开始呼叫
`11`	振铃
`20`	呼叫不可达（需配合 callResult 判断原因）
`21`	摘机 / 应答
`22`	挂机 / 通话结束
`45`	放音失败结束

callResult 详细原因（code=20 时）：

callResult	含义	callResult	含义
`00`	无原因	`18`	外地手机号前未加 0
`01`	路由失败	`20`	主叫限制
`02`	呼叫遇忙	`21`	被叫限制
`03`	用户不在服务区	`22`	呼转限制
`04`	用户无应答	`23`	被叫通话中
`05`	用户已关机	`24`	用户拒接
`06`	号码是空号	`25`	未识别回铃音
`11`	用户停机	`101`	信令判别路由失败
`12`	号码过期	`102`	信令判别呼叫遇忙
`13`	呼叫转移	`103`	信令判别不在服务区
`104`	信令判别无应答	`108`	线路忙（拥塞信令）
`109`	线路异常	`110`	信令判别空号
`113`	信令判别呼叫转移	`200`	已接通

外呼用户信息（userList.user[]）

参数	类型	必填	说明
`line`	String	Y	线路标识，固定 `0`
`number`	String	Y	外呼号码
`type`	String	Y	类型，固定 `0`
`state`	String	N	状态：`0`=空闲，`1`=通话中，`2`=呼叫中，`3`=振铃中
`translate`	String	Y	翻译号码（实际接通号码），空表示与外呼号码一致
`displayNumber`	String	N	显示号码

请求示例

{
  "clientId": "",
  "sid": "S20210316093614941989AC11000C02386591",
  "vccId": "666666",
  "chargeExt": "1000",
  "callId": "C20210316093614AC11000C02386588",
  "seq": "2",
  "method": "event",
  "code": "20",
  "callResult": "103",
  "reason": "",
  "msServer": "ms3",
  "filePath": "",
  "callData": "",
  "userList": {
    "user": [{
      "line": "0",
      "number": "13800138001",
      "type": "0",
      "state": "0",
      "displayNumber": "",
      "translate": ""
    }]
  }
}

响应

无需返回业务数据，回复 HTTP 200 即可确认接收。

三、话单推送

接口描述

呼叫结束后，能力平台向第三方推送计费级话单数据，包含外呼开始时间、振铃时间、应答时间、结束时间及接通状态。

推送 URL

与外呼请求中的 callBackUrl 一致。

请求参数

参数	类型	必填	说明
`clientId`	String	Y	客户端请求标识
`sid`	String	Y	服务端会话标识
`vccId`	String	Y	企业标识 ID
`method`	String	Y	请求方法，固定 `cdr`
`chargeExt`	String	Y	计费分机号码
`callId`	String	N	呼叫标识
`code`	String	Y	事件码（`20`/`22`/`45`）
`callResult`	String	N	详细原因（code=`20` 时，同上表）
`reason`	String	N	预留
`callData`	String	N	随路数据
`msServer`	String	N	媒体服务器名称
`filePath`	String	N	录音文件路径
`cdrList`	Object	N	话单列表

话单明细（cdrList.cdr[]）

参数	类型	必填	说明
`number`	String	Y	外呼号码
`type`	String	Y	类型，固定 `0`
`display`	String	Y	显示号码
`state`	String	Y	应答标识：`0`=未应答，`1`=已应答
`starttime`	String	Y	开始时间 `YYYYMMDDHHmmss`
`ringtime`	String	N	振铃时间 `YYYYMMDDHHmmss`
`answertime`	String	N	应答时间 `YYYYMMDDHHmmss`
`stoptime`	String	Y	结束时间 `YYYYMMDDHHmmss`

请求示例

{
  "clientId": "",
  "sid": "S20210316095346538260AC11000C00472681",
  "vccId": "666666",
  "chargeExt": "1000",
  "callId": "C20210316095346AC11000C00472619",
  "seq": "3",
  "method": "cdr",
  "code": "20",
  "callResult": "103",
  "reason": "",
  "msServer": "ms3",
  "filePath": "",
  "callData": "",
  "cdrList": {
    "cdr": [{
      "type": "0",
      "number": "13800138001",
      "display": "60002",
      "state": "0",
      "starttime": "20210316095346",
      "ringtime": "",
      "answertime": "",
      "stoptime": "20210316095346"
    }]
  }
}

响应

回复 HTTP 200 即可。

四、获取通话录音

通话录音在 recordType=1 时启用。呼叫结束后，通过推送消息中的 filePath 和 msServer 参数构造 HTTP 下载请求：

1	GET http://{IP}:{Port}/cincc-serv/media/download?msServer={msServer}&filePath={filePath}

其中 IP 和 Port 由平台提供，为媒体资源服务器的访问地址。

接口调用时序

语音通知接口时序

整个调用链路的典型流程：

第三方平台发起 call 请求，携带号码与语音内容
能力平台返回 result: 0000，分配 callId 和 sid
能力平台异步发起外呼，推送 code: 10（开始呼叫）
被叫振铃时推送 code: 11
接通后推送 code: 21，播放语音通知
通话结束推送 code: 22 / 20 / 45
推送 cdr 话单，包含精确时间戳
第三方平台通过 download 接口拉取录音文件

语音通知系统架构

修订记录

日期	版本	变更内容
2025-04-03	v1.0	初始版本，支持语音通知基本呼叫
2025-04-11	v1.1	新增批量呼叫（`number` 支持多号码）；Prompt 支持 TTS 变量
2025-06-15	v1.2	新增 TTS 音色/音量/语速/语调参数（`speaker`/`volume`/`speed`/`pitch`）
2025-07-28	v1.3	`result` 错误码细化补充
2025-07-31	v1.4	新增 `collectParam` 和 `collectAction` 收号交互能力
2025-08-21	v1.5	事件推送与话单新增 `callId`；事件推送新增 `displayNumber` 和 `callResult` 扩展

语音通知接口 API 技术规范

概述

适用场景

通信模型

通用规范

1. 名词解释

2. API 请求规范

3. 事件推送规范

4. 鉴权机制

API 接口

一、语音通知外呼

接口描述

请求 URL

请求参数

Prompt 格式说明

收号控制（collectParam）

收号后继操作（collectAction）

请求示例

响应参数

响应示例

二、呼叫事件推送

接口描述

推送 URL

请求参数

外呼用户信息（userList.user[]）

请求示例

响应

三、话单推送

接口描述

推送 URL

请求参数

话单明细（cdrList.cdr[]）

请求示例

响应

四、获取通话录音

接口调用时序

修订记录

🔗 反向链接

Hoppscotch 开源 API 平台：自托管部署与团队协作实战

QuestDB 高性能时序数据库：从部署到生产实战