语音通话 VoiceCall-语音通知呼叫状态通知API:请求参数

时间：2023-11-01 16:16:04

语音通话 VoiceCall 语音通知API

请求参数

SP调用语音通知API，语音通话平台发起呼叫，给用户播放自定义的语音文件或 TTS 合成语音文件，并可进行收号，获得应答信息并反馈给SP。

注：以下流程以语音通话平台呼叫A，给A播放语音文件并收号为例。流程和接口示例仅供参考，请以实际消息为准。

表2 请求Headers参数说明
参数名称	是否必选	参数类型	说明
Content-Type	是	String	固定填写为application/json;charset=UTF-8。
Authorization	是	String	固定填写为AKSK realm="SDP",profile="UsernameToken",type="Appkey"。
X-AKSK	是	String	取值为UsernameToken Username="APP_Key的值", PasswordDigest="PasswordDigest的值", Nonce="随机数", Created="随机数生成时间"。 PasswordDigest：根据PasswordDigest = Base64(HMAC(appSecret, url+安全随机数+时间戳))生成。其中，url使用客户设置的状态推送URL，随机数需使用安全随机数。 Nonce：客户发送请求时生成的一个随机数，长度为1~128位，可包含数字和大小写字母。例如：66C92B11FF8A425FB8D4CCFE0ED9ED1F。 Created：随机数生成时间。采用标准UTC格式，例如：2018-02-12T15:30:20Z。不同编程语言中将UTC时间戳转换为普通时间时使用的格式不同，部分语言可参考表3。

表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()转换后的时间格式去除毫秒后即为本接口要求的时间格式。

表4 请求Body参数说明
参数名称	是否必选	参数类型	说明
eventType	是	String(枚举)	该参数标识API事件通知的类型。取值范围如下： callout：呼出事件 alerting：振铃事件 answer：应答事件 collectInfo：放音收号结果事件 disconnect：挂机事件
statusInfo	否	CallStatusInfo	呼叫状态事件的信息。当eventType参数为callout、alerting、answer、collectInfo、disconnect时携带。

CallStatusInfo

表5 callout：呼出事件
参数名称	是否必选	参数类型	说明
timestamp	是	String(1-128)	该呼叫事件发生时语音通话平台的UNIX时间戳。该参数取值为UTC时间（+8小时为北京时间）格式，即为“yyyy-MM-dd HH:mm:ss”。
userData	否	String(1-256)	用户附属信息，此参数的值与“语音通知API”中的"userData"参数值一致。
sessionId	是	String(1-256)	唯一指定一条通话链路的标识ID。
caller	否	String(1-32)	主叫号码。号码仅支持全局号码格式（包含国家码），比如+86138****7021。注：呼出事件的主叫号码为SP设置的来电显示号码（displayNbr）。
called	否	String(1-32)	被叫号码。号码仅支持全局号码格式（包含国家码），比如+86138****7021。注：呼出事件的被叫号码为A号码。

接口示例

POST /status HTTP/1.1Content-Length: xx {"eventType":"callout","statusInfo":{"sessionId":"1202_14260_4294967295_20190124024846@callenabler245.huaweicaas.com","timestamp":"2019-01-24 02:48:46","caller":"+86138****0022","called":"+86138****0021"}}

表6 alerting：振铃事件
参数名称	是否必选	参数类型	说明
timestamp	是	String(1-128)	该呼叫事件发生时语音通话平台的UNIX时间戳。该参数取值为UTC时间（+8小时为北京时间）格式，即为“yyyy-MM-dd HH:mm:ss”。
userData	否	String(1-256)	用户附属信息，此参数的值与“语音通知API”中的"userData"参数值一致。
sessionId	是	String(1-256)	唯一指定一条通话链路的标识ID。
caller	否	String(1-32)	主叫号码。号码仅支持全局号码格式（包含国家码），比如+86138****7021。注：振铃事件的主叫号码为SP设置的来电显示号码（displayNbr）。
called	否	String(1-32)	被叫号码。号码仅支持全局号码格式（包含国家码），比如+86138****7021。注：振铃事件的被叫号码为A号码。

