====== 语音通知接入简介 ======

**语音通知**服务为通讯开放平台为开发者提供的一项服务，开发者可通过接口开发出由系统控制的主动外呼并播放固定语音文件的一种服务。通过这种服务可将程序化的通知类型服务更快更有效的传送至客户。常见于订单类通知、会议类通知、以及通知类提醒等各种场景。

  * 如需更完善的监听服务状态，需要配置 ：[[..回调地址指南|回调地址指南>>]]
===== 1、平台接口规则 =====

  * ① 非协议用户，上传的语音或文本内容，后台须审核，审核通过之后外呼，满足及时性要求不高的客户需求。
  
  * ② 协议用户，上传的语音或文本内容，后台不审核直接外呼，满足及时性要求高的客户需求。
  
  * ③ 语音文件形式：先在管理中心上传语音文件，后台审核通过之后，后续开发者每次传入语音文件名或ID，调用接口就可以自动外呼出去，无须审核，及时性比较高。
  
  * ④ 文本内容形式：在调用接口上上传文本内容，后台审核通过之后，平台自动转换成语音文件后，自动外呼出去，需要审核，及时性比较低。

===== 2、接口详情 =====

通过Rest 请求接口，平台服务器与开发者应用服务器之间直接链接并实时响应服务

==== 2.1 请求 ====

**请求地址**

<code java>
/{SoftVersion}/Accounts/{accountSid}/Calls/voiceNotify
</code>

**请求包头**

详情请查阅统一请求包头，并使用开发者账号进行验证。

**请求包体**

^属性 ^类型 ^约束 ^说明 |
|appId	|String	|必选	|应用Id|
|to	|String	|必选 |被叫号码，可以是正常手机号码、固定号码，被叫为座机时需要添加区号，如：075512345678。|
|type	|String	|必选 |内容类型：0：文本；1：语音ID|
|content	|String	|必选 |当type为0时：文本内容，平台负责将该内容转成语音，呼通指定号码后，播放该语音文件；当type为1时：表示语音ID（语音文件必须先上传）。|
|playTimes	|String	|必选 |循环播放次数，1－3次，默认播放1次。|

----
<hidden XML请求示例>
<code xml>
POST/2014-06-30/Accounts/e03bc9106c6ed0eaebfce8c368fdcd48/Calls/voiceNotify.xml?sig=841D35E63BB81C1D13918B4DD6CD988E
Host:api.ucpaas.com
Accept:application/xml
Content-Type:application/xml;charset=utf-8
Authorization:ZTAzYmM5MTA2YzZlZDBlYWViZmNlOGMzNjhmZGNkNDg6MjAxNDA2MjMxODQ1MjM=

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<voiceNotify>
  <appId>e462aba25bc6498fa5ada7eefe1401b7</appId>
  <to>18612345678</to>
  <type>0</type>
  <content>测试</content>
  <playTimes>3</playTimes>
</voiceNotify>
</code>
</hidden>
----

----
<hidden JSON请求示例>
<code java>
POST/2014-06-30/Accounts/e03bc9106c6ed0eaebfce8c368fdcd48/Calls/voiceNotify?sig=4D3C2549D3A487841CB3D84EA7421FCD
Host:api.ucpaas.com
Accept:application/json
Content-Type:application/json;charset=utf-8

Authorization:ZTAzYmM5MTA2YzZlZDBlYWViZmNlOGMzNjhmZGNkNDg6MjAxNDA2MjMxODQ3MzQ=  
{  
  "voiceNotify"  : {     
    "appId"      : "e462aba25bc6498fa5ada7eefe1401b7",     
    "to"         : "18612345678",
    "type"       : "0",   
    "content"    : "测试",  
    "playTimes" : "3"     
  } 
}
</code>
</hidden>
----
==== 2.2 第三方AS响应 ====

**响应包体**

^属性 ^类型 ^约束 ^说明 |
|respCode	|String	|必选 |请求状态码，取值000000（成功）|
|callId         |String |必选 |一个由32个字符组成的唯一电话标识符|
|createDate     |String |必选 |电话的创建时间|

----
<hidden XML响应示例>
<code xml>
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<resp>
  <respCode>000000</respCode>
  <voiceNotify>
  <callId>48dcc7d44fb274f316924bedd7696645</callId>
  <createDate>20140623184518</createDate>
  </voiceNotify>
</resp>
</code>
</hidden>
----

----
<hidden JSON响应示例>
<code java>
{"resp":{"respCode":"000000","voiceNotify"  : {
        "callId"     : "31d7ca243c406a81611910db21b68876",
        "createDate" : 20140623184729
        }
	}}} 
</code>
</hidden>
----