MakeCall外呼发起及事件订阅服务_v1.0

约定

发行/变更日志

2021-04-20

  • 文档修订

2019-06-25

  • v1.0文档

2019-08-14

  • v1.0文档更新[重新定义了回调内容]

2019-09-03

  • v1.0文档移除了之前作废的部分文档

2019-09-09

  • 呼叫接口返回错误码新增风控相关错误码

2019-09-19

  • 呼叫查询呼叫事件日志新增queryCallId(真实呼叫ID),gRocCode(gRpc返回码),gRpcMsg(gRpc返回码说明) 字段

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
}

认证

接口认证接入

接入时平台会把一批相关参数提供给业务方，用于通过Token获取方式获取Token进行接口认证

请求Header

字段字段类型说明
Authorizationstring"Bearer " + Token[获取方式如下]

注: Bearer与Token中间有空格

Token获取方式

http://developer.icsoc.net/docs/develop/authentication/

服务地址

https://mc-api.icsoc.net

外呼接口

发起呼叫

URL

/app/calling

请求方式

POST

请求参数

{
    "proId": 1,
    "caller": "15151515115",
    "phone": "18121376785",
    "userData": {
        "extId": "19291",
        "test": "123"
    }
}

说明:

字段必填类型备注
proId是int项目id
caller否string主叫(外显)号码
phone是string被叫号码
userData否map<string,object>用户自定义数据

返回结果

{
    "proId": 1,
    "callId": "1561343110869",
    "caller": "15151515115",
    "userData": {
        "extId": "19291",
        "test": "123"
    }
}

说明:

字段类型备注
proIdint项目id
callIdstring本次呼叫标识(唯一)
callerstring主叫号码
userDatamap<string,object>用户数据回带

查询呼叫事件日志

URL

/app/info/{callId}

请求方式

POST

请求参数 无

返回结果

{
  "req": "{\"caller\":\"\",\"phone\":\"18121376785\",\"proId\":2,\"userData\":{\"extId\":\"10000\",\"test\":\"123\",\"ss\":\"jj\"},\"vccId\":\"1018\"}",
  "reqTime": 1561613313986,
  "res": "{\"msg\":\"操作成功\",\"data\":{\"pro_id\":2,\"call_id\":\"6549880975554392064\",\"caller\":\"01057624344\",\"user_data\":{\"extId\":\"10000\",\"test\":\"123\",\"ss\":\"jj\"}},\"code\":200}",
  "resTime": 1561613315866,
  "queryCallId": "6575609544704004096",
  "gRpcCode": 0,
  "gRpcMsg": "",
  "progress": [
    {
      "type": "userRing",
      "body": "{\"callId\":\"6549880975554392064\",\"type\":\"userRing\",\"result\":null,\"reason\":null,\"timestamp\":1561613321,\"userData\":{\"extId\":\"10000\",\"test\":\"123\",\"ss\":\"jj\"}}",
      "httpCode": 200,
      "errMsg": null,
      "reqTime": 1561613321325,
      "resTime": 1561613321392,
      "retry": 0
    },
    {
      "type": "userAnswer",
      "body": "{\"callId\":\"6549880975554392064\",\"type\":\"userAnswer\",\"result\":null,\"reason\":null,\"timestamp\":1561613326,\"userData\":{\"extId\":\"10000\",\"test\":\"123\",\"ss\":\"jj\"}}",
      "httpCode": 200,
      "errMsg": null,
      "reqTime": 1561613327069,
      "resTime": 1561613327137,
      "retry": 0
    },
    {
      "type": "agentRing",
      "body": "{\"callId\":\"6549880975554392064\",\"type\":\"agentRing\",\"result\":null,\"reason\":null,\"timestamp\":1561613326,\"userData\":{\"extId\":\"10000\",\"test\":\"123\",\"ss\":\"jj\"}}",
      "httpCode": 200,
      "errMsg": null,
      "reqTime": 1561613327069,
      "resTime": 1561613327137,
      "retry": 0
    },
    {
      "type": "agentHangup",
      "body": "{\"callId\":\"6549880975554392064\",\"type\":\"agentHangup\",\"result\":null,\"reason\":null,\"timestamp\":1561613326,\"userData\":{\"extId\":\"10000\",\"test\":\"123\",\"ss\":\"jj\"}}",
      "httpCode": 200,
      "errMsg": null,
      "reqTime": 1561613327069,
      "resTime": 1561613327137,
      "retry": 0
    },
    {
      "type": "userHangup",
      "body": "{\"callId\":\"6549880975554392064\",\"type\":\"userHangup\",\"result\":1,\"reason\":\"用户挂机\",\"timestamp\":1561613327,\"userData\":{\"extId\":\"10000\",\"test\":\"123\",\"ss\":\"jj\"}}",
      "httpCode": 200,
      "errMsg": null,
      "reqTime": 1561613328604,
      "resTime": 1561613328639,
      "retry": 0
    }
  ]
}

