======1.IM服务端API介绍及接入======
----
=====1.1简介=====
为方便不同行业的开发者理解和快速接入，我们将服务端的通讯服务接口提供成一套 [[http://en.wikipedia.org/wiki/Representational_State_Transfer|Restful]] 的标准接口，基于这些接口开发者就只需要具备基本的HTTP协议知识背景，以及结合任何一门熟悉的开发语言，就可完成在现有业务的基础上完成集成通讯服务。\\
Rest是一套新兴的web通讯协议，访问方式和普通的http类似，平台接口分get和post方式请求。协议支持xml，json两种请求方式,采用md5加密算法的方式，通过url参数的形式发送参数。\\
=====1.2IM AS 开发实例=====
为了方便开发者的服务端对接云之讯平台，我们提供了  Server 开发实例:\\
[[https://www.ucpaas.com/UCSIMDOWNLOAD/AS/ASSDK_JAVA.zip|AS 开发实例(java版)]]\\
[[https://www.ucpaas.com/UCSIMDOWNLOAD/AS/ASSDK_PHP.zip|AS 开发实例(php版)]]
=====1.3接入方式=====
----
==== Base URL ====

文档中所有请求的URL地址都须加上如下Base URL：

<code java>
https://api.ucpaas.com/
</code>

注意： 为了确保数据隐私和安全， REST API须通过HTTPS方式请求

==== 统一请求包头 ====

**请求URL格式**
<code java>
{SoftVersion}/Accounts/{accountSid}/{function}/{operation}?sig={SigParameter}
</code>

**HTTP标准包头字段（必填）**
<code java>
Accept:application/xml;
Content-Type:application/xml;charset=utf-8;
Content-Length:256;
</code>

==== 属性说明 ====
----

^属性 ^类型 ^约束 ^说明 |
|SoftVersion |String |必选 |云之讯REST API版本号，当前版本号为：2015-06-30  |
|accountSid |String |必选 |开发者账号ID。由32个英文字母和阿拉伯数字组成的开发者账号唯一标识符 |
|SigParameter |String |必选 |请求URL必须带有此参数。  |
|Accept |String |必选 |客户端响应接收数据格式：application/xml、application/json   |
|Content-Type |String |必选 |类型：application/xml;charset=utf-8、application/json;charset=utf-8     |
|Authorization |String |必选 |验证信息。   |
|function |String |可选 |业务功能。    |
|operation |String |可选 |业务操作，业务功能的各类具体操作分支。   |

**说明**

1. SoftVersion是当前使用的REST API版本号，开发时须填写正确的版本号。

2. SigParameter是REST API 验证参数\\
  * URL后必须带有sig参数，sig= MD5（账户Id + 账户授权令牌 + 时间戳），共32位(注:转成大写)
  * 使用MD5加密（账户Id + 账户授权令牌 + 时间戳），共32位
  * 时间戳是当前系统时间（24小时制），格式"yyyyMMddHHmmss"。时间戳有效时间为50分钟。

3. Authorization是包头验证信息\\
  * 使用Base64编码（账户Id + 冒号 + 时间戳） 
  * 冒号为英文冒号
  * 时间戳是当前系统时间（24小时制），格式"yyyyMMddHHmmss"，需与SigParameter中时间戳相同。

4. function描述对应业务能力，operation描述业务能力的具体操作。

   例如：/im/group/getGroup

==== 数据报文格式 ====
----


REST API支持两种主流的报文格式：XML和JSON。

通过请求包头的字段Content-Type及Accept，即可决定请求包体和响应包体的格式，如：

<code java>Content-Type:application/xml;charset=utf-8;Accept:application/xml;</code>

表示请求类型格式是XML，要求服务器响应的包体类型也是XML；

<code java>Content-Type:application/json;charset=utf-8;Accept:application/json;</code>

表示请求类型格式是JSON，要求服务器响应类型也是JSON；


======2.帐号管理======
----
帐号管理主要提供给开发者用于关联自己的帐号体私系到云之讯平台和管理云之讯平台上的帐号，帐号操作管理主要包括：创建帐号、释放帐号、根据手机查询帐号、查询帐号信息。
===== 2.1创建帐号 =====
通过HTTPS POST方式提交请求，云之讯融合通讯开放平台收到请求后，创建Client帐号与开发者提供的用户注册帐号关联。\\

**请求**
<code java>
/{SoftVersion}/Accounts/{accountSid}/Clients
</code>

**请求包头**

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

**请求包体**

^属性 ^类型 ^约束 ^说明 |
|appId	|String	|必选 |开发者创建的应用ID，UCpaas平台生成，固定32位长度|
|userId |String	|必选	|开发者应用下注册用户的ID，数字、字母（区分大小写）组成，最长31位，应用下唯一。|
|friendlyName	|String	|可选	|开发者应用下注册用户对应的昵称，数字、字母（区分大小写）、下划线组成，最长31位|
|mobile	|String	|可选	|绑定的手机号码，同一个应用内唯一。|


**XML请求示例：**
<code xml>
POST/2015-06-30/Accounts/e03bc9106c6ed0eaebfce8c368fdcd48/Clients?sig=3C861C9CFA64862A79B906D80EDB79BA
Host: api.ucpaas.com
Accept:application/xml
Content-Type:application/xml;charset=utf-8
Authorization:ZTAzYmM5MTA2YzZlZDBlYWViZmNlOGMzNjhmZGNkNDg6MjAxNDA2MjMxNzE2MzI=

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<client>
    <appId>e462aba25bc6498fa5ada7eefe1401b7</appId>
    <userId>123867124912354679</userId>
    <friendlyName>97854038</friendlyName>
    <mobile>18612345678</mobile>
</client>
</code>
**JSON请求示例:**
<code java>
POST/2015-06-30/Accounts/e03bc9106c6ed0eaebfce8c368fdcd48/Clients?sig=027282406B5E0E66F4EFE2A86B7A60F7
Host: api.ucpaas.com
Accept:application/json
Content-Type:application/json;charset=utf-8
Authorization:ZTAzYmM5MTA2YzZlZDBlYWViZmNlOGMzNjhmZGNkNDg6MjAxNDA2MjMxNzMwMzg=

{
 "client"   : {
        "appId"        : "e462aba25bc6498fa5ada7eefe1401b7",
	"userId"       : "123867124912354679",
	"friendlyName" : "76598140",
        "mobile"       : "18612345678"
    }
}
</code>
**响应**

**响应包体**
^属性 ^类型 ^约束 ^说明 |
|respCode |String |必选 |响应状态码，定长6位，取值000000（成功)，具体状态码见状态码说明|
|client |String |必选 |client列表，节点的名称|
|clientNumber|String |必选 |UCPaas平台生成的唯一用户id，定长14位数字|
|clientPwd|String |必选 |用户帐号密码，数字和字母混合，定长8位|
|loginToken|String |必选 |UCPaas平台用户令牌|
|createDate|String |必选 |创建日期，格式yyyy-mm-dd hh:mm:ss|
|userId |String	|必选	|开发者应用下注册用户的ID，数字、字母（区分大小写）组成，最长31位，应用下唯一|

**XML响应示例：**
<code xml>
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<resp>
    <respCode>000000</respCode>
    <client>
        <clientNumber>66807000020828</clientNumber>
        <clientPwd>a9316df8</clientPwd>
	<loginToken>e03bc9106c6ed0eaebfce8c368fdcd48</loginToken>
        <createDate>2015-06-23 17:16:27</createDate>
        <userId>123867124912354679</userId>      
    </client>
</resp>
</code>

**JSON响应示例:**
<code java>
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
 "resp"   : {
    "respCode"   : "000000",
    "client"     : {
        "clientNumber" : 66807000020827,
        "clientPwd"    : "c4ad7da6",
        "loginToken"   : "e03bc9106c6ed0eaebfce8c368fdcd48",
        "createDate"   : "2015-06-23 17:15:04",
        "userId"       : "123867124912354679"
        }
    }
}
</code>
===== 2.2释放帐号 =====
通过HTTPS POST方式提交请求，云之讯融合通讯开放平台收到请求后，在云之讯平台上释放关闭对应开发者应用下用户的帐号\\

**请求**
<code java>
/{SoftVersion}/Accounts/{accountSid}/dropClient
</code>

**请求包头**

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

**请求包体**

^属性 ^类型 ^约束 ^说明 |
|appId	|String	|必选 |开发者创建的应用ID，UCpaas平台生成，固定32位长度|
|userId |String	|必选	|开发者应用下注册用户的ID，数字、字母（区分大小写）组成，最长31位，应用下唯一|

**XML请求示例：**
<code xml>
POST/2015-06-30/Accounts/e03bc9106c6ed0eaebfce8c368fdcd48/dropClient?sig=3C861C9CFA64862A79B906D80EDB79BA
Host: api.ucpaas.com
Accept:application/xml
Content-Type:application/xml;charset=utf-8
Authorization:ZTAzYmM5MTA2YzZlZDBlYWViZmNlOGMzNjhmZGNkNDg6MjAxNDA2MjMxNzE2MzI=

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<client>
    <appId> e462aba25bc6498fa5ada7eefe1401b7</appId>
    <userId>123867124912354679</userId>
</client>
</code>
**JSON请求示例:**
<code java>
POST/2015-06-30/Accounts/e03bc9106c6ed0eaebfce8c368fdcd48/dropClient?sig=027282406B5E0E66F4EFE2A86B7A60F7
Host: api.ucpaas.com
Accept:application/json
Content-Type:application/json;charset=utf-8
Authorization:ZTAzYmM5MTA2YzZlZDBlYWViZmNlOGMzNjhmZGNkNDg6MjAxNDA2MjMxNzMwMzg=

{
 "client"   : {
    "appId"  : "e462aba25bc6498fa5ada7eefe1401b7",
    "userId" : "123867124912354679",
    }
}
</code>
**响应**

**响应包体**
^属性 ^类型 ^约束 ^说明 |
|respCode |String |必选 |响应状态码，定长6位，取值000000（成功)，具体状态码见状态码说明|

**XML响应示例：**
<code xml>
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<resp>
    <respCode>000000</respCode>
</resp>
</code>

**JSON响应示例:**
<code java>
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
 "resp"   : {
    "respCode"   : "000000"
    }
}
</code>

===== 2.3根据手机号查询子帐号 =====
通过HTTPS GET方式提交请求，云之讯融合通讯开放平台收到请求后，返回开发者应用下与手机号绑定的用户帐号信息\\

**请求**
<code java>
/{SoftVersion}/Accounts/{accountSid}/ClientsByMobile
</code>

**请求包头**

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

**请求包体**

^属性 ^类型 ^约束 ^说明 |
|appId	|String	|必选 |开发者创建的应用ID，UCpaas平台生成，固定32位长度|
|mobile |String	|必选	|手机号码|

**XML请求示例：**
<code xml>
GET/2015-06-30/Accounts/e03bc9106c6ed0eaebfce8c368fdcd48/ClientsByMobile?sig=0E270413B0B038B7AEB6997F510F98EB&mobile=18612345678&appId=e462aba25bc6498fa5ada7eefe1401b7
Host: api.ucpaas.com
Accept:application/xml
Content-Type:application/xml;charset=utf-8
Authorization:ZTAzYmM5MTA2YzZlZDBlYWViZmNlOGMzNjhmZGNkNDg6MjAxNDA2MjMxNzE2MzI=
</code>
**JSON请求示例:**
<code java>
GET/2015-06-30/Accounts/e03bc9106c6ed0eaebfce8c368fdcd48/ClientsByMobile?sig=83D00E8EF62FC601A4035AE7EEF6197F&mobile=18612345678&appId=e462aba25bc6498fa5ada7eefe1401b7
Host: api.ucpaas.com
Accept:application/json
Content-Type:application/json;charset=utf-8
Authorization:ZTAzYmM5MTA2YzZlZDBlYWViZmNlOGMzNjhmZGNkNDg6MjAxNDA2MjMxNzMwMzg=
</code>
**响应**

**响应包体**
^属性 ^类型 ^约束 ^说明 |
|respCode |String |必选 |响应状态码，定长6位，取值000000（成功)，具体状态码见状态码说明|
|client |String |必选 |client列表，节点的名称|
|friendlyName |String |必选 |开发者应用下用户在UCPaas平台注册的昵称，数字、字母（区分大小写）、下划线组成，最长31位|
|mobile |String |可选 |用户帐号绑定的手机号|
|clientNumber |String |必选 |UCPaas平台生成的唯一用户id，定长14位数字|
|clientPwd |String |必选 |用户帐号密码，数字和字母混合，定长8位|
|createDate |String |必选 |创建日期，格式yyyy-mm-dd hh:mm:ss|
|loginToken|String |必选 |UCPaas平台用户令牌|
|userId |String	|必选	|开发者应用下注册用户的ID，数字、字母（区分大小写）组成，最长31位，应用下唯一|

**XML响应示例：**
<code xml>
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<resp>
    <respCode>000000</respCode>
    <client>  /*Client为节点*/
        <clientNumber>66807000020851</clientNumber>
        <clientPwd>afabcaa9</clientPwd>
        <createDate>2015-06-23 18:41:51</createDate>
        <friendlyName>71127894</friendlyName>
        <mobile>18612345678</mobile>
        <loginToken>e03bc9106c6ed0eaebfce8c368fdcd48</loginToken>
        <userId>123867124912354679</userId>
    </client>
</resp>
</code>

**JSON响应示例:**
<code java>
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
 "resp"   : {
    "respCode"   : "000000",
    "client"     : {
        "clientNumber" : "66807000020851",
        "clientPwd"    : "afabcaa9",
        "createDate"   : "2014-06-23 18:41:51",
        "friendlyName" : "71127894",
        "mobile"       : "18612345678",
        "loginToken"   : "e03bc9106c6ed0eaebfce8c368fdcd48",
        "userId"       : "123867124912354679"
        }
    }
}
</code>
===== 2.4根据userId查询子帐号 =====
通过HTTPS GET方式提交请求，云之讯融合通讯开放平台收到请求后，返回开发者应用下与UserId绑定的用户帐号信息\\

