用户工具

im_服务端开发文档

这是本文档旧的修订版!


1.IM服务端API介绍及接入


1.1简介

为方便不同行业的开发者理解和快速接入,我们将服务端的通讯服务接口提供成一套 Restful 的标准接口,基于这些接口开发者就只需要具备基本的HTTP协议知识背景,以及结合任何一门熟悉的开发语言,就可完成在现有业务的基础上完成集成通讯服务。
Rest是一套新兴的web通讯协议,访问方式和普通的http类似,平台接口分get和post方式请求。协议支持xml,json两种请求方式,采用md5加密算法的方式,通过url参数的形式发送参数。

1.2IM AS 开发实例

为了方便开发者的服务端对接云之讯平台,我们提供了 Server 开发实例:
AS 开发实例(java版)
AS 开发实例(php版)

1.3接入方式


Base URL

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

https://api.ucpaas.com/

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

统一请求包头

请求URL格式

{SoftVersion}/Accounts/{accountSid}/{function}/{operation}?sig={SigParameter}

HTTP标准包头字段(必填)

Accept:application/xml;
Content-Type:application/xml;charset=utf-8;
Content-Length:256;

属性说明


属性 类型 约束 说明
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,即可决定请求包体和响应包体的格式,如:

Content-Type:application/xml;charset=utf-8;Accept:application/xml;

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

Content-Type:application/json;charset=utf-8;Accept:application/json;

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

2.帐号管理


帐号管理主要提供给开发者用于关联自己的帐号体私系到云之讯平台和管理云之讯平台上的帐号,帐号操作管理主要包括:创建帐号、释放帐号、根据手机查询帐号、查询帐号信息。

2.1创建帐号

通过HTTPS POST方式提交请求,云之讯融合通讯开放平台收到请求后,创建Client帐号与开发者提供的用户注册帐号关联。

请求

/{SoftVersion}/Accounts/{accountSid}/Clients

请求包头

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

请求包体

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

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>

JSON请求示例:

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"
    }
}

响应

响应包体

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

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>

JSON响应示例:

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"
        }
    }
}

2.2释放帐号

通过HTTPS POST方式提交请求,云之讯融合通讯开放平台收到请求后,在云之讯平台上释放关闭对应开发者应用下用户的帐号

请求

/{SoftVersion}/Accounts/{accountSid}/dropClient

请求包头

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

请求包体

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

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>

JSON请求示例:

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",
    }
}

响应

响应包体

属性 类型 约束 说明
respCode String 必选 响应状态码,定长6位,取值000000(成功),具体状态码见状态码说明

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>

JSON响应示例:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
 
{
 "resp"   : {
    "respCode"   : "000000"
    }
}

2.3根据手机号查询子帐号

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

请求

/{SoftVersion}/Accounts/{accountSid}/ClientsByMobile

请求包头

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

请求包体

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

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=

JSON请求示例:

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=

响应

响应包体

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

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>

JSON响应示例:

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"
        }
    }
}

2.4根据userId查询子帐号

通过HTTPS GET方式提交请求,云之讯融合通讯开放平台收到请求后,返回开发者应用下与UserId绑定的用户帐号信息

请求

/{SoftVersion}/Accounts/{accountSid}/ClientsByUserId

请求包头

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

请求包体

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

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=

JSON请求示例:

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=

响应

响应包体

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

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>

JSON响应示例:

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"
        }
    }
}

3.群组管理


群组管理主要用于开发者对IM群组各种管理操作,主要包括:创建群组、释放群组、加入群组、退出群组、更新群组和查询群组。

3.1创建群组

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

请求

/{SoftVersion}/Accounts/{accountSid}/im/group/createGroup

请求包头

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

请求包体

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

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>

JSON请求示例:

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"    : "群组名称"
    }
}

响应

响应包体

