外呼机器人对外接口文档_v2.0
发行/变更日志
2021-09-10
- 新增任务统计情况查询接口
2021-09-02
- 回调结果新增callId字段
2019-07-02
- v2.0文档
2019-08-06
- 新增客户自定义字段存储
- 新增联系进度[排队中]
2019-09-03
- 结果查询及推送新增振铃时间、振铃时长字段
2019-11-26
- 结果查询及推送新增extId
2019-12-08
- 呼叫请求接口增加recallTimes未接通时重试次数字段
验证方式
接入时平台会把appId、appSecret给到业务方
签名计算方式
appSecret="123456"; //appId 对应的 appSecret,需要业务方高度保密
timestamp="1545372991205"; //毫秒时间戳字符串
sig=sha256(appSecret=123456×tamp=1545372991205) = c9f8f271384322fda0dfa65b3bcefc3608c46a3c707234171a5d296cbeb5d826
header
字段 | 字段类型 | 说明 |
---|---|---|
sig | string | 签名 |
appId | string | appId |
timestamp | string | 时间戳 |
时效性
timestamp会和服务器时间做对比,如果相差超过 10 分钟则会返回失败
API参数和输出
编码(encoding) 不支持协商,全部为UTF-8。无视HTTP header中的编码声明。
内容类型(Content-Type) 不支持协商,仅支持application/json。不接受其他类型的声明
输出 不支持协商,仅支持json。无视HTTP header中Accept的要求。 如无特殊说明,API不支持If-Modified-Since/If-None-Match,始终输出完整结果。
数据类型或格式
- JSON代码中出现的时间格式,如无特殊说明,均采用时间戳。
文档编辑
文中json代码为了书写方便,属性名也许存在未带双引号的情况(也可能在文档升级时解决该问题),编码时请全部按照含双引号的规范方式理解。
公共返回值
{
"code" : 200, // 请求返回码 200成功,其他返回码为失败
"msg" : "", // 错误信息
"data" : {} // 请求返回数据 json
}
服务地址
https://dm-robot.icsoc.net/robot/ext/
呼叫接口
批量增加呼叫请求
URL
/task/append/job
请求方式
POST
请求参数
{
"jobList" : [
{
"extId" : "2000" ,
"phone" : "15623***110" ,
"taskId" : 255 ,
"callerId" : "59222740",
"recallTimes" : 0 ,
"params" : {
"ttsName" : "Hello"
},
"userData": {
"username": "test",
"temp": "1"
}
}
]
}
说明:
参数 | 类型 | 说明 | 必选 | 约束/备注 |
---|---|---|---|---|
extId | string | 接口调用方针对这个号码呼叫标示唯一ID | 是 | 长度32位,唯一校验 |
phone | string | 被叫号码 | 是 | 手机号码校验 |
taskId | int | 任务ID | 是 | 必须为<获取任务列表>接口中存在的taskId |
callerId | string | 主叫号码 | 否 | 若传值,必须为系统配置的主叫号码;若为null或空,则从任务中随机选中一个主叫号码 |
recallTimes | int | 未接通时重试次数 | 否 | 默认为0,0表示呼叫未接通时不进行重呼,若值设为n,则表示呼叫未接通时,进行重呼产生n次新的呼叫,直到接通后,就不进行新呼叫;新呼叫的jobId与原有jobId不一样;目前默认在每次呼叫未接通后三分钟后发起重呼 |
params | map<string,string> | TTS合成自定义变量 | 否 | |
userData | map<string,string> | 自定义变量 | 否 | 用于存储的自定义变量在结果回调中原样返回 |
返回结果
{
"code" : 200 ,
"msg" : "操作成功" ,
"data" : {
"successList" : [
{
"extId" : "2000" ,
"phone" : "15623***110" ,
"jobId" : 1080
}
],
"failList" : [
{
"extId" : "2000" ,
"phone" : "15623***110" ,
"reason" : "..."
}
]
}
}
说明:
返回字段 | 字段类型 | 说明 |
---|---|---|
extId | string | 接口调用方针对这个号码呼叫标示唯一ID |
phone | string | 被叫号码 |
jobId | int | 呼叫唯一标识(需要调用方对这个值进行存储) |
reason | string | 失败原因 |
呼叫结果查询
URL
/job/info/{jobId}
请求方式
GET
请求参数
参数 | 类型 | 说明 | 必选 | 约束 |
---|---|---|---|---|
jobId | int | 呼叫唯一标识 | 是 | 必须为批量追加呼叫请求产生的jobId |
返回结果
{
"code" : 200 ,
"msg" : "操作成功" ,
"data" : {
"jobId" : 1080 ,
"extId": "5081917-0-1",
"callId": "6565225441255",
"phone" : "15623***110" ,
"callNumber" : "010****9122" ,
"progress" : 2 ,
"result" : 2 ,
"strategyName" : "******" ,
"commitTime" : 1522658414275 ,
"callTime" : 1522658414275 ,
"ringTime" : 1522658414275 ,
"connTime" : 1522658414275 ,
"endTime" : 1522658414275 ,
"ringDuration" : 3 ,
"callDuration" : 17 ,
"hangSide" : 1,
"recordUrl" : "http://....../record/2......" ,
"records" : [
{
"start" : 150,
"end" : 10712,
"content" : "您好,我是******......有XXX打算吗?",
"speaker" : 1
}
],
"labels" : [
{
"name" : "GS-A-00-01" ,
"sign" : "GS-A-00-01" ,
"describe" : null ,
"timestamp" : 1522658414275
}
],
"userData": {
"username": "test",
"temp": "1"
}
}
}
说明:
返回字段 | 字段类型 | 说明 |
---|---|---|
jobId | long | 呼叫唯一标识 |
extId | string | 接口调用方针对这个号码呼叫标示唯一ID |
callId | string | 接通后的呼叫唯一标识 |
phone | string | 被叫号码 |
callNumber | string | 主叫号码 |
progress | int | 联系进度 (枚举值) |
result | int | 联系结果 (枚举值) |
strategyName | string | AI语料库 |
commitTime | long | 提交时间(时间戳-毫秒)一个呼叫请求记录到库的时间 |
callTime | long | 呼出时间(时间戳-毫秒)对 多个呼叫请求 排队后,实际单个呼叫请求的呼叫的时间 |
ringTime | long | 振铃时间(时间戳-毫秒)客户电话振铃时间 |
connTime | long | 接通时间(时间戳-毫秒)客户接听电话的开始时间(接通后录音) |
endTime | long | 挂机时间(时间戳-毫秒)电话挂机时间 |
ringDuration | int | 振铃总时长(秒) |
callDuration | int | 通话总时长(秒) |
hangSide | int | 挂机方(枚举值) |
recordUrl | string | 录音文件地址 |
records | array[record] | 通话内容,record数组,一个record为对话过程中的一句话 |
record.start | int | 一句话相对于录音文件的开始时间 |
record.end | int | 一句话相对于录音文件的结束时间 |
record.content | string | 内容 |
record.speaker | int | 说话方 (枚举值) |
labels | array[label] | 通话标签 |
label.name | string | 标签名称 |
label.sign | string | 标签标示 |
label.describe | string | 标签描述 |
label.timestamp | long | 标签产生时间 |
userData | map<string,string> | 自定义变量 |
获取呼叫成功JobId列表
URL
/job/success/list
请求方式
POST
请求参数
{
"startTime" : 1546396855000 ,
"endTime" : 1546396894000
}
说明:
参数 | 类型 | 说明 | 必选 | 约束 |
---|---|---|---|---|
startTime | long | 查询时间范围的开始时间 | 否 | 时间戳(毫秒) |
endTime | long | 查询时间范围的结束时间(都不传时,默认取最近五分钟内成功的jobId列表) | 否 | 时间戳(毫秒) |
返回结果
{
"code" : 200 ,
"msg" : "操作成功" ,
"data" : {
"jobIds" : [ 1765,1764,1762 ]
}
}
说明:
返回字段 | 字段类型 | 说明 |
---|---|---|
jobIds | array[int] | 呼叫成功的jobId数组 |
批量取消呼叫
URL
/job/cancel
请求方式
POST
请求参数
{
"jobIds" : [ 1765,1764,1762 ]
}
说明:
参数 | 类型 | 说明 | 必选 | 约束 |
---|---|---|---|---|
jobIds | array[int] | 待取消呼叫的jobId数组 | 必填 | 数组最大长度为50 |
返回结果
{
"code" : 200 ,
"msg" : "操作成功" ,
"data" : {
"successList" : [ 1765,1764 ],
"failList" : [
{
"jobId" : 1080,
"reason" : 1
}
]
}
}
说明:
返回字段 | 字段类型 | 说明 |
---|---|---|
successList | array[int] | 取消呼叫成功的JobIds列表 |
failList | array[failInfo] | 取消呼叫失败列表 |
failInfo.jobId | int | 取消呼叫失败的JobId |
failInfo.reason | int | 取消失败的原因 |
批量恢复呼叫
批量恢复被取消的呼叫 URL
/job/restart
请求方式
POST
请求参数
{
"jobIds" : [ 1765,1764,1762 ]
}
说明:
参数 | 类型 | 说明 | 必选 | 约束 |
---|---|---|---|---|
jobIds | array[int] | 待恢复呼叫的jobId数组 | 必填 | 数组最大长度为50 |
返回结果
{
"code" : 200 ,
"msg" : "操作成功" ,
"data" : {
"successList" : [ 1765,1764 ],
"failList" : [
{
"jobId" : 1080,
"reason" : 1
}
]
}
}
说明:
返回字段 | 字段类型 | 说明 |
---|---|---|
successList | array[int] | 恢复呼叫成功的JobIds列表 |
failList | array[failInfo] | 恢复呼叫失败的列表 |
failInfo.jobId | int | 恢复呼叫失败的JobId |
failInfo.reason | int | 恢复呼叫失败的原因 |
呼叫任务统计情况查询
URL
/task/statistic
请求方式
POST
请求参数
{
"startDate": "2021-09-01",
"endDate": "2021-09-10",
"taskIds": [
10179,
10177
]
}
说明
参数 | 类型 | 说明 | 必选 | 约束 |
---|---|---|---|---|
startDate | string | 开始日期字符串 | 是 | 格式yyyy-MM-dd ,如2021-09-01 |
endDate | string | 结束日期字符串 | 是 | 格式yyyy-MM-dd ,如2021-09-01 ,开始到结束跨度不超过90天 |
taskIds | array[int] | 任务ID集合 | 是 | 待查询任务ID集合 |
返回结果
{
"msg": "操作成功",
"data": [
{
"dayStr": "2021-09-09",
"taskName": "测试1",
"taskId": 10179,
"receiveNum": 3,
"calledNum": 3,
"answeredNum": 1,
"answeredRate": "33.33%"
}
],
"code": 200
}
说明:
返回字段 | 字段类型 | 说明 |
---|---|---|
dayStr | string | 日期 |
taskName | string | 任务名称 |
taskId | int | 任务ID |
receiveNum | int | 当日接收数据量 |
calledNum | int | 当日外呼量 |
answeredNum | int | 当日接通量 |
answeredRate | int | 当日接通率 |
结果推送服务
呼叫结果推送
URL
需提前客户给出推送的地址,并根据下面的协议实现响应接口接收推送结果
认证方式
需客户实现一套相同的签名计算方式进行验证
请求方式
POST
包体参数
{
"jobId" : 1080 ,
"extId": "5081917-0-1",
"callId": "62656485154285",
"phone" : "15623***110" ,
"callNumber" : "010****9122" ,
"progress" : 2 ,
"result" : 2 ,
"strategyName" : "******" ,
"commitTime" : 1522658414275 ,
"callTime" : 1522658414275 ,
"ringTime" : 1522658414275 ,
"connTime" : 1522658414275 ,
"endTime" : 1522658414275 ,
"ringDuration" : 3 ,
"callDuration" : 17 ,
"hangSide" : 1,
"recordUrl" : "http://....../record/2......" ,
"records" : [
{
"start" : 150,
"end" : 10712,
"content" : "您好,我是******......有XXX打算吗?",
"speaker" : 1
}
],
"labels" : [
{
"name" : "GS-A-00-01" ,
"sign" : "GS-A-00-01" ,
"describe" : null ,
"timestamp" : 1522658414275
}
],
"effectiveLabels" : {
"code" : "COMPLAIN",
"intention" : "不明确",
"relation" : "三方"
},
"userData": {
"username": "test",
"temp": "1"
}
}
说明:
返回字段 | 字段类型 | 说明 |
---|---|---|
jobId | int | 呼叫唯一标识 |
extId | string | 接口调用方针对这个号码呼叫标示唯一ID |
callId | string | 接通后的呼叫唯一标识 |
phone | string | 被叫号码 |
callNumber | string | 主叫号码 |
progress | int | 联系进度 (枚举值) |
result | int | 联系结果 (枚举值) |
strategyName | string | AI语料库 |
callIndex | int | 拨打次数 (在后期针对jobId对应呼叫进行重呼时可能用到,自增策略) |
commitTime | long | 提交时间(时间戳-毫秒)一个呼叫请求记录到库的时间 |
callTime | long | 呼出时间(时间戳-毫秒)对 多个呼叫请求 排队后,实际单个呼叫请求的呼叫的时间 |
ringTime | long | 振铃时间(时间戳-毫秒)客户电话振铃时间 |
connTime | long | 接通时间(时间戳-毫秒)客户接听电话的开始时间(接通后录音) |
endTime | long | 挂机时间(时间戳-毫秒)电话挂机时间 |
ringDuration | int | 振铃总时长(秒) |
callDuration | int | 通话总时长(秒) |
hangSide | int | 挂机方(枚举值) |
recordUrl | string | 录音文件地址 |
records | array[record] | 通话内容,record数组,一个record为对话过程中的一句话 |
record.start | int | 一句话相对于录音文件的开始时间 |
record.end | int | 一句话相对于录音文件的结束时间 |
record.content | string | 内容 |
record.speaker | int | 说话方 (枚举值) |
labels | array[label] | 通话标签 |
label.name | string | 标签名称 |
label.sign | string | 标签标示 |
label.describe | string | 标签描述 |
label.timestamp | long | 标签产生时间 |
effectiveLabels | map<string,string> | 根据配置的有效标签计算逻辑计算出的有效标签 K:类型 V:标签值 |
userData | map<string,string> | 自定义变量 |
返回结果 无
- 接受到推送请求后,HTTP请求响应状态为200时,认定为外呼结果推送成功,推送成功后将不会进行重试。否则,重试三次放弃。
- 只有通过批量增加呼叫请求接口增加的任务,才进行回调
- 转人工时,立刻发起推送失败后立即重试三次,总计四次失败后不再推送
- 正常挂机,排队回调推送失败后排队重试三次,总计四次失败后不再推送
- 设置了未接通时重试次数recallTimes后,会进行多次推送(n次重呼,就有n次推送),多次推送的结果的JobId是不同,但是多次推送结果的extId一致
枚举值
联系进度
值 | 说明 |
---|---|
0 | 未联系 |
1 | 联系中 |
2 | 已联系 |
3 | 已暂停 |
4 | 已取消 |
5 | 排队中 |
联系结果
值 | 说明 |
---|---|
0 | 无法接通 |
1 | 空号 |
2 | 接听后挂断 |
5 | 转人工 |
10 | 无人接听 |
11 | 占线 |
12 | 关机 |
13 | 停机 |
14 | 号码错误 |
15 | 网络异常 |
16 | 无法接通[无法识别] |
说话方
值 | 说明 |
---|---|
0 | 客户说话 |
1 | 机器人说话 |
呼叫取消失败原因
值 | 说明 |
---|---|
1 | 呼叫任务已取消 |
2 | 呼叫已进入排队 |
3 | 呼叫已完成[无法取消] |
4 | 呼叫任务不存在 |
呼叫恢复失败原因
值 | 说明 |
---|---|
1 | 呼叫任务已暂停 |
2 | 呼叫已进入排队 |
3 | 呼叫已完成[不需要恢复] |
4 | 呼叫任务不存在 |
5 | 呼叫任务未就绪 |
挂机方
值 | 说明 |
---|---|
0 | 客户挂机 |
1 | 机器人挂机 |
错误码
系统错误码
值 | 说明 |
---|---|
401 | 鉴权失败 |
5000 | 服务运行错误,请联系管理员 |
5001 | 请求体没有包含正确的version值 |
5002 | 参数校验未通过 |
5003 | 服务内部异常,请重试 |
业务错误码
值 | 说明 |
---|---|
51001 | 呼叫工作不存在 |
51002 | 通话记录生成中 |
51003 | timestamp和服务器相差超过10分钟 |
51004 | 任务追加数量超过限制,单次50个 |