**请求**
<code java>
/{SoftVersion}/Accounts/{accountSid}/ClientsByUserId
</code>

**请求包头**

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

**请求包体**

^属性 ^类型 ^约束 ^说明 |
|appId	|String	|必选 |开发者创建的应用ID，UCpaas平台生成，固定32位长度|
|userId |String	|必选	|开发者应用下注册用户的ID，数字、字母（区分大小写）组成，最长31位，应用下唯一|

**XML请求示例：**
<code xml>
GET/2015-06-30/Accounts/e03bc9106c6ed0eaebfce8c368fdcd48/ClientsByUserId?sig=0E270413B0B038B7AEB6997F510F98EB&userId=18612345678123&appId=e462aba25bc6498fa5ada7eefe1401b7
Host: api.ucpaas.com
Accept:application/xml
Content-Type:application/xml;charset=utf-8
Authorization:ZTAzYmM5MTA2YzZlZDBlYWViZmNlOGMzNjhmZGNkNDg6MjAxNDA2MjMxNzE2MzI=
</code>
**JSON请求示例:**
<code java>
GET/2015-06-30/Accounts/e03bc9106c6ed0eaebfce8c368fdcd48/ClientsByUserId?sig=83D00E8EF62FC601A4035AE7EEF6197F&userId=18612345678123&appId=e462aba25bc6498fa5ada7eefe1401b7
Host: api.ucpaas.com
Accept:application/json
Content-Type:application/json;charset=utf-8
Authorization:ZTAzYmM5MTA2YzZlZDBlYWViZmNlOGMzNjhmZGNkNDg6MjAxNDA2MjMxNzMwMzg=
</code>
**响应**

