隐号通话对接—流程图

开发者账号

注册或者登录开发者账号流程说明请参考登录注册>>

创建应用及申请上线

创建应用及申请上线流程说明请参考创建应用及申请上线>>

资质认证

申请上线应用之前需完成资质认证，具体认证流程请参考账号认证>>

上传隐号通话铃声（可选）

1.上传隐号通话铃声—语音库管理

点击【开发者控制台> 隐号通话产品管理】选择语音库管理模块，点击“添加语音”按钮。

2.上传隐号通话铃声—上传铃声

选择要上传的语音文件，点击上传，完成，等待后台审核。

接口对接

注意：为了确保数据隐私和安全， REST API须通过HTTPS方式请求（查询子账号信息接口除外）

URL格式

https://api.ucpaas.com/{version}/Accounts/{accountSid}/{function}/{operation}?sig={SigParameter}

URL参数属性说明

属性		说明
version		云之讯REST API版本号，当前版本号为：2014-06-30
Accounts		此参数为默认固定值
accountSid		注册云之讯官网，在控制台中即可获取此参数
function		业务功能
operation		业务操作，业务功能的各类具体操作分支
SigParameter		请求URL必须带有此参数

HTTP标准包头字段(必填)

属性		说明
Accept		客户端响应接收数据格式：application/json
Content-Type		类型：application/json;charset=utf-8
Authorization		验证信息
Content-Length		包体长度

关键点

SigParameter是REST API 验证参数 
URL后必须带有sig参数，sig= MD5（账户Id + 账户授权令牌 + 时间戳），共32位(注:转成大写)
使用MD5加密（账户Id + 账户授权令牌 + 时间戳），共32位 
时间戳是当前系统时间（24小时制），格式“yyyyMMddHHmmss”。时间戳有效时间为50分钟。
Authorization是包头验证信息 
使用Base64编码（账户Id + 冒号 + 时间戳） 
冒号为英文冒号 
时间戳是当前系统时间（24小时制），格式“yyyyMMddHHmmss”，需与SigParameter中时间戳相同

1.隐号通话接口对接—双向绑定号码同步接口

双向绑定号码同步请求路径
https://api.ucpaas.com/{version}/Accounts/{accountSid}/safetyCalls/applyNumber?sig={SigParameter}

请求参数说明

参数名	要求	备注
appId	必选	创建应用时系统分配的唯一标示，在“应用列表”中可以查询。
caller	必选	主叫号码(必须为11位手机号，号码前加0086，如008613631686024)
callee	必选	规则同caller
callerRingName	可选	主叫呼入时播放IVR语音文件名
calleeRingName	可选	被叫呼入时播放IVR语音文件名
dstVirtualNum	必选	分配的直呼虚拟中间保护号码规则为0086+区号首位0+号码
bindId	必选	绑定id，客户方平台保证唯一
maxAge	必选	主被叫+虚拟保护号码允许合作方最大cache存储时间(单位秒)
cityId	必选	城市id
requestId	可选	字符串最大长度不超过128字节，该requestId在后面话单和录音URL推送中原样带回
record	可选	是否录音，0表示不录音，1表示录音。默认为不录音
maxAllowTime	可选	允许最大通话时间单位分钟，不填默认为10分钟
statusUrl	可选	状态回调通知地址，正式环境可以配置默认推送地址
hangupUrl	可选	话单推送地址，不填推到默认协商地址
recordUrl	可选	录单URL回调通知地址，不填推到默认协商地址

响应参数说明

参数名	要求	备注
appId	必选	创建应用时系统分配的唯一标示，在“应用列表”中可以查询。
caller	必选	主叫号码
callee	必选	被叫号码
dstVirtualNum	必选	用户指定分配的直呼虚拟中间保护号码规则为0086+区号首位0+号码
bindId	必选	分配唯一针对中间号码与主被叫号码的绑定Id

请求包体

Encoding: UTF-8
Http-Method: POST

包头

