外呼机器人对外接口文档_v1.0

发行/变更日志

2018-12-21

v1.0文档

2018-12-22

1. 增加v1.0文档错误码描述
1. 增加对查询呼叫结果拨打次数的说明

2018-12-24

1. 增加提交时间、呼出时间、接通时间的详细描述

2019-01-02

1. 批量增加呼叫请求接口增加主叫号码字段
1. 增加拉取呼叫成功的JobId列表

2019-03-20

1. 增加批量取消呼叫接口
1. 增加批量恢复呼叫接口

验证方式

接入时平台会把appId、appSecret给到业务方

签名计算方式

appSecret="123456"; //appId 对应的 appSecret，需要业务方高度保密
timestamp="1545372991205"; //毫秒时间戳字符串
sig=sha256(appSecret=123456&timestamp=1545372991205) = c9f8f271384322fda0dfa65b3bcefc3608c46a3c707234171a5d296cbeb5d826

header

字段	字段类型	说明
sig	string	签名
appId	string	appId
timestamp	string	时间戳

时效性

timestamp会和服务器时间做对比，如果相差超过 10 分钟则会返回失败

API参数和输出

编码（encoding） 不支持协商，全部为UTF-8。无视HTTP header中的编码声明。

输出不支持协商，仅支持json。无视HTTP header中Accept的要求。如无特殊说明，API不支持If-Modified-Since/If-None-Match，始终输出完整结果。

数据类型或格式

JSON代码中出现的时间格式，如无特殊说明，均采用时间戳。

文档编辑

文中json代码为了书写方便，属性名也许存在未带双引号的情况（也可能在文档升级时解决该问题），编码时请全部按照含双引号的规范方式理解。

公共返回值

{
    "code" : 200,          // 请求返回码 200成功，其他返回码为失败
    "msg" : "",            // 错误信息
    "data" : {}            // 请求返回数据 json
}

服务地址

http://robot.icsoc.net/robot/ext/

接口列表

获取任务列表

URL

/task/list

请求方式

GET

请求参数 无

返回结果

{
    "code" : 200 ,
    "msg" : "操作成功" ,
    "data" : [
        {
            "taskId" : 255 ,
            "taskName" : "1220***测试北京" ,
            "strategyName" : "******" ,
            "callNums" : [ "59***740" , "15623***110" ] ,
            "workTime" : "周日的时间" 
        }
    ]
}

说明：

返回字段	字段类型	说明
taskId	int	任务ID
taskName	string	任务名称
strategyName	string	话术名称
callNums	array[string]	主叫号码
workTime	string	日程规则名称

批量增加呼叫请求

URL

/task/append/job

请求方式

POST

请求参数

{
    "jobList" : [
        {
            "extId" : "2000" ,
            "phone" : "15623***110" ,
            "taskId" : 255 ,
            "callerId" : "59222740"
        }
    ]
}

说明：

参数	类型	说明	必选	约束
extId	string	接口调用方针对这个号码呼叫标示唯一ID	是	长度32位,唯一校验
phone	string	被叫号码	是	手机号码校验
taskId	int	任务ID	是	必须为<获取任务列表>接口中存在的taskId
callerId	string	主叫号码	否	若传值，必须为系统配置的主叫号码；若为null或空，则从任务中随机选中一个主叫号码

返回结果

{
    "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 ,
        "phone" : "15623***110" ,
        "callNumber" : "01080909122" ,
        "progress" : 2 ,
        "result" : 2 ,
        "strategyName" : "******" ,
        "commitTime" : 1522658414275 ,
        "callTime" : 1522658414275 ,
        "connTime" : 1522658414275 ,
        "callDuration" : 17 ,
        "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
            }
        ]
    }
}

说明：

