注意,webcall接口v2的使用需要进行接口鉴权

1.接口简介

第三方系统通过发送HTTP POST请求来发起外呼将被叫呼通后送入指定的流程中。在这个流程中,用户可以实现语音播报、接入坐席、双向回呼、隐私通话、批量外呼等一系列功能。

功能示意图:

2 接口请求

  • HTTP请求方式:POST

  • 请求url:{HOST}/v20160818/webCall/webCall/{ACCOUNTID}?sig={SIG}

  • 请求时请将{HOST}换成对接数据查询中获取到的请求域名,{ACCOUNTID}替换为账户编号,{SIG}是根据鉴权规则生成的,请看鉴权文档,查看具体的生成规则

  • 鉴权方式:接口鉴权

  • 请求频次限制:200次/分钟

3.接口参数如下:(红色为必传参数)

参数名 描述
Action Webcall(固定不变)
ServiceNo 虚拟服务号,由七陌技术提供,每种对应一个固定的服务号,默认都是0102527开头的号码
Exten 被叫电话号码(双向回呼场景时Exten为主叫号码,自定义参数中传的phoneNum是被叫号码)
WebCallType 调用WebCall的接口类型(同步异步)当传此值时采用异步的接口,例:WebCallType=asynchronous(不填为同步接口)
CallBackUrl 调用异步时需要传参,回调的地址,例:CallBackUrl=http://www.baidu.com/
CallBackType 回调的方式get或者post,例:CallBackType=post(不填默认为get) 注意:异步回调post方式,推送的参数是application/x-www-form-urlencoded格式
Variable 和七陌技术协商的自定义变量通过此字段以键值对方式传递,多个变量之间用逗号分隔开,如var1:value1,var2:value2。常见业务场景:语音播报场景下可传:Variable=text:"张先生,你好",七陌即可直接播报text对应内容,隐私通话、双向回拨场景下可传Variable=phoneNum:"183xxxxxxxx",七陌可直接把phoneNum的值当做被叫号码去拨打
ActionID 本次调用接口的唯一标示,response中会返回此字段。在对外事件推送中会推送次字段,但是参数名为:WebcallActionID。该参数不可传重复值,必须唯一
Timeout 本字段是用来控制Exten中传入号码的被叫时间的,接口呼叫被叫的时长单位为秒。值的范围为20至60,此时长包含接口调用后被叫开始振铃的这段时间。如果被叫有响应,则接口立即返回。如被叫一直不接,直到超时时间接口才返回。(本字段可不传,默认超时时长为20秒)
MaxCallTime (此字段只针对双向回呼场景)该字段用来在双向回呼场景中设置最大通话时长。从双方接通开始计时,到时间自动掐断。单位为秒。(本字段非必填,需要控制通话时长时才传。例如:MaxCallTime:60)
ChatingIvrPrompt (此字段只针对双向回呼场景)对双向回呼通话过程中,给双方播放提示IVR。一般配合MaxCallTime字段来用,提示通话双方还剩余多久的通话时长。
字段值实例:秒-服务号-变量
OutShow 指定第一被叫(Exten)的外显号码。注意:此号码必须为账号线路配置里的真实号码。最新的通话服务器才支持该功能,如果需使用此功能可提前找群内对接技术确认。
注意事项:

a.定时提醒可以配置多次提醒,每次之间用英文分号分隔。

b.每次提醒变量可以传多个,多个变量用英文逗号分隔,变量举例var1:value1,var2:value2……。IVR流程中无需播报变量则变量可不传。

c.在七陌系统中,一个IVR流程的起点为服务号,播放IVR流程之前请提前在通话配置中添加好服务号流程,最好请七陌工作人员协助配置

d.异步回调post方式,推送的参数是application/x-www-form-urlencoded格式

真实场景举例:要求双方通话为60秒,并且在通话开始后30秒和50秒时播放提醒语音。
MaxCallTime=60&ChatingIvrPrompt=30-01056332288-notice:30;50-01056332288

4.系统返回:

同步接口返回值详解:

若接口是同步接口,response是在被叫号码做出响应后才会返回。超时时间默认为20秒(可以通过参数Timeout设置)。

接口返回的response是一个json格式字符串,包含如下字段:

参数名 说明
Command Response 值固定不变
Response WebCall 值固定不变
ActionID 随机数 与调用接口时传的ActionID相同。如果调用接口时没传ActionID,则值是Webcall+随机数。
Succeed true/false 本次接口调用是否成功。
Message 数字 a)Message:4 被叫已接听
b)Message:0或8 线路繁忙/异常(某些情况下,也可能为被叫拒接/振铃未接/占线/关机/空号)
c)Message:3 被叫拒接/振铃未接/占线/关机/空号
d)Message:5 一般情况下为余额不足,请先检查账户资费。(少数情况下可能是线路异常)

常见报错:

message返回值 含义
500 Server error 服务器错误,请联系售后
502 Account cc product not found 账号未开通云客服产品
401 PBX not found 通话服务器没找到
505 Service no can not fond 服务号没找到
416 dialoutLine didnum id disable 服务号不存在,请联系商务同事查看服务号
415 call is limit 并发限制,请联系商务同事
501 Account not found 账户编号传递错误,请检查ACCOUNTID传值是否正确
504 Service no is necessary 未查询到服务号,请检查您的传参格式

【注意】:受中国通信网络大环境影响,由于webcall业务中间经过多层路由,message的编码的含义已经没有实际意义了,可能在中间的某一层或某几层都变成了别的意义。所以只需要关注4是接听,其他是未接听即可

5.Response例子:


{"Command":"Response","Succeed":true,"Message":"4",
"ActionID":"Webcall1382293010856915711","Response":"Webcall"}  

同步接口返回值详解:

若接口是异步接口,response立即返回后,在被叫号码做出响应后会对相应接口推送(详见异步情况调用)。

接口返回的response是一个json格式字符串,包含如下字段:

参数名 说明
Command Response 值固定不变
Response WebCall 值固定不变
ActionID 随机数 与调用接口时传的ActionID相同。如果调用接口时没传ActionID,则值是Webcall+随机数。【注意ActionID必须唯一,否则会影响对外事件推送中WebcallActionID的回传
Succeed true/false 本次接口调用是否成功。
Response例子:

{"Command":"Response","Succeed":true,"ActionID":"Webcall1382293010856915711",
"Response":"Webcall"}  

异步情况调用:

接口url:http://www.baidu.com/callback
1.get请求示例: 接口示例:http://www.baidu.com/callback?actionid=Webcall1382293010856915711&Message=4
2.post请求示例: "{"actionid":"abcdefg","Message":"3"}"

参数名 说明
Message 数字 a)Message:4 被叫已接听
b)Message:0或8 线路繁忙/异常(某些情况下,也可能为被叫拒接/振铃未接/占线/关机/空号)
c)Message:3 被叫拒接/振铃未接/占线/关机/空号
d)Message:5 一般情况下为余额不足,请先检查账户资费。(少数情况下可能是线路异常)

【注意】:如果需要高并发的接口模式,请与商务同事和技术同事单独沟通。