**响应包体**
^属性 ^类型 ^约束 ^说明 |
|respCode |String |必选 |响应状态码，定长6位，取值000000（成功)，具体状态码见状态码说明|
|client |String |必选 |client列表，节点的名称|
|friendlyName |String |必选 |开发者应用下用户在UCPaas平台注册的昵称，数字、字母（区分大小写）、下划线注册，最长31位|
|mobile |String |可选 |用户帐号绑定的手机号|
|clientNumber |String |必选 |UCPaas平台生成的唯一用户id，定长14位数字|
|clientPwd |String |必选 |用户帐号密码，数字和字母混合，定长8位|
|createDate |String |必选 |创建日期，格式yyyy-mm-dd hh:mm:ss|
|loginToken|String |必选 |UCPaas平台用户令牌|
|userId |String	|必选	|开发者应用下注册用户的ID，数字、字母（区分大小写）组成，最长31位|

**XML响应示例：**
<code xml>
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<resp>
    <respCode>000000</respCode>
    <client>  /*Client为节点*/
        <clientNumber>66807000020851</clientNumber>
        <clientPwd>afabcaa9</clientPwd>
        <createDate>2015-06-23 18:41:51</createDate>
        <friendlyName>71127894</friendlyName>
        <mobile>18612345678</mobile>
        <loginToken>e03bc9106c6ed0eaebfce8c368fdcd48</loginToken>
        <userId>123867124912354679</userId>
    </client>
