外呼机器人对外接口文档_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&timestamp=1545372991205) = c9f8f271384322fda0dfa65b3bcefc3608c46a3c707234171a5d296cbeb5d826

header

字段字段类型说明
sigstring签名
appIdstringappId
timestampstring时间戳

时效性

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"
            }
        }
    ]
}

说明：

参数类型说明必选约束/备注
extIdstring接口调用方针对这个号码呼叫标示唯一ID是长度32位,唯一校验
phonestring被叫号码是手机号码校验
taskIdint任务ID是必须为<获取任务列表>接口中存在的taskId
callerIdstring主叫号码否若传值，必须为系统配置的主叫号码；若为null或空，则从任务中随机选中一个主叫号码
recallTimesint未接通时重试次数否默认为0，0表示呼叫未接通时不进行重呼，若值设为n，则表示呼叫未接通时，进行重呼产生n次新的呼叫，直到接通后，就不进行新呼叫;新呼叫的jobId与原有jobId不一样;目前默认在每次呼叫未接通后三分钟后发起重呼
paramsmap<string,string>TTS合成自定义变量否
userDatamap<string,string>自定义变量否用于存储的自定义变量在结果回调中原样返回

返回结果

{
    "code" : 200 ,
    "msg" : "操作成功" ,
    "data" : {
        "successList" : [
            {
                "extId" : "2000" ,
                "phone" : "15623***110" ,
                "jobId" : 1080
            }
        ],
        "failList" : [
            {
                "extId" : "2000" ,
                "phone" : "15623***110" ,
                "reason" : "..."
            }
        ]
    }
}

说明：

返回字段字段类型说明
extIdstring接口调用方针对这个号码呼叫标示唯一ID
phonestring被叫号码
jobIdint呼叫唯一标识（需要调用方对这个值进行存储）
reasonstring失败原因

呼叫结果查询

URL

/job/info/{jobId}

请求方式

GET

请求参数

参数类型说明必选约束
jobIdint呼叫唯一标识是必须为批量追加呼叫请求产生的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"
        }
    }
}

说明：

返回字段字段类型说明
jobIdlong呼叫唯一标识
extIdstring接口调用方针对这个号码呼叫标示唯一ID
callIdstring接通后的呼叫唯一标识
phonestring被叫号码
callNumberstring主叫号码
progressint联系进度 （枚举值）
resultint联系结果 （枚举值）
strategyNamestringAI语料库
commitTimelong提交时间（时间戳-毫秒）一个呼叫请求记录到库的时间
callTimelong呼出时间（时间戳-毫秒）对 多个呼叫请求 排队后，实际单个呼叫请求的呼叫的时间
ringTimelong振铃时间（时间戳-毫秒）客户电话振铃时间
connTimelong接通时间（时间戳-毫秒）客户接听电话的开始时间（接通后录音）
endTimelong挂机时间（时间戳-毫秒）电话挂机时间
ringDurationint振铃总时长（秒）
callDurationint通话总时长（秒）
hangSideint挂机方（枚举值）
recordUrlstring录音文件地址
recordsarray[record]通话内容，record数组，一个record为对话过程中的一句话
record.startint一句话相对于录音文件的开始时间
record.endint一句话相对于录音文件的结束时间
record.contentstring内容
record.speakerint说话方 （枚举值）
labelsarray[label]通话标签
label.namestring标签名称
label.signstring标签标示
label.describestring标签描述
label.timestamplong标签产生时间
userDatamap<string,string>自定义变量

获取呼叫成功JobId列表

URL

/job/success/list

请求方式

POST

请求参数

{
    "startTime" :  1546396855000 ,
    "endTime" :  1546396894000
}

说明：

参数类型说明必选约束
startTimelong查询时间范围的开始时间否时间戳（毫秒）
endTimelong查询时间范围的结束时间（都不传时，默认取最近五分钟内成功的jobId列表）否时间戳（毫秒）

返回结果

{
    "code" : 200 ,
    "msg" : "操作成功" ,
    "data" : {
        "jobIds" : [ 1765,1764,1762 ]
    }
}

说明：

返回字段字段类型说明
jobIdsarray[int]呼叫成功的jobId数组

批量取消呼叫

URL

/job/cancel

请求方式

POST

请求参数

{
    "jobIds" :  [ 1765,1764,1762 ]
}

说明：

参数类型说明必选约束
jobIdsarray[int]待取消呼叫的jobId数组必填数组最大长度为50