属性 类型 约束 说明
respCode String 必选 响应状态码,定长6位,取值000000(成功),具体状态码见状态码说明
memberCountString 必选 群组中成员个数
groupNameString 可选 群组名称
userIdString 可选 开发者应用下注册用户的ID,只能数字,最长31位

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>

JSON响应示例:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
 
{
    "resp": {
        "respCode": "000000",
        "memberCount": "1",
        "groupName": "群组名称",
        "memberName":[
            {"userId": "123867124912354679"}
        ]
    }
}

3.2释放群组

通过HTTPS POST方式提交请求,云之讯融合通讯开放平台收到请求后,释放对应的群组。

请求

/{SoftVersion}/Accounts/{accountSid}/im/group/dismissGroup

请求包头

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

请求包体

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

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>

JSON请求示例:

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",
    }
}

响应

响应包体

属性 类型 约束 说明
respCode String 必选 响应状态码,定长6位,取值000000(成功),具体状态码见状态码说明

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>

JSON响应示例:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
 
{
    "resp": {
        "respCode": "000000"
    }
}

3.3加入群组

通过HTTPS POST方式提交请求,云之讯融合通讯开放平台收到请求后,可批量加入多个userId到群组,每次最多加入不超过50人,且加入的userId是已经注册过的帐号。

请求

/{SoftVersion}/Accounts/{accountSid}/im/group/joinGroupBatch

请求包头

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

请求包体

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

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>

JSON请求示例:

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"
    }
}

响应

响应包体

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

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>

部分加入失败,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>

JSON响应示例:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
 
{
    "resp": {
        "respCode": "000000"
    }
}

部分加入失败,JSON响应示例:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
 
{
    "resp": {
        "respCode": "106021", 
        "errorList": [
            {
                "respCode": "103119", 
                "userId": "123867124912354679"
            }, 
            {
                "respCode": "103119", 
                "userId": "123867124912354680"
            }
        ]
    }
}

3.4退出群组

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

请求

/{SoftVersion}/Accounts/{accountSid}/im/group/quitGroup

请求包头

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

请求包体

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

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>

JSON请求示例:

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"
    }
}

响应

响应包体

属性 类型 约束 说明
respCode String 必选 响应状态码,定长6位,取值000000(成功),具体状态码见状态码说明

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>

JSON响应示例:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
 
{
    "resp": {
        "respCode": "000000"
    }
}

3.5更新群组

通过HTTPS POST方式提交请求,云之讯融合通讯开放平台收到请求后,对对应群组更新群名称。

请求

/{SoftVersion}/Accounts/{accountSid}/im/group/updateGroup

请求包头

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

请求包体

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

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>

JSON请求示例:

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"    : "群组名称"
    }
}

响应

响应包体

属性 类型 约束 说明
respCode String 必选 响应状态码,定长6位,取值000000(成功),具体状态码见状态码说明

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>

JSON响应示例:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
 
{
    "resp": {
        "respCode": "000000"
    }
}

3.6查询群组

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

请求

/{SoftVersion}/Accounts/{accountSid}/im/group/getGroup

请求包头

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

请求包体

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

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>

JSON请求示例:

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"
    }
}

响应

响应包体

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

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>

JSON响应示例:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
 
{
    "resp": {
        "respCode": "000000",
        "memberCount": "1",
        "memberName":[
            {"userId": "123867124912354679"}
        ]
    }
}

4.消息管理


消息管理主要用于开发者对IM消息各种管理操作,主要包括:广播消息。

4.1广播消息

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

请求

/{SoftVersion}/Accounts/{accountSid}/im/broadcast/text

请求包头

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

请求包体

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

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>

JSON请求示例:

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"
    }
}

响应

响应包体

属性 类型 约束 说明
respCode String 必选 响应状态码,定长6位,取值000000(成功),具体状态码见状态码说明

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>

JSON响应示例:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
 
{
    "resp": {
        "respCode": "000000"
    }
}

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次

页面工具