======隐号通话对接—流程图====== {{:隐号通话:隐私通话流程图2.png|}} ======开发者账号====== 注册或者登录开发者账号流程说明请参考[[..login_singup|登录注册>>]] ======创建应用及申请上线====== 创建应用及申请上线流程说明请参考[[..creatnewapp|创建应用及申请上线>>]] =======资质认证====== 申请上线应用之前需完成资质认证，具体认证流程请参考[[..account_authentication|账号认证>>]] ======上传隐号通话铃声（可选）====== ===1.上传隐号通话铃声—语音库管理=== 点击【开发者控制台> 隐号通话产品管理】选择语音库管理模块，点击“添加语音”按钮。 {{:隐号通话:隐号通话.png|}} ===2.上传隐号通话铃声—上传铃声=== 选择要上传的语音文件，点击上传，完成，等待后台审核。 {{:隐号通话:上传语音.png|}} ======接口对接======

注意： 为了确保数据隐私和安全， 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= **包体**\\ { "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= **包体**\\ { “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= **包体**\\ { “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]} **包体**\\ { "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]} **包体**\\ { "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]} { "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.官网接口文档=== **[[..rest_api介绍及接入|接口简介和统一请求包头>>]]**\\ **[[..client管理api|申请client接口文档>>]]**\\ **[[..呼叫鉴权请求接口|呼叫鉴权回调文档>>]]**\\ **[[..呼叫建立通知接口|呼叫接通回调文档>>]]**\\ **[[..呼叫挂机计费接口|呼叫结束回调文档>>]]**\\ ======附录—常见问题====== **[[..rest_error|接口错误码说明]]** 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不合法** 创建应用时，基础配置中的服务器白名单清空下，如果配置了服务器白名单调用接口必须在白名单上调用，否则就会报此错。