</resp>
</code>

**JSON响应示例:**
<code java>
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
 "resp"   : {
    "respCode"   : "000000",
    "client"     : {
        "clientNumber" : "66807000020851",
        "clientPwd"    : "afabcaa9",
        "createDate"   : "2014-06-23 18:41:51",
        "friendlyName" : "71127894",
        "mobile"       : "18612345678",
        "loginToken"   : "e03bc9106c6ed0eaebfce8c368fdcd48",
        "userId"       : "123867124912354679"
        }
    }
}
</code>
======3.群组管理======
----
群组管理主要用于开发者对IM群组各种管理操作，主要包括:创建群组、释放群组、加入群组、退出群组、更新群组和查询群组。

===== 3.1创建群组 =====
通过HTTPS POST方式提交请求，云之讯融合通讯开放平台收到请求后，创建一个对应的群组。\\

**请求**
<code java>
/{SoftVersion}/Accounts/{accountSid}/im/group/createGroup
</code>

**请求包头**

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

**请求包体**

^属性 ^类型 ^约束 ^说明 |
|appId	|String	|必选 |开发者创建的应用ID，UCpaas平台生成，固定32位长度|
|groupId |String|必选 |群组ID|
|userId	|String	|必选 |开发者应用下用户的ID|
|groupName |String |可选 |群组名称|

**XML请求示例：**
<code xml>
POST/2015-06-30/Accounts/e03bc9106c6ed0eaebfce8c368fdcd48/im/group/createGroup?sig=3C861C9CFA64862A79B906D80EDB79BA
Host: api.ucpaas.com
Accept:application/xml
Content-Type:application/xml;charset=utf-8
Authorization:ZTAzYmM5MTA2YzZlZDBlYWViZmNlOGMzNjhmZGNkNDg6MjAxNDA2MjMxNzE2MzI=

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<imGroup>
    <appId>e462aba25bc6498fa5ada7eefe1401b7</appId>
    <groupId>97854038</groupId>
    <userId>123867124912354679</userId>
    <groupName>群组名称</groupName>
</imGroup>
</code>
**JSON请求示例:**
<code java>
POST/2015-06-30/Accounts/e03bc9106c6ed0eaebfce8c368fdcd48/im/group/createGroup?sig=027282406B5E0E66F4EFE2A86B7A60F7
Host: api.ucpaas.com
Accept:application/json
Content-Type:application/json;charset=utf-8
Authorization:ZTAzYmM5MTA2YzZlZDBlYWViZmNlOGMzNjhmZGNkNDg6MjAxNDA2MjMxNzMwMzg=

{
 "imGroup"   : {
    "appId"        : "e462aba25bc6498fa5ada7eefe1401b7",
    "groupId"      : "97854038",
    "userId"       : "123867124912354679"
    "groupName"    : "群组名称"
    }
}
</code>
**响应**

**响应包体**
^属性 ^类型 ^约束 ^说明 |
|respCode |String |必选 |响应状态码，定长6位，取值000000（成功)，具体状态码见状态码说明|
|memberCount|String |必选 |群组中成员个数|
|groupName|String |可选 |群组名称|
|userId|String |可选 |开发者应用下注册用户的ID，只能数字，最长31位|


**XML响应示例：**
<code xml>
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<resp>
    <respCode>000000</respCode>
    <memberCount>1</memberCount>
    <groupName >群组名称</groupName>
    <memberName>
        <userId>123867124912354679<userId>
    </memberName>