返回字段	字段类型	说明
jobId	int	呼叫唯一标识
phone	string	被叫号码
callNumber	string	主叫号码
progress	int	联系进度（枚举值）
result	int	联系结果（枚举值）
strategyName	string	AI语料库
callIndex	int	拨打次数 (在后期针对jobId对应呼叫进行重呼时可能用到，自增策略)
commitTime	long	提交时间（时间戳-毫秒）一个呼叫请求记录到库的时间
callTime	long	呼出时间（时间戳-毫秒）对多个呼叫请求排队后，实际单个呼叫请求的呼叫的时间
connTime	long	接通时间（时间戳-毫秒）客户接听电话的开始时间（接通后录音）
callDuration	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	标签描述

获取呼叫成功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

需提前客户给出推送的地址，并根据下面的协议实现响应接口接收推送结果

认证方式

需客户实现一套相同的签名计算方式进行验证

请求方式

POST

包体参数

{
    "extId" : "2000" ,
    "jobId": 1080,
    "phone": "15623***110",
    "callNumber" : "01080909122" ,
    "progress": 2,
    "result": 2,
    "strategyName": "******",
    "commitTime": 1522658414275,
    "callTime": 1522658414275,
    "connTime": 1522658414275,
    "callDuration": 17,
    "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
        }
    ]
}

说明：

返回字段	字段类型	说明
extId	string	接口调用方针对这个号码呼叫标示唯一ID
jobId	int	呼叫唯一标识
phone	string	被叫号码
callNumber	string	主叫号码
progress	int	联系进度（枚举值）
result	int	联系结果（枚举值）
strategyName	string	AI语料库
callIndex	int	拨打次数 (在后期针对jobId对应呼叫进行重呼时可能用到，自增策略)
commitTime	long	提交时间（时间戳-毫秒）一个呼叫请求记录到库的时间
callTime	long	呼出时间（时间戳-毫秒）对多个呼叫请求排队后，实际单个呼叫请求的呼叫的时间
connTime	long	接通时间（时间戳-毫秒）客户接听电话的开始时间（接通后录音）
callDuration	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	标签描述

返回结果 无

接受到推送请求后，HTTP请求响应状态为200时，认定为外呼结果推送成功，推送成功后将不会进行重试。否则，重试三次放弃。
只有通过批量增加呼叫请求接口增加的任务，才进行回调
转人工时，立刻发起推送失败后立即重试三次，总计四次失败后不再推送
正常挂机，排队回调推送失败后排队重试三次，总计四次失败后不再推送

枚举值

联系进度

值	说明
0	未联系
1	联系中
2	已联系
3	已暂停
4	已取消

联系结果

值	说明
0	无法接通
1	空号
2	接听后挂断
3	邀约失败
4	邀约成功
5	转人工
10	无人接听
11	占线
12	关机
13	停机
14	号码错误
15	网络异常
16	无法接通[无法识别]

说话方

值	说明
0	客户说话
1	机器人说话

呼叫取消失败原因

值	说明
1	呼叫任务已取消
2	呼叫已进入排队
3	呼叫已完成[无法取消]
4	呼叫任务不存在

呼叫恢复失败原因

值	说明
1	呼叫任务已暂停
2	呼叫已进入排队
3	呼叫已完成[不需要恢复]
4	呼叫任务不存在
5	呼叫任务未就绪

错误码

系统错误码

值	说明
401	鉴权失败
5000	服务运行错误，请联系管理员
5001	请求体没有包含正确的version值
5002	参数校验未通过
5003	服务内部异常，请重试

业务错误码

值	说明
51001	呼叫工作不存在
51002	通话记录生成中
51003	timestamp和服务器相差超过10分钟
51004	任务追加数量超过限制，单次50个

开发者平台

wincall V2

外呼机器人对外接口文档_v1.0

发行/变更日志

验证方式

签名计算方式

header

时效性

API参数和输出

数据类型或格式

文档编辑

公共返回值

服务地址

接口列表

获取任务列表

批量增加呼叫请求

呼叫结果查询

获取呼叫成功JobId列表

批量取消呼叫

批量恢复呼叫

推送服务

结果推送

枚举值

联系进度

联系结果

说话方

呼叫取消失败原因

呼叫恢复失败原因

错误码

系统错误码

业务错误码