接口示例

POST /status HTTP/1.1Content-Length: xx {"eventType":"alerting","statusInfo":{"sessionId":"1202_14260_4294967295_20190124024846@callenabler245.huaweicaas.com","timestamp":"2019-01-24 02:48:47","caller":"+86138****0022","called":"+86138****0021"}}

表7 answer：应答事件
参数名称	是否必选	参数类型	说明
timestamp	是	String(1-128)	该呼叫事件发生时语音通话平台的UNIX时间戳。该参数取值为UTC时间（+8小时为北京时间）格式，即为“yyyy-MM-dd HH:mm:ss”。
userData	否	String(1-256)	用户附属信息，此参数的值与“语音通知API”中的"userData"参数值一致。
sessionId	是	String(1-256)	唯一指定一条通话链路的标识ID。
caller	否	String(1-32)	主叫号码。号码仅支持全局号码格式（包含国家码），比如+86138****7021。注：应答事件的主叫号码为SP设置的来电显示号码（displayNbr）。
called	否	String(1-32)	被叫号码。号码仅支持全局号码格式（包含国家码），比如+86138****7021。注：应答事件的被叫号码为A号码。

接口示例

POST /status HTTP/1.1Content-Length: xx {"eventType":"answer","statusInfo":{"sessionId":"1202_14260_4294967295_20190124024846@callenabler245.huaweicaas.com","timestamp":"2019-01-24 02:49:12","caller":"+86138****0022","called":"+86138****0021"}}

表8 collectInfo：放音收号结果事件
参数名称	是否必选	参数类型	说明
timestamp	是	String(1-128)	该呼叫事件发生时语音通话平台的UNIX时间戳。该参数取值为UTC时间（+8小时为北京时间）格式，即为“yyyy-MM-dd HH:mm:ss”。
sessionId	是	String(1-256)	唯一指定一条通话链路的标识ID。
digitInfo	否	String(1-64)	语音通知场景中携带收号的结果。（即用户输入的数字）

接口示例

POST /status HTTP/1.1Content-Length: xx {"eventType":"collectInfo","statusInfo":{"sessionId":"1202_14260_4294967295_20190124024846@callenabler245.huaweicaas.com","timestamp":"2019-01-24 02:49:12","digitInfo":"02"}}

表9 disconnect：挂机事件
参数名称	是否必选	参数类型	说明
timestamp	是	String(1-128)	该呼叫事件发生时语音通话平台的UNIX时间戳。该参数取值为UTC时间（+8小时为北京时间）格式，即为“yyyy-MM-dd HH:mm:ss”。
userData	否	String(1-256)	用户附属信息，此参数的值与“语音通知API”中的"userData"参数值一致。
sessionId	是	String(1-256)	唯一指定一条通话链路的标识ID。
caller	否	String(1-32)	主叫号码。号码仅支持全局号码格式（包含国家码），比如+86138****7021。注：挂机事件的主叫号码为SP设置的来电显示号码（displayNbr）。
called	否	String(1-32)	被叫号码。号码仅支持全局号码格式（包含国家码），比如+86138****7021。注：挂机事件的被叫号码为A号码。
stateCode	否	Integer	通话挂机的原因值，仅当eventType为disconnect时携带。取值范围及表示的含义请参考通话挂机原因值说明。
stateDesc	否	String(1-128)	通话挂机的原因值的描述，仅当eventType为disconnect时携带。

接口示例

POST /status HTTP/1.1Content-Length: xx {"eventType":"disconnect","statusInfo":{"sessionId":"1202_14260_4294967295_20190124024846@callenabler245.huaweicaas.com","timestamp":"2019-01-24 02:49:23","caller":"+86138****0022","called":"+86138****0021","stateCode":0,"stateDesc":"The user releases the call."}}

上一篇：语音通话 VoiceCall-语音回呼话单通知API:语音回呼场景请求参数

下一篇：语音通话 VoiceCall-附录1-Q850原因值说明