</resp>
</code>

**JSON响应示例:**
<code java>
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "resp": {
        "respCode": "000000",
        "memberCount": "1",
        "groupName": "群组名称",
        "memberName":[
            {"userId": "123867124912354679"}
        ]
    }
}
</code>
===== 3.2释放群组 =====
通过HTTPS POST方式提交请求，云之讯融合通讯开放平台收到请求后，释放对应的群组。\\

**请求**
<code java>
/{SoftVersion}/Accounts/{accountSid}/im/group/dismissGroup
</code>

**请求包头**

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

**请求包体**

^属性 ^类型 ^约束 ^说明 |
|appId	|String	|必选 |开发者创建的应用ID，UCpaas平台生成，固定32位长度|
|groupId |String|必选 |群组ID|

**XML请求示例：**
<code xml>
POST/2015-06-30/Accounts/e03bc9106c6ed0eaebfce8c368fdcd48/im/group/dismissGroup?sig=3C861C9CFA64862A79B906D80EDB79BA
Host: api.ucpaas.com
Accept:application/xml
Content-Type:application/xml;charset=utf-8
Authorization:ZTAzYmM5MTA2YzZlZDBlYWViZmNlOGMzNjhmZGNkNDg6MjAxNDA2MjMxNzE2MzI=

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<imGroup>
    <appId>e462aba25bc6498fa5ada7eefe1401b7</appId>
    <groupId>97854038</groupId>
</imGroup>
</code>
**JSON请求示例:**
<code java>
POST/2015-06-30/Accounts/e03bc9106c6ed0eaebfce8c368fdcd48/im/group/dismissGroup?sig=027282406B5E0E66F4EFE2A86B7A60F7
Host: api.ucpaas.com
Accept:application/json
Content-Type:application/json;charset=utf-8
Authorization:ZTAzYmM5MTA2YzZlZDBlYWViZmNlOGMzNjhmZGNkNDg6MjAxNDA2MjMxNzMwMzg=

{
 "imGroup"   : {
    "appId"        : "e462aba25bc6498fa5ada7eefe1401b7",
    "groupId"      : "97854038",
    }
}
</code>
**响应**

**响应包体**
^属性 ^类型 ^约束 ^说明 |
|respCode |String |必选 |响应状态码，定长6位，取值000000（成功)，具体状态码见状态码说明|


**XML响应示例：**
<code xml>
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<resp>
    <respCode>000000</respCode>
</resp>
</code>

**JSON响应示例:**
<code java>
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "resp": {
        "respCode": "000000"
    }
}
</code>
===== 3.3加入群组 =====
通过HTTPS POST方式提交请求，云之讯融合通讯开放平台收到请求后，可批量加入多个userId到群组，每次最多加入不超过50人，且加入的userId是已经注册过的帐号。\\

**请求**
<code java>
/{SoftVersion}/Accounts/{accountSid}/im/group/joinGroupBatch
</code>

**请求包头**

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

**请求包体**

^属性 ^类型 ^约束 ^说明 |
|appId	|String	|必选 |开发者创建的应用ID，UCpaas平台生成，固定32位长度|
|groupId |String |必选 |群组ID|
|userId |String |必选 |多个用户userId字符串列表，用英文逗号隔开，一次最多加50个用户，userId最长不超过31|

**XML请求示例：**
<code xml>
POST/2015-06-30/Accounts/e03bc9106c6ed0eaebfce8c368fdcd48/im/group/joinGroupBatch?sig=3C861C9CFA64862A79B906D80EDB79BA
Host: api.ucpaas.com
Accept:application/xml
Content-Type:application/xml;charset=utf-8
Authorization:ZTAzYmM5MTA2YzZlZDBlYWViZmNlOGMzNjhmZGNkNDg6MjAxNDA2MjMxNzE2MzI=

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<imGroup>
    <appId>e462aba25bc6498fa5ada7eefe1401b7</appId>
    <groupId>97854038</groupId>
    <userId>123867124912354679, 123867124912354680</userId>
</imGroup>
</code>
**JSON请求示例:**
<code java>
POST/2015-06-30/Accounts/e03bc9106c6ed0eaebfce8c368fdcd48/im/group/joinGroupBatch?sig=027282406B5E0E66F4EFE2A86B7A60F7
Host: api.ucpaas.com
Accept:application/json
Content-Type:application/json;charset=utf-8
Authorization:ZTAzYmM5MTA2YzZlZDBlYWViZmNlOGMzNjhmZGNkNDg6MjAxNDA2MjMxNzMwMzg=

{
 "imGroup"   : {
    "appId"        : "e462aba25bc6498fa5ada7eefe1401b7",
    "groupId"      : "97854038",
    "userId"       : "123867124912354679, 123867124912354680"
    }
}
</code>
**响应**

**响应包体**
^属性 ^类型 ^约束 ^说明 |
|respCode |String |必选 |响应状态码，定长6位，取值000000（成功)，具体状态码见状态码说明|
|errorList|String |可选 |加入失败时的，失败用户列表|

**XML响应示例：**
<code xml>
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<resp>
    <respCode>000000</respCode>
</resp>
</code>