返回结果

{
    "code" : 200 ,
    "msg" : "操作成功" ,
    "data" : {
        "successList" : [ 1765,1764 ],
        "failList" : [
            {
                "jobId" : 1080,
                "reason" : 1
            }
        ]
    }
}

说明：

返回字段字段类型说明
successListarray[int]取消呼叫成功的JobIds列表
failListarray[failInfo]取消呼叫失败列表
failInfo.jobIdint取消呼叫失败的JobId
failInfo.reasonint取消失败的原因

批量恢复呼叫

批量恢复被取消的呼叫 URL

/job/restart

请求方式

POST

请求参数

{
    "jobIds" :  [ 1765,1764,1762 ]
}

说明：

参数类型说明必选约束
jobIdsarray[int]待恢复呼叫的jobId数组必填数组最大长度为50

返回结果

{
    "code" : 200 ,
    "msg" : "操作成功" ,
    "data" : {
        "successList" : [ 1765,1764 ],
        "failList" : [
            {
                "jobId" : 1080,
                "reason" : 1
            }
        ]
    }
}

说明：

返回字段字段类型说明
successListarray[int]恢复呼叫成功的JobIds列表
failListarray[failInfo]恢复呼叫失败的列表
failInfo.jobIdint恢复呼叫失败的JobId
failInfo.reasonint恢复呼叫失败的原因

呼叫任务统计情况查询

URL

/task/statistic

请求方式

POST

请求参数

{
  "startDate": "2021-09-01",
  "endDate": "2021-09-10",
  "taskIds": [
    10179,
    10177
  ]
}

说明

参数类型说明必选约束
startDatestring开始日期字符串是格式yyyy-MM-dd,如2021-09-01
endDatestring结束日期字符串是格式yyyy-MM-dd,如2021-09-01,开始到结束跨度不超过90天
taskIdsarray[int]任务ID集合是待查询任务ID集合

返回结果

{
  "msg": "操作成功",
  "data": [
    {
      "dayStr": "2021-09-09",
      "taskName": "测试1",
      "taskId": 10179,
      "receiveNum": 3,
      "calledNum": 3,
      "answeredNum": 1,
      "answeredRate": "33.33%"
    }
  ],
  "code": 200
}

说明：

返回字段字段类型说明
dayStrstring日期
taskNamestring任务名称
taskIdint任务ID
receiveNumint当日接收数据量
calledNumint当日外呼量
answeredNumint当日接通量
answeredRateint当日接通率

结果推送服务

呼叫结果推送

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"
    }
}

说明：

返回字段字段类型说明
jobIdint呼叫唯一标识
extIdstring接口调用方针对这个号码呼叫标示唯一ID
callIdstring接通后的呼叫唯一标识
phonestring被叫号码
callNumberstring主叫号码
progressint联系进度 （枚举值）
resultint联系结果 （枚举值）
strategyNamestringAI语料库
callIndexint拨打次数 (在后期针对jobId对应呼叫进行重呼时可能用到，自增策略)
commitTimelong提交时间（时间戳-毫秒）一个呼叫请求记录到库的时间
callTimelong呼出时间（时间戳-毫秒）对 多个呼叫请求 排队后，实际单个呼叫请求的呼叫的时间
ringTimelong振铃时间（时间戳-毫秒）客户电话振铃时间
connTimelong接通时间（时间戳-毫秒）客户接听电话的开始时间（接通后录音）
endTimelong挂机时间（时间戳-毫秒）电话挂机时间
ringDurationint振铃总时长（秒）
callDurationint通话总时长（秒）
hangSideint挂机方（枚举值）
recordUrlstring录音文件地址
recordsarray[record]通话内容，record数组，一个record为对话过程中的一句话
record.startint一句话相对于录音文件的开始时间
record.endint一句话相对于录音文件的结束时间
record.contentstring内容
record.speakerint说话方 （枚举值）
labelsarray[label]通话标签
label.namestring标签名称
label.signstring标签标示
label.describestring标签描述
label.timestamplong标签产生时间
effectiveLabelsmap<string,string>根据配置的有效标签计算逻辑计算出的有效标签 K:类型 V：标签值
userDatamap<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通话记录生成中
51003timestamp和服务器相差超过10分钟
51004任务追加数量超过限制，单次50个
Last updated on 9/9/2021 by luyongbing
← 外呼机器人对外接口文档_v1.0媒体库对外接口文档_v1.0 →