典型场景
当应用要实现语音回呼功能时，可以调用语音回呼场景API。
接口功能
主叫用户通过应用拨打被叫用户，语音通话平台呼叫主叫和被叫，使主叫和被叫能够 互相通话。
图2-1 语音回呼体验流程
语音回呼业务体验描述：
1. 用户A通过应用呼叫用户B，请求上报到SP。
2. SP调用语音回呼场景API。
4. 语音通话平台呼叫用户B的号码。
5. 用户B接听，用户A和用户B通话。
使用说明
● 前提条件
a. 已通过“应用管理”页面获取该语音回呼能力的APP_Key，APP_Secret和APP 接入地址。
b. 已通过“号码订购”页面向语音通话平台申请以下号码：
▪
若使用定制化主叫端来电显示号码，请确认已申请固话号码（displayNbr）。
▪
若需隐藏主叫号码，使用定制化被叫端来电显示号码，请确认已申请固 话号码（displayCalleeNbr）。c. 若需使用通话录音功能，请确认已向语音通话平台申请该功能。
d. 若使用个性化放音，请确认已按要求制作并通过放音文件管理页面向语音通 话平台提交放音文件，包括最后一分钟提示音（lastMinVoice），主叫提示 音（preVoice），主叫等待音（waitVoice），录音提示音
（recordHintTone），回呼提示音（callBackTone）。
e. 若需订阅呼叫状态和话单通知，请确认已通过应用管理向语音通话平台提交 呼叫状态通知URL（statusUrl）和话单通知URL（feeUrl）。若未提交，调用 接口时填写也可以。
● 注意事项 无。
● 使用限制 无。
接口类型
表2-1 接口类型说明 请求方法 POST
访问URI /rest/httpsessions/click2Call/v2.0 通信协议 HTTPS
请求参数
表2-2 请求 Headers 参数说明 参数名称 是否
必选
参数类型 说明
Content-Type 是 String 固定填写为application/json;charset=UTF-8。
参数名称 是否 必选
参数类型 说明
Authoriza
tion 是 String 固定填写为WSSE
realm="SDP",profile="UsernameToken",type="
Appkey"。
X-WSSE 是 String 取值为UsernameToken Username="APP_Key的 值", PasswordDigest="PasswordDigest的值", Nonce="随机数", Created="随机数生成时间"。
● PasswordDigest：根据PasswordDigest = Base64 (SHA256 (Nonce + Created + Password))生成。其中，Password为 APP_Secret的值。Nonce、Created、
Password直接进行字符串拼接即可，无需包含 +号和空格。
● Nonce：客户发送请求时生成的一个随机数，
长度为1~128位，可包含数字和大小写字母。
例如：66C92B11FF8A425FB8D4CCFE0ED9ED1F。
● Created：随机数生成时间。采用标准UTC格 式，例如：2018-02-12T15:30:20Z。不同编程 语言中将UTC时间戳转换为普通时间时使用的 格式不同，部分语言可参考表2-3。
表2-3 不同编程语言的时间格式
编程语言 时间格式
Java yyyy-MM-dd'T'HH:mm:ss'Z' PHP Y-m-d\TH:i:s\Z
Python %Y-%m-%dT%H:%M:%SZ C# yyyy-MM-ddTHH:mm:ssZ
Node.js toISOString().replace(/.[0-9]+\Z/, 'Z')
注：Node.js中，使用toISOString()转换后的时间格式去除毫秒后即 为本接口要求的时间格式。
表2-4 请求 Body 参数说明
参数名称 是否
必选
参数类 型
默认 值
说明
displayNbr 是 String(4
-31) 无 此字段定义主叫用户收到语音通话平台的 呼叫时，主叫用户手机终端的来电显示号 码。需提前在订购号码页面申请该号码。
号码格式（固话）：国家码+区号+固话，
与号码管理页面的“固话号码”保持一 致。
若该号码为“暂停”状态，语音通话平台 会从该应用下随机选取一个其他可用的固 话号码进行外呼。
callerNbr 是 String(4
-31) 无 此字段定义用户在SP开发的应用中，通过 语音回呼功能发起呼叫时所使用的主叫号 码。
● 手机号码格式：+{国家码}{手机号 码}。示例：+86135***0002。
● 固话格式：+{国家码}{区号}{固话号 码}，其中区号需去掉首位的0。示 例：国家码86，区号0755，固话号码 28****02，填写为+8675528****02。
displayCallee
Nbr 是 String(4
-31) 无 此字段定义被叫用户收到语音通话平台的 呼叫时，被叫用户终端的来电显示号码。
需提前在订购号码页面申请该号码。
该号码可以与displayNbr配置为同一个号 码，也可以配置为不同号码。
号码格式（固话）：国家码+区号+固话，
与号码管理页面的“固话号码”保持一 致。
若该号码为“暂停”状态，语音通话平台 会从该应用下随机选取一个其他可用的固 话号码进行外呼。
calleeNbr 是 String(4
-31) 无 此字段定义终端用户在SP开发的应用中通 过语音回呼业务发起呼叫时所拨打的被叫 号码。
号码格式：
● 手机号码格式：+{国家码}{手机号 码}。示例：+86135****0004。
● 固话格式：+{国家码}{区号}{固话号 码}，其中区号需去掉首位的0。示 例：国家码86，区号0755，固话号码 28****04，填写为+8675528****04。
参数名称 是否 必选
参数类 型
默认 值
说明
maxDuration 否 Integer 0 此字段用于设置允许单次通话进行的最长 时间，通话时间从被叫接通的时刻开始计 算。
取值范围：0~1440分钟
● 0：系统不主动结束通话，由主被叫双 方结束通话。
● 1~1440：当通话时长达到此配置值，
系统主动结束通话。
不携带时，参数值默认为0。
lastMinVoice 否 String(1
-128) 无 当maxDuration字段设置为非0时此参数 有效。
此参数用于设置最后一分钟放音提示音，
此值填写SP定制的放音文件名，例如 lastmin_voice1.wav，参数取值有以下两 种场景：
● SP无需定制个性化放音，无需配置此 参数，系统将使用默认放音文件，放 音内容为：“本次通话时长还剩1分 钟”。
● SP需要定制个性化放音，接口消息中 携带此参数，参数值携带定制的放音 文件名，请提前制作放音文件并通过 放音文件管理页面提交到语音通话平 台。
lastMinToUE 否 String
（枚 举）
both 当maxDuration字段设置为非0时此参数 有效。
此字段用于设置最后一分钟放音的播放对 象。
● toa：仅对主叫用户放音。
● tob：仅对被叫用户放音。
● both：同时给主叫和被叫用户放音。
不携带时，参数值默认为both。
playPreVoice 否 String
（枚 举）
false 此字段用于设置主叫（callerNbr）应答语 音回呼后，呼叫被叫（calleeNbr）前，
是否向主叫（callerNbr）播放提示音。
当该参数设置为true时，播放完主叫提示 音（preVoice）后才播放主叫等待音
（waitVoice）并呼叫被叫
（calleeNbr）。
● true：播放提示音。
● false：不播放提示音。
参数名称 是否 必选
参数类 型
默认 值
说明
preVoice 否 String(1
-128) 无 当playPreVoice字段设置为true时此参数 有效。
此字段用于设置主叫（callerNbr）应答语 音回呼后，呼叫被叫（calleeNbr）前向 主叫播放的提示音，此值填写放音文件 名，例如pre_voice1.wav。
● SP无需定制个性化放音文件，接口消 息中无需携带此参数，系统将使用默 认放音“正在为您转接中，请稍 后”。
● SP需要定制个性化放音文件，接口消 息中携带此参数，请提前制作放音文 件并通过放音文件管理页面提交到语 音通话平台。
waitVoice 否 String(1
-128) 无 此字段用于设置主叫应答语音回呼后的等 待音，此值填写放音文件名，例如 wait_voice1.wav。
● SP无需定制个性化放音文件，接口消 息中无需携带此参数，系统将使用默 认放音，系统边给主叫放音（循环放 音）边拨打被叫用户；被叫应答才中 止放音。
● SP需要定制个性化放音文件，接口消 息中携带此参数，请提前制作放音文 件并通过放音文件管理页面提交到语 音通话平台。
waitVoice可结合calleeMedia使用。
calleeMedia 否 String
（枚 举）
all 该参数用于指定被叫的媒体音播放方式，
参数取值范围如下：
● all：透传被叫端的所有放音。当被叫 端返回振铃音等媒体音，则终止主叫 的等待音，播放被叫的媒体音，如彩 铃音等。
● none：不透传被叫所有放音，一直播 放主叫的等待音，直到被叫应答或挂 机。
● fail：只有在被叫回失败放音时（带 reason原因值），才终止主叫的等待 音、播放被叫的失败放音。
不携带时，参数值默认为all。
参数名称 是否 必选
参数类 型
默认 值
说明
statusUrl 否 String(1
-128) 无 此参数请采用BASE64编码进行加密。
此字段用于设置SP接收状态上报的URL。
语音通话平台将业务触发过程中通话的状 态信息（包括呼出、振铃、摘机和挂机信 息）推送至此服务器，SP根据通话状态信 息确定用户状态。
URL可填写为http://IP:Port或域名，推荐 使用域名，支持http和https。且该域名对 应多个服务器，避免单点故障无法接收通 知。
URL只能由大小写字母（a-z、A-Z），数 字（0-9），中划线（-），英文冒号
（:），英文点号（.），以及英文斜杠
（/）组成，不支持其它字符。最大128字 节。
feeUrl 否 String(1
-128) 无 此参数请采用BASE64编码进行加密。
此参数用于设置SP接收话单上报的URL。
语音通话平台将业务产生的话单推送至此 服务器。
URL可填写为http://IP:Port或域名，推荐 使用域名，支持http和https。且该域名对 应多个服务器，避免单点故障无法接收话 单。
URL只能由大小写字母（a-z、A-Z），数 字（0-9），中划线（-），英文冒号
（:），英文点号（.），以及英文斜杠
（/）组成，不支持其它字符。最大128字 节。
recordFlag 否 String
（枚 举）
false 此字段设置语音回呼通话过程是否录音。
● true：开启录音，请在添加应用时开启 录音功能。
● false：不开启录音。
不携带时，参数值默认为false。
录音相关API包括“获取录音文件下载地 址API”。
参数名称 是否 必选
参数类 型
默认 值
说明
recordHintTo
ne 否 String(1
-128) 无 此字段在recordFlag为true时才有效。
此字段用于设置使用录音功能的提示音，
参数传值为指定的放音文件名，例如 recordhint_voice1.wav。
● 无需定制个性化放音时，接口消息中 无需携带此参数，此时系统可能会放 默认提示音，也可能不放，请联系华 为云客服确认。
● 需要定制个性化放音文件时，接口消 息中携带此参数，请提前制作放音文 件并通过放音文件管理页面提交到语 音通话平台。
partyTypeRe quiredInDisc onnect
否 String(
枚举) fals
e 该参数用于指定语音通话平台给开发者发 送disconnect的呼叫状态时，通知消息是 否需要携带通话主动挂机的用户类型（主 叫挂机、被叫挂机、平台挂机）。
该参数取值范围如下：
● true：需要携带
● false：不需要携带
不携带该参数时，默认值为false。
returnIdlePor
t 否 String(
枚举) fals
e 指示是否需要返回平台空闲呼叫端口数 量。
● true：需要返回
● false：不需要返回
不携带该参数时，默认值为false。
userData 否 String(1
-256) 无 此字段用于SP开发者自定义呼叫发起时，
设置用户的附属信息，应用场景可以是当 开发者想要对每一次呼叫的用户进行跟踪 时，该参数可以携带用于标识用户的信 息，如customerId123.
语音通话平台不对此参数做强制要求，如 果开发者传入此参数，语音通话平台会在 后续发给SP的通知消息中携带该参数值。
语音通话平台不对此参数做强制要求，如 果开发者传入此参数，语音通话平台会在 后续发给SP的通知消息中携带该参数值。