说明:

字段类型备注
reqstring发起呼叫请求体(非标准json)
reqTimeint发起呼叫请求时间
resstring发起呼叫响应体
resTimeint发起呼叫响应时间
queryCallIdstring真实呼叫ID
gRpcCodestringgRpc返回值[码表:gRpc返回码]
gRpcMsgstringgRpc返回值说明
progressarray[progressInfo]回调过程日志
progressInfo.typestring事件类型[码表:事件类型]
progressInfo.bodystring回调数据(非标准json)
progressInfo.httpCodeint回调返回http状态码(如"200")
progressInfo.errMsgstring回调错误信息(如"404 not found")
progressInfo.reqTimeint当次回调发起时间
progressInfo.resTimeint当次回调响应时间
progressInfo.retryint回调重试次数

推送服务

事件推送服务_NEW[已确认]

URL

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

认证方式

暂无

请求方式

POST

{
  "callId": "1561343110869",
  "type": "userRing",
  "timestamp": 1565679749, 
  "userData": {
      "extId": "19291",
      "test": "123"
  },
  "recordUrl": "https://file...",
  "hangupReason": 0,
  "failReason": 2,
  "startTime": 1565679749,
  "userRingTime": 1565679750,
  "userAnswerTime": 1565679751,
  "userHangupTime": 1565679752,
  "userRingDuration": 1,
  "userCallDuration": 1,
  "agentRingTime": 1565679754,
  "agentAnswerTime": 1565679755,
  "agentHangupTime": 1565679756,
  "agentRingDuration": 1,
  "agentCallDuration": 1
}

说明：

字段类型说明
callIdstring本次呼叫标识(唯一)
typestring事件类型[码表：事件类型]
timestamplong当前事件时间
userDatamap<string,object>自定义数据
recordUrlstring通话录音地址
hangupReasonint挂机原因[码表：挂机原因]
failReasonint外呼失败原因[码表：回铃识别码]
startTimelong外呼开始时间
userRingTimelong用户振铃时间
userAnswerTimelong用户接听时间
userHangupTimelong用户挂机时间
userRingDurationint用户振铃时长（单位：秒）
userCallDurationint用户接通时长（单位：秒）
agentRingTimelong坐席振铃时间
agentAnswerTimelong坐席接听时间
agentHangupTimelong坐席挂机时间
agentRingDurationint坐席振铃时长（单位：秒）
agentCallDurationint坐席接通时长（单位：秒）

事件推送服务说明_NEW

  • 时间推送中相关的字段时间，在事件产生后，逐步追加写入相应的状态时间到请求体中，没有相关参数对应值时为null
  • 事件推送保证推送按照事件生成的顺序进行推送[不保证极端情况下的有序事件]
  • 接受到推送请求后，HTTP请求响应状态为200时，认定为外呼结果推送成功，推送成功后将不会进行重试。否则，立刻重试三次[可配置]放弃
  • 事件推送失败后的每一小时，均会针对推送失败的事件进行重推

码表

事件类型[type]

值说明
callFail呼叫失败
userRing用户振铃
userAnswer用户接听
agentRing分机振铃
agentAnswer分机接听
userHangup用户挂机
agentHangup分机挂机
restartHangupcti重启挂机
asrMessage回铃识别
  • 补充说明：支持选择订阅以上事件类型对应的结果回调

挂机原因[result]

值说明
1用户挂机
2分机挂机
99系统异常挂机

回铃识别码[rdInt]

值说明
1用户忙
2无法接通
3关机
4停机
5空号
6号码错误
11呼叫限制
98无法识别

错误码

系统错误码

值说明
200操作成功
401鉴权失败
5000服务运行错误，请联系管理员
5001请求体没有包含正确的version值
5002参数校验未通过
5003服务内部异常，请重试
5004服务重启中，请稍后重试
5005服务响应超时，请稍后重试

业务错误码

值说明
200001未找到对应项目
200002gRpc故障
200003号码归属查询出错
200004非法主叫号码
200005无可用主叫号码
200006gRpc调用返回值异常
200007无空闲线路资源
210001企业不正确
210002企业过期
210006被叫号码不正确
210004主叫号码在黑名单
210012主叫号码被风控
210013主叫号码没有外呼能力
220000风控接口未返回可用主叫

gRpc返回码

值说明
-2准备呼叫中
-1gRpc调用异常
0已发起呼叫
93企业已过期
99系统重启中
Last updated on 7/28/2021 by luyongbing
← 外呼机器人NLP接口参考手册_v1.0新老报表指标映射 →