**部分加入失败，XML响应示例：**
<code xml>
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<resp>
    <respCode>106021</respCode>
    <errorList>
        <respCode>103119</respCode>
        <userId>123867124912354679</userId>
    </errorList>
    <errorList>
        <respCode>103119</respCode>
        <userId>123867124912354680</userId>
    </errorList>
</resp>
</code>

**JSON响应示例:**
<code java>
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "resp": {
        "respCode": "000000"
    }
}
</code>

**部分加入失败，JSON响应示例：**
<code java>
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "resp": {
        "respCode": "106021", 
        "errorList": [
            {
                "respCode": "103119", 
                "userId": "123867124912354679"
            }, 
            {
                "respCode": "103119", 
                "userId": "123867124912354680"
            }
        ]
    }
}
</code>

===== 3.4退出群组 =====
通过HTTPS POST方式提交请求，云之讯融合通讯开放平台收到请求后，把指定用户移出对应群组。\\

**请求**
<code java>
/{SoftVersion}/Accounts/{accountSid}/im/group/quitGroup
</code>

**请求包头**

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

**请求包体**

^属性 ^类型 ^约束 ^说明 |
|appId	|String	|必选 |开发者创建的应用ID，UCpaas平台生成，固定32位长度|
|groupId |String|必选 |群组ID|
|userId	|String	|必选 |开发者应用下用户的ID|

**XML请求示例：**
<code xml>
POST/2015-06-30/Accounts/e03bc9106c6ed0eaebfce8c368fdcd48/im/group/quitGroup?sig=3C861C9CFA64862A79B906D80EDB79BA
Host: api.ucpaas.com
Accept:application/xml
Content-Type:application/xml;charset=utf-8
Authorization:ZTAzYmM5MTA2YzZlZDBlYWViZmNlOGMzNjhmZGNkNDg6MjAxNDA2MjMxNzE2MzI=

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<imGroup>
    <appId>e462aba25bc6498fa5ada7eefe1401b7</appId>
    <groupId>97854038</groupId>
    <userId>123867124912354679</userId>
</imGroup>
</code>
**JSON请求示例:**
<code java>
POST/2015-06-30/Accounts/e03bc9106c6ed0eaebfce8c368fdcd48/im/group/quitGroup?sig=027282406B5E0E66F4EFE2A86B7A60F7
Host: api.ucpaas.com
Accept:application/json
Content-Type:application/json;charset=utf-8
Authorization:ZTAzYmM5MTA2YzZlZDBlYWViZmNlOGMzNjhmZGNkNDg6MjAxNDA2MjMxNzMwMzg=

{
 "imGroup"   : {
    "appId"        : "e462aba25bc6498fa5ada7eefe1401b7",
    "groupId"      : "97854038",
    "userId"       : "123867124912354679"
    }
}
</code>
**响应**

**响应包体**
^属性 ^类型 ^约束 ^说明 |
|respCode |String |必选 |响应状态码，定长6位，取值000000（成功)，具体状态码见状态码说明|

**XML响应示例：**
<code xml>
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<resp>
    <respCode>000000</respCode>
</resp>
</code>

**JSON响应示例:**
<code java>
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "resp": {
        "respCode": "000000"
    }
}
</code>
===== 3.5更新群组 =====
通过HTTPS POST方式提交请求，云之讯融合通讯开放平台收到请求后，对对应群组更新群名称。\\

**请求**
<code java>
/{SoftVersion}/Accounts/{accountSid}/im/group/updateGroup
</code>

**请求包头**

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

**请求包体**

^属性 ^类型 ^约束 ^说明 |
|appId	|String	|必选 |开发者创建的应用ID，UCpaas平台生成，固定32位长度|
|groupId |String|必选 |群组ID|
|groupName |String |可选 |群组名称|

**XML请求示例：**
<code xml>
POST/2015-06-30/Accounts/e03bc9106c6ed0eaebfce8c368fdcd48/im/group/updateGroup?sig=3C861C9CFA64862A79B906D80EDB79BA
Host: api.ucpaas.com
Accept:application/xml
Content-Type:application/xml;charset=utf-8
Authorization:ZTAzYmM5MTA2YzZlZDBlYWViZmNlOGMzNjhmZGNkNDg6MjAxNDA2MjMxNzE2MzI=

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<imGroup>
    <appId>e462aba25bc6498fa5ada7eefe1401b7</appId>
    <groupId>97854038</groupId>
    <groupName>群组名称</groupName>
</imGroup>
</code>
**JSON请求示例:**
<code java>
POST/2015-06-30/Accounts/e03bc9106c6ed0eaebfce8c368fdcd48/im/group/updateGroup?sig=027282406B5E0E66F4EFE2A86B7A60F7
Host: api.ucpaas.com
Accept:application/json
Content-Type:application/json;charset=utf-8
Authorization:ZTAzYmM5MTA2YzZlZDBlYWViZmNlOGMzNjhmZGNkNDg6MjAxNDA2MjMxNzMwMzg=

{
 "imGroup"   : {
    "appId"        : "e462aba25bc6498fa5ada7eefe1401b7",
    "groupId"      : "97854038",
    "groupName"    : "群组名称"
    }
}
</code>
**响应**

**响应包体**
^属性 ^类型 ^约束 ^说明 |
|respCode |String |必选 |响应状态码，定长6位，取值000000（成功)，具体状态码见状态码说明|