Headers: 
{Accept=[application/json], 
accept-encoding=[gzip,deflate], 
connection=[Keep-Alive], 
Content-Length=[316], 
content-type=[application/json;charset=UTF-8], 
host=[127.0.0.1],
Authorization:ZTAzYmM5MTA2YzZlZDBlYWViZmNlOGMzNjhmZGNkNDg6MjAxNDA2MjMxODQ1MjM=

包体

json 请求示例

{
"hangupUrl": "",
"caller": "008618612341234",
"appId": "7df01234567841ed816564bb12345678",
"callerRingName": "1124",
"bindId": “7df0123456ipoopujk7841ed816564bb12345678”,
"requestId": "sel-define follow your heart and rules",
"calleeDisplayNum": "00861054890813",
“maxAge”: “600”,
“record”: “0”,
“maxAllowTime”: “10”,
“dstVirtualNum”: “00861054890813”,
“calleeRingName”: “1142”,
“statusUrl”: “”,
“callee”: “008613611133396”,
“recordUrl”: “”
“cityId”:”008610”
}

正确响应包体

Response-Code: 200
Content-Type: application/json;charset=utf-8
Headers: {Content-Type=[application/json;charset=utf-8], Content-Length=[163], Date=[Wed, 15 Jun 2016 09:13:58 GMT]}
Payload: {"caller":"18612341234","appId":"7df01234567841ed816564bb12345678","bindId":"7df0123456ipoopujk7841ed816564bb12345678","dstVirtualNum":"0086201000123","callee":"13611133396"}

错误响应包体

Response-Code: 200
Content-Type: application/json;charset=utf-8
Headers: {Content-Type=[application/json;charset=utf-8], Content-Length=[22], Date=[Wed, 15 Jun 2016 09:21:54 GMT]}
Payload: {"errorCode":"102102"}

2.隐号通话接口对接—双向绑定号码申请接口

双向绑定号码申请路径
https://api.ucpaas.com/{version}/Accounts/{accountSid}/safetyCalls/allocNumber?sig={SigParameter}

请求参数说明

参数名	要求	备注
appId	必选	创建应用时系统分配的唯一标示，在“应用列表”中可以查询。
caller	必选	主叫号码(必须为11位手机号，号码前加0086，如008613631686024)
callee	必选	规则同caller
callerRingName	可选	主叫呼入时播放IVR语音文件名
calleeRingName	可选	被叫呼入时播放IVR语音文件名
maxAge	必选	主被叫+虚拟保护号码允许合作方最大cache存储时间(单位秒)
cityId	必选	城市id
requestId	可选	字符串最大长度不超过128字节，该requestId在后面话单和录音URL推送中原样带回
record	可选	是否录音，0表示不录音，1表示录音。默认为不录音
maxAllowTime	可选	允许最大通话时间单位分钟，不填默认为10分钟
statusUrl	可选	状态回调通知地址，正式环境可以配置默认推送地址
hangupUrl	可选	话单推送地址，不填推到默认协商地址
recordUrl	可选	录单URL回调通知地址，不填推到默认协商地址

响应参数说明

参数名	要求	备注
appId	必选	创建应用时系统分配的唯一标示，在“应用列表”中可以查询。
caller	必选	主叫号码(必须为11位手机号，号码前加0086，如008613631686024)
callee	必选	规则同caller
dstVirtualNum	必选	分配的直呼虚拟中间保护号码
bindId	必选	分配唯一针对中间号码与主被叫号码的唯一绑定Id

请求包体

Encoding: UTF-8
Http-Method: POST

包头

Headers: 
{Accept=[application/json], 
accept-encoding=[gzip,deflate], 
connection=[Keep-Alive], 
Content-Length=[316], 
content-type=[application/json;charset=UTF-8], 
host=[127.0.0.1],
Authorization:ZTAzYmM5MTA2YzZlZDBlYWViZmNlOGMzNjhmZGNkNDg6MjAxNDA2MjMxODQ1MjM=

包体

json 请求示例

{
“hangupUrl”: “”,
“caller”: “18612341234”,
“appId”: “7df01234567841ed816564bb12345678”,
“callerRingName”: “1124”,
“requestId”: “111111”,
“calleeDisplayNum”: “00862068714329”,
“maxAge”: “600”,
“record”: “0”,
“maxAllowTime”: “10”,
“calleeRingName”: “1142”,
“statusUrl”: “”,
“callee”: “008613611133396”,
“recordUrl”: “”
“cityId”:”008620”
}

正确响应包体

Response-Code: 200
Content-Type: application/json;charset=utf-8
Headers: {Content-Type=[application/json;charset=utf-8], Content-Length=[163], Date=[Wed, 15 Jun 2016 09:13:58 GMT]}
Payload: {"caller":"18612341234","appId":"7df01234567841ed816564bb12345678","bindId":"7df0123456784ikyui1ed816564bb12345678","dstVirtualNum":"0086201000123","callee":"13611133396"}

错误响应包体

Response-Code: 200
Content-Type: application/json;charset=utf-8
Headers: {Content-Type=[application/json;charset=utf-8], Content-Length=[22], Date=[Wed, 15 Jun 2016 09:21:54 GMT]}
Payload: {"errorCode":"102102"}

3.隐号通话接口对接—双向绑定关系解除接口

删除双方号码绑定关系路径
https://api.ucpaas.com/{version}/Accounts/{accountSid}/safetyCalls/freeNumber?sig={SigParameter}

请求参数说明

参数名	要求	备注
appId	必选	创建应用时系统分配的唯一标示，在“应用列表”中可以查询。
bindId	必选	双方号码+中间号绑定ID，该ID全局唯一
cityId	必选	城市Id格式为 0086+去零区号

请求包体

Encoding: UTF-8
Http-Method: POST

包头

Headers: 
{Accept=[application/json], 
accept-encoding=[gzip,deflate], 
connection=[Keep-Alive], 
Content-Length=[316], 
content-type=[application/json;charset=UTF-8], 
host=[127.0.0.1],
Authorization:ZTAzYmM5MTA2YzZlZDBlYWViZmNlOGMzNjhmZGNkNDg6MjAxNDA2MjMxODQ1MjM=

包体

json 包体

{
	“appId”: “1234b71f7c274b0782173a04509b1234”,
	"bindId": “7df0123456784ikyui1ed816564bb12345678”,
	"cityId": "008620",
}

正确响应包体

Response-Code: 200
Content-Type: application/json;charset=utf-8
Headers: {Content-Type=[application/json;charset=utf-8], Content-Length=[22], Date=[Wed, 15 Jun 2016 09:28:39 GMT]}
Payload: {"errorCode":"000000"}

错误响应包体

Response-Code: 200
Content-Type: application/json;charset=utf-8
Headers: {Content-Type=[application/json;charset=utf-8], Content-Length=[22], Date=[Wed, 15 Jun 2016 09:24:15 GMT]}
Payload: {"errorCode":"104127"}

4.隐号通话接口对接—实时绑定并发数查询接口

获取城市并发数路径
https://api.ucpaas.com/{version}/Accounts/{accountSid}/safetyCalls/getConcurrent?sig={SigParameter}

请求包体

Encoding: UTF-8
Http-Method: POST

包头

Headers: 
{Accept=[application/json], 
accept-encoding=[gzip,deflate], 
connection=[Keep-Alive], 
Content-Length=[2], 
content-type=[application/json;charset=UTF-8], 
Authorization:ZTAzYmM5MTA2YzZlZDBlYWViZmNlOGMzNjhmZGNkNDg6MjAxNDA2MjMxODQ1MjM=

包体

{"appId":"125489wslfjlsjfklsjfljdslfjkf756962eaefa0",” cityId”:”0086755”}

正确响应包体

Response-Code: 200
Content-Type: application/json;charset=utf-8
Headers: {Content-Type=[application/json;charset=utf-8], Content-Length=[39], Date=[Wed, 15 Jun 2016 09:33:16 GMT]}
Payload: {"total":"0","008610":"0","008620":"0"}

错误响应包体

Response-Code: 200
Content-Type: application/json;charset=utf-8
Headers: {Content-Type=[application/json;charset=utf-8], Content-Length=[22], Date=[Wed, 15 Jun 2016 09:35:22 GMT]}
Payload: {"errorCode":"100007"}

5.隐号通话接口对接—通话状态回调接口

通话状态回调路径
可通过接口传参给定URL地址或者采用配置默认URL

请求参数说明

参数名	要求	备注
appId	必选	平台分配
callId	必选	点击通话请求响应中返回的callId
requestId	必选	点击通话请求时请求携带的requestId，原样返回
caller	必选	主叫号码
dstVirtualNum	必选	主叫通讯录直拨虚拟保护号码
callee	必选	被叫号码
userFlag	必选	该路通话中用于区分状态属于主叫/被叫 caller：主叫 callee：被叫，非绑定关系中的主被
callStatus	必选	invite：发起呼叫 ringing：响铃 answered：接听 refused：拒绝 disconnected：正常挂机 failed：呼叫异常
errorCode	可选	sip响应码
timeStamp	必选	状态发生的unix时间戳
bindId	必选	分配唯一针对中间号码与主被叫号码的绑定Id
calleeDisplayNum	可选	本次呼叫中被叫所显示号码

响应参数说明

参数名		要求	备注
retcode		必选	返回错误码，0：成功非0：失败
reason		必选	原因描述

请求包体

Encoding: UTF-8
Http-Method: POST

包头

Headers: 
{Accept=[application/json], 
Content-Length=[316], 
content-type=[application/json;charset=UTF-8], 
host=[127.0.0.1]}

包体

json 包体

{
"appId":"123456",
"callId":"fc84cc206c2d6b86af5fe9f37d4b13c3",
"requestId":"888F1ZXNzc3QyMjg5EIKABBjzjue5BSIkNTY4ODM4MzctN",
"caller":"008618503073759",
"dstVirtualNum":"008675566616484",
"callee":"008613828772876",
"userFlag":"caller",
"callStatus":"invite",
"errorCode":0,
"timeStamp":"1470620220",
"bindId":"9999137-4ea5-43b7-9b49-5d4b95225144-5d4b95225166",
"calleeDisplayNum":"008613828772876",
}

响应包体

Response-Code: 200
Content-Type: application/json;charset=utf-8
Headers: {Content-Type=[application/json;charset=utf-8], Content-Length=[163], Date=[Wed, 15 Jun 2016 09:13:58 GMT]}
Payload: {"retcode":0,"reason":"OK“}

6.隐号通话接口对接—话单回调接口

话单回调请求地址 可通过接口传参给定URL地址或者采用配置默认URL

请求参数说明

参数名	要求	备注
appId	必选	应用唯一标识
callId	必选	通话唯一标识Id
requestId	必选	接口传入唯一Id
caller	必选	主叫号码
callee	必选	主叫通讯录直拨虚拟保护号码
dstVirtualNum	必选	虚拟保护号码即中间号码
callCenterAcceptTime	必选	虚拟保护号码平台收到呼叫时间
startDstCallTime	必选	被叫呼叫开始时间
startDstRingTime	可选	被叫响铃开始时间
dstAcceptTime	必选	被叫接听时间
endCallTime	必选	用户挂机通话结束时间
callEndStatus	必选	通话最后状态
		0：未知状态
		1：正常通话
		2：查询呼叫转移被叫号异常
		3：呼叫转移被叫未接通
		4：呼叫转移被叫未接听
callerDuration	必选	主叫接通虚拟保护号码到通话结束通话时间
calleeDuration	必选	呼叫转接被叫接通收到200ok到通话结束通话时间
bindId	必选	绑定id，客户方平台保证唯一
calleeDisplayNum	可选	本次呼叫中被叫所显示号码

响应参数说明

参数名		要求	备注
retcode		必选	返回错误码，0：成功非0：失败
reason		必选	原因描述

请求包体

Encoding: UTF-8
Http-Method: POST

包头

Headers: 
{Accept=[application/json], 
Content-Length=[316], 
content-type=[application/json;charset=UTF-8], 
host=[127.0.0.1]}

包体

json

{
"appId":"123456",
"callId":"fc84cc206c2d6b86af5fe9f37d4b13c3",
"requestId":"888F1ZXNzc3QyMjg5EIKABBjzjue5BSIkNTY4ODM4MzctN",
"caller":"008618503073759",
"callee":"008613828772876",
"dstVirtualNum":"008675566616484",
"callCenterAcceptTime":"1470620220",
"startDstCallTime":"1470620220",
"startDstRingTime":"1470620220",
"dstAcceptTime":"1470620220",
"endCallTime":"1470620222",
"callerDuration":"2",
"calleeDuration":"2",
"callEndStatus":"1",
"bindId":"9999137-4ea5-43b7-9b49-5d4b95225144-5d4b95225166",
"calleeDisplayNum":"008613828772876"
}

响应包体

Response-Code: 200
Content-Type: application/json;charset=utf-8
Headers: {Content-Type=[application/json;charset=utf-8], Content-Length=[163], Date=[Wed, 15 Jun 2016 09:13:58 GMT]}
Payload: {"retcode":0,"reason":"OK"}

7.隐号通话接口对接—录音回调接口

录音回调请求地址
可通过接口传参给定URL地址或者采用配置默认URL

请求参数说明

参数名	要求	备注
appId	必选	应用唯一标识
callId	必选	通话唯一标识Id
requestId	必选	接口传入唯一Id
caller	必选	主叫号码
callee	必选	被叫号码
dstVirtualNum	必选	虚拟保护号码即中间号码
recordUrl	必选	录音下载URL
bindId	必选	绑定Id, 客户方平台保证唯一
calleeDisplayNum	可选	本次呼叫中被叫所显示号码

响应参数说明

参数名		要求	备注
retcode		必选	返回错误码，0：成功非0：失败
reason		必选	原因描述

请求包体：

Encoding: UTF-8
Http-Method: POST

包头：

Headers: 
{Accept=[application/json], 
Content-Length=[316], 
content-type=[application/json;charset=UTF-8], 
host=[127.0.0.1]}

json 包体

{
"appId":"123456",
"callId":"fc84cc206c2d6b86af5fe9f37d4b13c3",
"requestId":"888F1ZXNzc3QyMjg5EIKABBjzjue5BSIkNTY4ODM4MzctN",
"caller":"008618503073759",
"callee":"008613828772876",
"dstVirtualNum":"008675566616484",
"recordUrl":"http://voiceproxy.oss-cn-beijing.aliyuncs.com/qq.proxy/20160808/7df0153d055841ed816564bb66aca62c_fc84cc206c2d6b86af5fe9f37d4b13c3_20160808.mp3",
"bindId":"9999137-4ea5-43b7-9b49-5d4b95225144-5d4b95225166",
"calleeDisplayNum":"008613828772876"
}

响应包体：

Response-Code: 200
Content-Type: application/json;charset=utf-8
Headers: {Content-Type=[application/json;charset=utf-8], Content-Length=[163], Date=[Wed, 15 Jun 2016 09:13:58 GMT]}
Payload: {"retcode":0,"reason":"OK"}

8.附录—常用链接

Demo下载连接
官网提供java php c# phthon 等语音demo，第三方开发者提供了golang、nodejs等语音的demo 可以参考调用,下载地址请点击>>

9.官网接口文档

附录—常见问题

接口错误码说明

 http://docs.ucpaas.com/doku.php?id=rest_error

调用接口返回100699 系统内部错误

 a.查看接口参数sig是否拼写正确  sig= md5(账户Id + 账户授权令牌 + 时间戳)共32位， md5加密后转大写
 b.查看接口参数Authorization是否拼写正确 Authorization=base64(账户Id +冒号+ 时间戳) 时间戳是当前系统时间（24小时制） yyyyMMddHHmmss

调用接口返回100005 访问ip不合法

 创建应用时，基础配置中的服务器白名单清空下，如果配置了服务器白名单调用接口必须在白名单上调用，否则就会报此错。

目录

隐号通话对接—流程图

开发者账号

创建应用及申请上线

资质认证

上传隐号通话铃声（可选）

1.上传隐号通话铃声—语音库管理

2.上传隐号通话铃声—上传铃声

接口对接

1.隐号通话接口对接—双向绑定号码同步接口

2.隐号通话接口对接—双向绑定号码申请接口

3.隐号通话接口对接—双向绑定关系解除接口

4.隐号通话接口对接—实时绑定并发数查询接口

5.隐号通话接口对接—通话状态回调接口

6.隐号通话接口对接—话单回调接口

7.隐号通话接口对接—录音回调接口

8.附录—常用链接

9.官网接口文档

附录—常见问题