Blu接口文档 Copy
[TOC]
缩略词与名词解释
| 缩略语 | 全称 | 备注 |
|---|---|---|
| API | 指平台对外的接口能力 | |
| appId | 调用方应用标识，用于调用接口时鉴权 | 请联系对接运营获取 |
| appKey | 调用方密钥，用于调用接口时鉴权 | 请联系对接运营获取 |
| timeStamp | 过去的毫秒数，生成规则：timeStamp=new Date().getTime(); | |
| sign | 签名，规则为：sign = sha256(appId+appKey+timestamp) |
接口说明
接口协议使用HTTPS，由服务提供方提供访问的URL规范，创建任务使用POST方法发送请求并获取应答报文；查询接口采用GET方法（详见接口描述）。发起和返回报文统一使用UTF-8编码。调用方与平台间交互同步等待超时时间根据实际情况协商。
注：所有接口入参不支持emoji等特殊字符。
生产环境地址： https://bluapi.shanghu.ai/
鉴权接口
调用方需先向运营对接人申请appId和appKey，在请求报文头中加上appId、timeStamp、sign参数用于身份鉴权。
鉴权接口请求参数
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| appId | Y | string | 调用方id（请联系运营获取） |
| timeStamp | Y | string | 过去的毫秒数，生成规则： timeStamp=new Date().getTime(); |
| sign | Y | string | 签名规则为： sha256(appId+a ppKey+timestamp) |
交互接口总览
说明：建议一次性对接创建任务、上传名单、外呼回调、拨打（触达）前验证接口，拨打结果查询和取消名单接口可以不用对接。
创建任务接口
创建任务接口请求示例
POST /rest/v1/createTask
appId: 10001
timeStamp: 1626856869046
sign: 84e00b98ea02b9afd0aa20d289ff5979df9308278572d7300d24dea85ef5a948
Content-Type: application/json
{
"taskName": "Bahasa-202102021259",
"strategy": 2
}
创建任务接口请求参数
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| taskName | Y | string | 任务名称：不能超过100个字符。支持英文字符、数字、下划线。字母不区分大小写。推荐使用场景+日期，例如：“ H1_20230412 ” |
| strategy | Y | Long | 策略id（请联系对接运营获取） |
创建任务接口返回示例
创建任务成功样例：
{
"code": 2000,
"message": "success",
"taskId": 66635573
}
创建任务异常-任务名重复：（建议更换任务名重试）
{
"code": 401,
"message": "Task name duplicated"
}
创建任务异常-指定策略不存在：（建议联系运营对接人核实）
{
"code": 402,
"message": "Strategy not existed"
}
创建任务异常-商户被禁用：（建议联系运营对接人核实）
{
"code": 403,
"message": "Tenant was disabled"
}
创建任务异常-缺少动参：（建议联系运营对接人核实）
{
"code": 408,
"message": "upload records missing variable"
}
创建任务异常-其他错误：（建议联系我方测试或运营对接人核实）
{
"code": 500,
"message": "error message"
}
创建任务接口响应参数说明
| 参数名 | 类型 | 说明 | 备注 |
|---|---|---|---|
| code | Integer | 响应码 | |
| message | String | 响应说明 | 响应码对应的说明信息： 2000 -- succuss ： 创建成功 402 -- Strategy not existed： 策略不存在 403 -- Tenant was disabled： 商户禁用 408 -- upload records missing variable: 缺少动参 500 -- error message： 其他错误 |
| taskId | Long | 任务id | 创建任务失败则返回空 |
上传数据接口
上传数据成功后，会按照任务绑定的策略配置，自动执行外呼任务。单次上传建议200条，限量1000条。
注意：
- 一个任务内可以上传的名单不限量，名单量较大时，请分批上传。
- 一个任务（按当地时间）当日内有效，第二天请生成新的任务。
- 已经取消（过期）的任务请勿再继续上传名单。
上传数据接口请求示例
POST /rest/v1/uploadAndStartJob
{
"taskId": 66635573,
"records": [{
"id":55667448，
"name":"Anoj Mohoo",
"mobile":"0177****3990",
"extVars":"{"key":"string","intkey":10000}",
"callVars":"{"name":"Bob","salary":10000}"
}]
}
上传数据接口请求参数
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| taskId | Y | Long | 创建任务成功时获取的任务ID |
| record | Y | JsonArray | 数据内容，字段详见下方说明。 |
record入参说明
| 参数名 | 必选 | 类型 | 说明 |
|---|---|---|---|
| id | Y/N | Long | 用户身份标识，纯数字，长度必须小于10个数字 |
| name | Y/N | String | 用户姓名，支持字母或数字，不支持特殊符号，长度100以内。 （注：为保证良好的对话体验，运营人员可能对此字段有其他约定，例如只取first name等，请以运营约定为准） |
| mobile | Y | String | 用户手机号，纯数字，长度不超过20个数字 无需添加国家码 |
| extVars | Y/N | Map | 重要说明： 1. 随路数据及触达前验证的入参，通过此字段传入。 2. extVars透传参数的长度限制为2000字符以内。 3. Map的json形式，例如：{'key':'string','intkey':10000}。 4. 请提前与运营约定需要传哪些动参。 |
| callVars | Y/N | Map | 重要说明： 1. 机器人对话及消息动参，通过此字段传入。例如，语音机器人话术中的动参ClientName和AppName、消息中的动参,如：短信或WABA消息中的link等，放在此字段中传入。 2. Map的json形式，例如：{'name':'张先生','Repayment date ':2月3日}。拼接效果：尊敬的{张先生}，请您在{2月3日}前完成还款。 3. 注意：请确保传入动参值中，不含 < > 符号，否则，可能会影响机器人朗读变量。 4. 请提前与运营约定需要传哪些动参。 |
上传数据接口返回示例
数据上传成功：
{
"code": 2000,
"message": "success",
"count": 2
}
数据上传异常-taskid过期-taskid在当地时间当自然日内有效，第二天的名单请勿传到过期任务中
{
"code": 400,
"message": "The taskId:%s has expired,Please create a new taskId.",
}
数据上传异常-校验错误
{
"code": 405,
"message": "strategy validation error"
}
数据上传异常-校验错误-策略未启用
{
"code": 406,
"message": "strategy of this task is not enable now"
}
数据上传异常-其他错误
{
"code": 500,
"message": "internal error"
}
上传数据接口返回参数说明
|参数名|类型|说明|参数说明|
|:----- |:-----|----- |
|code |Integer |响应码 |详见下表|
|message |String |响应说明 |响应码对应的说明信息|
|count |Long |处理总数 |上传成功记录总数|
|errors|JsonArray |错误字段 |具体错误信息见下表|
字段code枚举值
|响应码|响应码对应的说明信息：|
|:----- |:-----|----- |
|2000 |正常入库|
|400 |参数错误，包含空值|
|401 |单次上传数据条数超限|
|404 |taskId对应的任务不存在|
|405 |validation校验后剩余正确记录数量为0|
|406 |taskId对应的任务所选策略异常|
|500|内部异常|
字段errors结构
|参数名|类型|说明|参数说明|
|:----- |:-----|----- |
|index |Integer |记录编号 |错误记录编号|
|Id|Long |上传用户参数 |业务上传的用户id|
|errors |Array|错误信息 |具体错误|
拨打（触达）前验证接口
功能说明：在发起外呼（触达）前，blu调用拨打（触达）前验证接口查询用户的当前状态，判断是否执行拨打（触达）。
例如，每次拨打催收电话前，查询用户的还款状态，若用户已还款，则放弃拨打。
拨打（触达）前验证接口请求示例
POST 商户配置URL
Content-type:application/json;charset=utf-8
其他商户自定义Headers
注：回调接口如需加验签，需排期订制开发。不加验签我方可配置上线，即时可用。 安全问题可以加ip白名单控制。
拨打（触达）前验证接口请求参数
| 参数名 | 必选 | 类型 | 参数说明 |
|---|---|---|---|
| 甲方自定义参数 | N | string | 进件时通过extVars字段传入。我方可透传。例如：appid，customerid，scenecode，version等等。 |
| 甲方自定义参数2 | N | string |
注：至少要有一个自定义参数，可设多个自定义参数，所设参数进线时通过extVars字段传入，我方取传入值调用拨打前验证接口。
拨打（触达）前验证接口返回参数
| 参数名 | 必选 | 类型 | 参数说明 |
|---|---|---|---|
| code | Y | Integer | 响应码，取消拨打请返回0，其他数字视为继续拨打 |
| message | Y | string | 响应码对应的说明信息 |
取消触达接口
功能说明：上传名单后，需要取消（外呼等）触达
例如，提交了催收拨打名单，中途用户自主还款了，需要取消后续拨打。
取消触达请求示例
POST /rest/v1/taskCancelPhoneCall
{
"taskId": 66635573,
"mobile": "13688888888"
"orderId":123456
}
取消触达接口请求参数
| 参数名 | 必选 | 类型 | 参数说明 |
|---|---|---|---|
| taskId | Y | Long | 进件时传的taskId。 |
| mobile | Y | string | 手机号码 |
| orderId | N | string | 进件时需通过extVars传入值，此处传入同样的值用以取消 |
注：传了orderId，视为按orderId取消，匹配不到则报错。未传orderId视为用手机号匹配，取消该任务下，所有此号码的（外呼等）触达。
取消触达接口返回参数
| 参数名 | 必选 | 类型 | 参数说明 |
|---|---|---|---|
| code | Y | Integer | 2000 成功 4000 传参错误 4004 任务/手机号不存在 4005 号码已存在 5001 系统错误 |
| message | Y | string | 2000 成功 4000 传参错误 4004 任务/手机号不存在 4005 号码已存在 5001 系统错误 |
拨打结果查询接口
拨打结果查询接口请求示例
POST /rest/v1/queryCallResult
{
"taskId": "5573",
}
拨打结果查询接口请求参数
| 参数名 | 必选 | 类型 | 参数说明 |
|---|---|---|---|
| taskId | Y | Long | 创建任务成功时获取的任务ID ，是一个任务的唯一标识 |
| jobId | N | Long | 批次ID，一个任务内会出现多个不同jobid，如传入该参数则返回该批次通话结论，否则返回整个任务数据 |
| pageNo | N | Integer | 页数，默认1 |
| pageSize | N | Long | 单页记录数，默认为10条，最大1000条 |
说明：1. 只根据taskId请求时，返回的数据，默认每页10条，查第1页；2. 如果根据taskId、pageNo、pageSize请求，那么返回结果中的count值是当页的外呼记录条数，非该任务的全部外呼记录数量。2. 查询时间范围：近45天。3. jobId字段，Blu系统用于拆分名单、分批调度等内部逻辑，甲方客户可忽略，不用关注此字段。
拨打结果查询接口响应示例
任务结果查询成功
{
"code":2000,
"message":"success",
"count":1,
"data":[{
"taskId":66547748,
"callId":123654,
"jobId":890100048,
"userId":1208048,
"phone":"0159***0188",
"recordUrl":"https://bluapi.shanghu.ai/download/v1/getDownloadUrl/FCAGKR4SUAFP2MMOZA3JVENTL4XCO5GTIJ4YSKX=",
"name":"Anoji Mohoo",
"status":2,
"code":"PTP"
"desc":"Promised to payback"，
"strategyId":2,
"botId":123,
"startTime":"2024-01-01 13:00:00",
"answerTime":"2024-01-01 13:00:10",
"endTime":"2024-01-01 13:00:50",
"duration":40,
"extVars":"{}"
}]
}
任务查询异常 —— 任务不存在
{
"code":404,
"message":"task not found",
}
任务查询异常 —— 内部错误
{
"code":500,
"message":"error message",
}
拨打结果查询接口响应参数
| 参数名 | 类型 | 描述 | 参数说明 |
|---|---|---|---|
| code | Integer | 响应码 | 2000 查询成功 404 任务不存在 500 内部错误 |
| message | String | 响应说明 | 响应码对应的说明信息 |
| count | Long | 处理总数 | 通话数量 |
| data | JsonArray | 详细信息 | 呼叫结果的详细列表，详见下表说明 |
data字段说明
| 参数名 | 类型 | 描述 | 参数说明 |
|---|---|---|---|
| taskId | Long | 任务ID | 请求对应的任务id，一个任务的唯一标识 |
| jobId | Long | 呼叫批次 | 呼叫批次id，一个任务内可能有多个批次id |
| callId | Long | 呼叫标识 | 单次呼叫的唯一标识id，一个批次内可能会有多个callid |
| userId | Long | 自传用户id | 调用方传入的userid，回调时透传 |
| strategyId | Long | 自传策略ID | 调用方传入的strategy，回调时透传 |
| botId | Long | 机器人编号 | nlp平台配置的机器人ID，一个策略下可能会关联多个机器人 |
| name | String | 自传用户姓名 | 调用方传入的name，回调时透传 |
| phone | String | 自传用户手机号码 | 调用方传入的phone，回调时透传 |
| recordUrl | String | 通话录音Url | （仅接通的有值）通过此url获取这通对话的录音文件下载地址，下载地址有效期是自拨打日起30天。录音文件格式是.wav |
| status | Integer | 呼叫状态 | 0：等待拨打 1：拨打中 -1：系统异常 2：已接通 3：线路故障 -3：呼叫超时 4：非电话号码 -4：任务取消 5：任务取消(命中拨打前验证) 7：任务取消(错误名单) 8：任务取消(禁播时间) -2：未接通 -200：未接通（响铃） -201：未接通（用户忙） -202：未接通（关机） -203：未接通（空号） -204：未接通（停机） -205：未接通（静音） -206：未接通（不在服务区） -207：未接通（号码未激活） -208：未接通（语音信箱） -209：未接通（响铃带彩铃） -210:未接通-商户号码(音乐) |
| startTime | timestamp | 开始时间 | 呼叫开始时间： 格式 yyyy-MM-dd HH:mm:ss |
| answerTime | timestamp | 接通时间 | 未接通则为空： 格式 yyyy-MM-dd HH:mm:ss |
| endTime | timestamp | 结束时间 | 呼叫结束时间： 格式 yyyy-MM-dd HH:mm:ss |
| duration | Integer | 通话时长 | 单位为秒 |
| code | String | 结论编码 | 可参考文末编码表 |
| desc | String | 结论描述 | code描述 |
| extVars | String | 透传参数 | 用户随路数据返回 |
拨打结果回调接口
根据Blu商户上配置的甲方客户回调地址（联系Blu产品配置），Blu系统外呼任务执⾏成功后，会请求该回调接⼝，返回拨打结果。
说明：
- 一个Blu商户上只能配置一个回调地址；
- 拨打结果按单条数据回调；
- Blu发起回调请求，客户侧响应 http status = 200，Blu判定回调成功；
- 回调失败的重试机制：每5分钟重试1次，最多重试5次。
#####拨打结果回调接口请求报文样例
POST 商户配置URL
Content-type:application/json;charset=utf-8
其他商户自定义Headers
拨打结果回调接口输入参数说明
| 参数名 | 类型 | 必须 | 参数说明 |
|---|---|---|---|
| taskId | Long | Y | 任务id（一个任务的唯一标识） |
| jobId | Long | Y | 批次id（一个任务内可能会有多个不同jobid） |
| count | Long | Y | 通话数量 |
| data | JsonArray | Y | 呼叫结果的详细列表，详见下表说明 |
说明：jobId字段，Blu系统用于拆分名单、分批调度等内部逻辑，排查问题时使用，甲方客户不用特意关注此字段。
拨打结果回调接口data字段说明
| 参数名 | 类型 | 描述 | 参数说明 |
|---|---|---|---|
| taskId | Long | 任务ID | 请求对应的任务id，一个任务的唯一标识 |
| jobId | Long | 呼叫批次 | 呼叫批次id，一个任务内可能有多个批次id |
| callId | Long | 呼叫标识 | 单次呼叫的唯一标识id，一个批次内可能会有多个callid |
| userId | Long | 自传用户id | 调用方传入的userid，回调时透传 |
| strategyId | Long | 自传策略ID | 调用方传入的strategy，回调时透传 |
| botId | Long | 机器人编号 | nlp平台配置的机器人ID，一个策略下可能会关联多个机器人 |
| name | String | 自传用户姓名 | 调用方传入的name，回调时透传 |
| phone | String | 自传用户手机号码 | 调用方传入的phone，回调时透传 |
| recordUrl | String | 通话录音Url | （仅接通的有值）通过此url获取这通对话的录音文件下载地址，下载地址有效期是自拨打日起30天。录音文件格式是.wav |
| status | Integer | 呼叫状态 | -1：系统异常 2：已接通 3：线路故障 -3：呼叫超时 4：非电话号码 -4：任务取消 5：任务取消(命中拨打前验证) 7：任务取消(错误名单) 8：任务取消(禁播时间) -2：未接通 -200：未接通（响铃） -201：未接通（用户忙） -202：未接通（关机） -203：未接通（空号） -204：未接通（停机） -205：未接通（静音） -206：未接通（不在服务区） -207：未接通（号码未激活） -208：未接通（语音信箱） -209：未接通（响铃带彩铃） -210：未接通-商户号码(音乐) |
| startTime | timestamp | 开始时间 | 呼叫开始时间： 格式 yyyy-MM-dd HH:mm:ss |
| answerTime | timestamp | 接通时间 | 未接通则为空： 格式 yyyy-MM-dd HH:mm:ss |
| endTime | timestamp | 结束时间 | 呼叫结束时间： 格式 yyyy-MM-dd HH:mm:ss |
| duration | Integer | 通话时长 | 单位为秒 |
| code | String | 结论编码 | 可参考文末编码表 |
| desc | String | 结论描述 | code描述 |
| extVars | String | 透传参数 | 用户随路数据返回 |
回调结果样例
{
"count": 1,
"data": [
{
"answerTime": "2024-05-11 12:00:40",
"botId": 644,
"callId": 101855207,
"code": "Unrecognized",
"desc": "Unrecognized",
"duration": 51,
"endTime": "2024-05-11 12:01:31",
"extVars": "{\"round\":0,\"orderId\":\"1052240506000001609\",\"strategyId\":\"569\",\"lastRound\":false}",
"jobId": 3489938,
"name": "zulma elena",
"phone": "916632031",
"recordUrl": "https://bluapi.shanghu.ai/download/v1/getDownloadUrl/FCAGKR4SUAFP2MMOZA3JVENTL4XCO5GTIJ4YSKY=",
"startTime": "2024-05-11 12:00:30",
"status": 2,
"strategyId": 569,
"taskId": 1604074,
"userId": 916632031
}
],
"finishTime": "2024-05-11 21:30:00",
"jobId": 3489938,
"status": 4,
"taskId": 1604074
}
####附件：通话结论字典
注意：机器人通话结论可根据业务场景定制，详情请与运营联系，以下仅供参考。
机器人沟通结论字典1
| code响应码 | Desc说明 |
|---|---|
| LMS | 语音信箱 |
| Busy | 用户正忙 |
| AP | 已还款 |
| HPTP | 承诺还款无明确时间 |
| NOST | 无法达成协议 |
| NotOneself | 非本人 |
| CPL | 投诉倾向 |
| unknown | 未知意图 |
| undfined | 未定义（系统内置） |
机器人沟通结论字典2
| code响应码 | Desc说明 |
|---|---|
| Voicemail | 语音信箱 |
| Willing | 愿意做联系人 |
| Unwilling | 不愿意做联系人 |
| Donotknow | 不认识客户 |
| Busy | 用户正忙 |
| Whichcompany | 询问公司、什么公司 |
| Complan | 投诉、骂人、不要再打了 |
| Undecided | 未知意图 |
| Unconnected | 未接通 |
| Taskcancel | 任务取消 |
#####空停检测结论字段
| code响应码 | Desc说明 |
|---|---|
| D00 | 响铃 |
| D01 | 忙音 |
| D02 | 关机 |
| D03 | 空号 |
| D04 | 停机 |
| D05 | 静音 |
| D06 | 无法连接 |
| D07 | 未激活 |
| D08 | 待转接（指语音信箱） |
| D09 | 响铃且带彩铃 |
| D10 | 商户号码(音乐) |
| D90 | 未识别 |
| D91 | 暂时无法接通 |
| D99 | 已接通 |
| NAN | 未知结果 |
#####特殊结论字典
| code响应码 | Desc说明 |
|---|---|
| ROBOTERROR | 机器人编号不正确 |
| STERROR | 策略值错误 |
| OVERERROR | 未给挂机指令 |
| LICERROR | 授权错误 |
Modified at 2025-01-10 05:53:14