**XML响应示例：**
<code xml>
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<resp>
    <respCode>000000</respCode>
</resp>
</code>

**JSON响应示例:**
<code java>
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "resp": {
        "respCode": "000000"
    }
}
</code>

===== 3.6查询群组 =====
通过HTTPS POST方式提交请求，云之讯融合通讯开放平台收到请求后，查询对应群组信息并返回。\\

**请求**
<code java>
/{SoftVersion}/Accounts/{accountSid}/im/group/getGroup
</code>

**请求包头**

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

**请求包体**

^属性 ^类型 ^约束 ^说明 |
|appId	|String	|必选 |开发者创建的应用ID，UCpaas平台生成，固定32位长度|
|groupId |String|必选 |群组ID|

**XML请求示例：**
<code xml>
POST/2015-06-30/Accounts/e03bc9106c6ed0eaebfce8c368fdcd48/im/group/getGroup?sig=3C861C9CFA64862A79B906D80EDB79BA
Host: api.ucpaas.com
Accept:application/xml
Content-Type:application/xml;charset=utf-8
Authorization:ZTAzYmM5MTA2YzZlZDBlYWViZmNlOGMzNjhmZGNkNDg6MjAxNDA2MjMxNzE2MzI=

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<imGroup>
    <appId>e462aba25bc6498fa5ada7eefe1401b7</appId>
    <groupId>97854038</groupId>
</imGroup>
</code>
**JSON请求示例:**
<code java>
POST/2015-06-30/Accounts/e03bc9106c6ed0eaebfce8c368fdcd48/im/group/getGroup?sig=027282406B5E0E66F4EFE2A86B7A60F7
Host: api.ucpaas.com
Accept:application/json
Content-Type:application/json;charset=utf-8
Authorization:ZTAzYmM5MTA2YzZlZDBlYWViZmNlOGMzNjhmZGNkNDg6MjAxNDA2MjMxNzMwMzg=

{
 "imGroup"   : {
    "appId"        : "e462aba25bc6498fa5ada7eefe1401b7",
    "groupId"      : "97854038"
    }
}
</code>
**响应**

**响应包体**
^属性 ^类型 ^约束 ^说明 |
|respCode |String |必选 |响应状态码，定长6位，取值000000（成功)，具体状态码见状态码说明|
|memberCount|String |必选 |群组中成员个数|
|userId|String |可选 |开发者应用下注册用户的ID，只能数字，最长31位|


**XML响应示例：**
<code xml>
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<resp>
    <respCode>000000</respCode>
    <memberCount>1</memberCount>
    <memberName>
        <userId>123867124912354679<userId>
    </memberName>
</resp>
</code>

**JSON响应示例:**
<code java>
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "resp": {
        "respCode": "000000",
        "memberCount": "1",
        "memberName":[
            {"userId": "123867124912354679"}
        ]
    }
}
</code>

======4.消息管理======
----
消息管理主要用于开发者对IM消息各种管理操作，主要包括:广播消息。

===== 4.1广播消息 =====
通过HTTPS POST方式提交请求，云之讯融合通讯开放平台收到请求后，发送广播消息并返回。\\

**请求**
<code java>
/{SoftVersion}/Accounts/{accountSid}/im/broadcast/text
</code>

**请求包头**

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

**请求包体**

^属性 ^类型 ^约束 ^说明 |
|appId	|String	|必选 |开发者创建的应用ID，UCpaas平台生成，固定32位长度|
|content |String|必选 |消息内容|

**XML请求示例：**
<code xml>
POST/2015-06-30/Accounts/e03bc9106c6ed0eaebfce8c368fdcd48/im/broadcast/text?sig=3C861C9CFA64862A79B906D80EDB79BA
Host: api.ucpaas.com
Accept:application/xml
Content-Type:application/xml;charset=utf-8
Authorization:ZTAzYmM5MTA2YzZlZDBlYWViZmNlOGMzNjhmZGNkNDg6MjAxNDA2MjMxNzE2MzI=

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<imBroadcast>
    <appId>e462aba25bc6498fa5ada7eefe1401b7</appId>
    <content>消息内容11</content>
</imBroadcast>
</code>
**JSON请求示例:**
<code java>
POST/2015-06-30/Accounts/e03bc9106c6ed0eaebfce8c368fdcd48/im/broadcast/text?sig=027282406B5E0E66F4EFE2A86B7A60F7
Host: api.ucpaas.com
Accept:application/json
Content-Type:application/json;charset=utf-8
Authorization:ZTAzYmM5MTA2YzZlZDBlYWViZmNlOGMzNjhmZGNkNDg6MjAxNDA2MjMxNzMwMzg=

{
 "imBroadcast"   : {
    "appId"        : "e462aba25bc6498fa5ada7eefe1401b7",
    "content"      : "消息内容11"
    }
}
</code>
**响应**

**响应包体**
^属性 ^类型 ^约束 ^说明 |
|respCode |String |必选 |响应状态码，定长6位，取值000000（成功)，具体状态码见状态码说明|


**XML响应示例：**
<code xml>
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<resp>
    <respCode>000000</respCode>
</resp>
</code>

**JSON响应示例:**
<code java>
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "resp": {
        "respCode": "000000"
    }
}
</code>

======5.服务端接口全局返回码======
----
在调用服务端的REST接口API时，云之讯平台服务端会返回成功或失败的返回码，对每个返回码对应相应的原因说明。
=====5.1帐号管理接口返回码=====
^返回码 ^说明 |
|000000 |成功执行|
|100000 |金额不为整数 |
|100001 |余额不足 |
|100002 |数字非法 |
|100003 |不允许有空值 |
|100004 |枚举类型取值错误 |
|100005 |访问IP不合法 |
|100006 |手机号不合法 |
|100007 |查无数据 |
|100008 |手机号码为空 |
|100009 |手机号为受保护的号码 |
|100010 |登录邮箱或手机号为空 |
|100011 |邮箱不合法 |
|100012 |密码不能为空 |
|100013 |没有测试子账号 |
|100015 |号码不合法 |
|100016 |余额被冻结 |
|100017 |余额已注销 |
|100699	|系统内部错误 |
|101100	|请求包头Authorization参数为空 |
|101101	|请求包头Authorization参数Base64解码失败 |
|101102	|请求包头Authorization参数解码后账户ID为空 |
|101103	|请求包头Authorization参数解码后时间戳为空 |
|101104	|请求包头Authorization参数解码后格式有误 |
|101105	|主账户ID存在非法字符 |
|101106	|请求包头Authorization 参数解码后时间戳过期 |
|101107	|请求地址SoftVersion参数有误 |
|101108	|主账户已关闭 |
|101109	|主账户未激活 |
|101111	|主账户不存在 |
|101112	|主账户ID为空 |
|101113	|请求包头Authorization参数中账户ID跟请求地址中的账户ID不一致 |
|101114	|请求地址Sig参数为空 |
|101115	|请求token校验失败 |
|101116	|主账号sig加密串不匹配 |
|101117	|主账号token不存在 |
|102100	|应用ID为空 |
|102101	|应用ID存在非法字符 |
|102102	|应用不存在 |
|102103	|应用未审核通过 |
|102104	|测试应用不允许创建client |
|102105	|应用不属于该主账号 |
|102115	|应用ID超长，超过50个字符 |
|103100	|子账户昵称为空 |
|103101	|子账户名称存在非法字符 |
|103102	|子账户昵称长度有误 |
|103105	|子账户friendlyname只能包含数字和字母和下划线 |
|103107	|client不存在或不属于该主账号 |
|103108	|client已经关闭 |
|103114	|同一应用下同一手机号只能绑定一次 |
|103116	|绑定手机号失败 |
|103119	|应用下该子账号不存在 |
|103121	|查询client参数不能为空 | 
|103122	|client不属于应用 |
|103123	|未上线应用不能超过100个client |
|103126	|未上线应用或demo只能使用白名单中号码 |
|103127	|测试demo不能创建子账号 |
|103129	|校验码错误或失效 |
|103130	|校验号码失败 |
|103131	|解绑失败,信息错误或不存在绑定关系 |
|103132 |userId为空 | 
|103133 |userId不存在|
|103134 |userId不合法，含非法字符 |
|103135 |userId超长,超过31个字符 |
|103136 |userId已处于关闭状态 |
|103137 |调用中间件创建子账号失败 |
|103138 |同一个应用下userId只能被注册一次 |
|103139	|测试client不能换绑 |
|103140	|测试client不能解绑 |
|105101 |URL必选参数为空 |
|100500 |HTTP状态码不等于200 |

=====5.2群组管理接口返回码=====
^返回码 ^说明 |
|106000	|userId为空 |
|106001	|userId在该群组中不存在 |
|106002	|userId不合法，含非法字符 |
|106003	|userId超长 |
|106004	|userId已处于关闭状态 |
|106005	|同一个应用下userId只能被注册一次 |
|106006	|该userId对应的子账户不存在 |
|106007	|群组ID为空 |
|106008	|群组ID不合法，含非法字符 |
|106009	|groupName在应用下已经存在 |
|106010	|groupName长度限制32个字符 |
|106011	|groupId长度限制32个字符 |
|106012	|groupId群组不存在 |
|106013	|groupId已处于已经释放状态 |
|106014	|groupId属于应用，应用不属于主账号 |
|106015	|groupId属于主账号，应用不属于主账号 |
|106016	|groupId不属于主账号和应用，应用属于主账号 |
|106017	|groupId不属于主账号和应用，应用不属于主账号 |
|106018	|单次加入group人数不能超过50人 |
|106019	|要加入的userId在group中已存在 |
|106020	|群组名称为空 |
|106021	|群组对象不能为空 |
|106022	|groupId群组已创建，不能重复创建 |
|106023	|获取群组失败 |
|106024	|更新群组失败 |
|106025	|获取群组成员列表失败 |
|106026	|删除群组失败 |
|106027	|群组批量加入成员超过50个 |
|106028	|群组批量加入成员失败(包括部分失败) |

=====5.3消息管理接口返回码=====
^返回码 ^说明 |
|106029	|消息对象不能为空 |
|106030	|消息内容不能为空 |
|106031	|消息内容长度限制500个字符 |
|106032	|发送次数限制：1小时内最多只能发送1次，24小时内最多只能发送3次 |