极光文档 > 极光IM > REST API > REST API

IM REST API

最近更新：2021-12-15

本页目录

User 对象字段总览
用户注册
- 注册用户
用户维护
消息相关
- 发送消息
- 消息撤回
媒体文件下载与上传
- 文件上传
Group 对象字段总览
群组维护
好友
跨应用
敏感词
聊天室字段总览
聊天室维护
配置
- 设置 SDK-API 用户注册开关
- 获得 SDK-API 用户注册开关
HTTP 返回
- Example Error Response
业务错误码定义

展开全部

IM REST API

极光 IM API 为开发者提供 IM 相关功能的 HTTP API。

这类 API 地址统一为（注意与 Push API 不同）：https://api.im.jpush.cn

如无特殊说明，调用参数值应转码为：UTF-8，一个汉字占用 3 个字节长度。

HTTP 验证

验证采用 HTTP Basic 机制，即 HTTP Header（头）里加一个字段（Key/Value 对）：

Authorization: Basic base64_auth_string

其中 base64_auth_string 的生成算法为：base64(appKey:masterSecret)

即，对 appKey 加上冒号，加上 masterSecret 拼装起来的字符串，再做 base64 转换。

字符串规范

此处定义 JMessage 产品里字段属性与规范，用于校验与规范化。

参数	字符说明	长度限制
app_key	由 JPush Web Portal 生成的 24位字符串。字母或者数字，不区分大小写
username	以字母或者数字开头。支持字母、数字、下划线、英文点、减号、 @。	Byte(4~128)
password	不限	Byte(4~128)
group_name	不支持的字符：“\n” “\r”	Byte(0~64)
nickname	不支持的字符：“\n” “\r”	Byte(0~64)
note_name	不支持的字符：“\n” “\r”	Byte(0~64)
other	其他未明确指定的 String 类型字段，都按照这个处理。支持字符：全部	Byte(0~250)

User 对象字段总览

参数	含义	字符长度限制
username	用户登录名	Byte(4~128)
password	登录密码	Byte(4~128)
appkey	用户所属于的应用的appkey
nickname	用户昵称	Byte(0~64)
birthday	生日	yyyy-MM-dd HH:mm:ss
gender	性别 0 - 未知， 1 - 男，2 - 女
signature	用户签名	Byte(0~250)
region	用户所属地区	Byte(0~250)
address	用户详细地址	Byte(0~250)
ctime	用户创建时间
mtime	用户最后修改时间
extras	用户自定义json对象	Byte(0~512)

用户注册

注册用户

批量注册用户到极光 IM 服务器，一次批量注册最多支持 500 个用户。

POST /v1/users/

          POST /v1/users/

此代码块在浮窗中显示

Example Request

[{ "username": "dev_fang", "password": "password" }]

          [{
    "username": "dev_fang",
    "password": "password"
}]

此代码块在浮窗中显示

Request Params

JSON Array.

username（必填）用户名
- 开头：字母或者数字
- 字母、数字、下划线
- 英文点、减号、@
password（必填）用户密码。极光 IM 服务器会 MD5 加密保存。
nickname （选填）用户昵称
- 不支持的字符：英文字符： \n \r\n
avatar （选填）头像
- 需要填上从文件上传接口获得的 media_id
birthday （选填）生日 example: 1990-01-24
- yyyy-MM-dd
signature （选填）签名
- 支持的字符：全部，包括 Emoji
gender （选填）性别
- 0 - 未知， 1 - 男，2 - 女
region （选填）地区
- 支持的字符：全部，包括 Emoji
address （选填）地址
- 支持的字符：全部，包括 Emoji
extras (选填) 用户自定义 json 对象

Example Response

< HTTP/1.1 201 Created < Content-Type: application/json < [{ "username": "dev_fang" }]

          < HTTP/1.1 201 Created
< Content-Type: application/json
<
[{
    "username": "dev_fang"
}]

此代码块在浮窗中显示

Response Params

JSON Array.

username
error 某个用户注册出错时，该对象里会有 error 对象，说明错误原因。
- 899003 参数错误，Request Body 参数不符合要求
- 899001 用户已存在

用户维护

获取用户信息

GET /v1/users/{username}

          GET /v1/users/{username}

此代码块在浮窗中显示

Request Params

username 用户名。填充到请求路径上。

Example Response

{ "username": "javen", "nickname": "hello", "avatar": "/avatar", "birthday": "1990-01-24 00:00:00", "gender": 0, "signature": "orz", "region": "shenzhen", "address": "shenzhen", "mtime": "2015-01-01 00:00:00", "ctime": "2015-01-01 00:00:00", "extras": { "key": "value" } }

          {
    "username": "javen",
    "nickname": "hello",
    "avatar": "/avatar",
    "birthday": "1990-01-24 00:00:00",
    "gender": 0,
    "signature": "orz",
    "region": "shenzhen",
    "address": "shenzhen",
    "mtime": "2015-01-01 00:00:00",
    "ctime": "2015-01-01 00:00:00",
    "extras": {
        "key": "value"
    }
}

此代码块在浮窗中显示

说明

除了 username mtime ctime 这三个子段之外，其余字段如果没存 json 中就没有相应的 key

更新用户信息

PUT /v1/users/{username}

          PUT /v1/users/{username}

此代码块在浮窗中显示

Example Request

{ "nickname": "Hello JMessage" }

          {
    "nickname": "Hello JMessage"
}

此代码块在浮窗中显示

Request Params

nickname （选填）用户昵称
- 不支持的字符：英文字符： \n \r\n
avatar （选填）头像
- 需要填上从文件上传接口获得的 media_id
birthday （选填）生日 example: 1990-01-24
- yyyy-MM-dd
signature （选填）签名
- 支持的字符：全部，包括 Emoji
gender （选填）性别
- 0 - 未知， 1 - 男，2 - 女
region （选填）地区
- 支持的字符：全部，包括 Emoji
address （选填）地址
- 支持的字符：全部，包括 Emoji
extras (选填) 用户自定义 json 对象

Example Response

< HTTP/1.1 204 < Content-Type: application/json; charset=utf-8

          < HTTP/1.1 204
< Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

用户在线状态查询

Get /v1/users/{username}/userstat

          Get /v1/users/{username}/userstat

此代码块在浮窗中显示

Example Request

Request Header

Get /v1/users/caiyh/userstat Content-Type: application/json; charset=utf-8

          Get /v1/users/caiyh/userstat
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Request Params

username 用户名

Request Body

N/A

Example Response

Response Header

HTTP/1.1 200 NO Content Content-Type: application/json; charset=utf-8

          HTTP/1.1 200 NO Content
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Response Data

{ "login": true, "online": false }

          {
    "login": true,
    "online": false
}

此代码块在浮窗中显示

该接口不适用于多端在线，多端在线请用批量状态接口

Error Code

错误码

899003 username 不合法
899002 用户不存在

批量用户在线状态查询

Post /v1/users/userstat

          Post /v1/users/userstat

此代码块在浮窗中显示

Example Request

Request Header

Post /v1/users/userstat Content-Type: application/json; charset=utf-8

          Post /v1/users/userstat
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Request Params

N/A

Request Body

["USER1","USER2"]

Example Response

Response Header

HTTP/1.1 200 Content-Type: application/json; charset=utf-8

          HTTP/1.1 200
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Response Data

[{ "devices": [], "username": "caiyh01" }, { "devices": [{ "login": false, "online": false, "platform": "a" }], "username": "Rauly" }]

          [{
    "devices": [],
    "username": "caiyh01"
}, {
    "devices": [{
        "login": false,
        "online": false,
        "platform": "a"
    }],
    "username": "Rauly"
}]

此代码块在浮窗中显示

devices 设备登陆状态数组，没有登陆过数组为空
platform SDK 各平台：a-Android，i-iOS，j-JS，w-Windows

Error Code

错误码

899003 username 不合法
899002 用户不存在

批量用户在线状态查询 v2

Post /v2/users/statuser

          Post /v2/users/statuser

此代码块在浮窗中显示

Example Request

Request Header

Post /v2/users/statuser Content-Type: application/json; charset=utf-8

          Post /v2/users/statuser
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Request Params

N/A

Request Body

["USER1","USER2"]

Example Response

Response Header

HTTP/1.1 200 Content-Type: application/json; charset=utf-8

          HTTP/1.1 200
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Response Data

[{ "devices": [], "username": "caiyh01", "statuscode": 1, // 用户不存在，会有statusmsg "statusmsg": "no_exist" }, { "devices": [{ "login": false, "online": false, "platform": "a" }], "username": "Rauly", "statuscode": 0 // 用户存在 }]

          [{
    "devices": [],
    "username": "caiyh01",
    "statuscode": 1, // 用户不存在，会有statusmsg
    "statusmsg": "no_exist"
}, {
    "devices": [{
        "login": false,
        "online": false,
        "platform": "a"
    }],
    "username": "Rauly",
    "statuscode": 0 // 用户存在
}]

此代码块在浮窗中显示

devices 设备登陆状态数组，没有登陆过数组为空
platform SDK 各平台：a-Android，i-iOS，j-JS，w-Windows

Error Code

错误码

899003 username 不合法

修改密码

PUT /v1/users/{username}/password

          PUT /v1/users/{username}/password

此代码块在浮窗中显示

Request Header

PUT /v1/users/javen/password

          PUT /v1/users/javen/password

此代码块在浮窗中显示

Example Request

{ "new_password": "654321" }

          {
     "new_password": "654321"
}

此代码块在浮窗中显示

Request Params

new_password （必填）新密码

Example Response

HTTP/1.1 204 NO Content Content-Type: application/json; charset=utf-8

          HTTP/1.1 204 NO Content
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Response Data

删除用户

DELETE /v1/users/{username}

          DELETE /v1/users/{username}

此代码块在浮窗中显示

Request Params

username 用户名。

Example Response

< HTTP/1.1 204 NO CONTENT < Content-Type: application/json; charset=utf-8

          < HTTP/1.1 204 NO CONTENT
< Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

批量删除用户

DELETE /v1/users/

          DELETE /v1/users/

此代码块在浮窗中显示

Request Body

["USER1","USER2"]

          ["USER1","USER2"]

此代码块在浮窗中显示

username 用户名数组。（最多支持同时删除 100 个用户）

Example Response

< HTTP/1.1 200 NO CONTENT < Content-Type: application/json; charset=utf-8

          < HTTP/1.1 200 NO CONTENT
< Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

添加黑名单

Put /v1/users/{username}/blacklist

          Put /v1/users/{username}/blacklist

此代码块在浮窗中显示

Example Request

Request Header

Put /v1/users/{username}/blacklist Content-Type: application/json; charset=utf-8

          Put /v1/users/{username}/blacklist
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Request Params

JsonArray
- username 的 JsonArray

Request Body

[ "test1", "test2" ]

          [
 "test1",
 "test2"
 ]

此代码块在浮窗中显示

Example Response

Response Header

HTTP/1.1 204 NO Content Content-Type: application/json; charset=utf-8

          HTTP/1.1 204 NO Content
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Response Data

N/A

移除黑名单

Delete /v1/users/{username}/blacklist

          Delete /v1/users/{username}/blacklist

此代码块在浮窗中显示

Example Request

Request Header

Delete /v1/users/{username}/blacklist Content-Type: application/json; charset=utf-8

          Delete /v1/users/{username}/blacklist
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Request Params

JsonArray
- username 的 JsonArray

Request Body

[ "test1", "test2" ]

          [
 "test1",
 "test2"
 ]

此代码块在浮窗中显示

Example Response

Response Header

HTTP/1.1 204 NO Content Content-Type: application/json; charset=utf-8

          HTTP/1.1 204 NO Content
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Response Data

N/A

黑名单列表

Get /v1/users/{username}/blacklist

          Get /v1/users/{username}/blacklist

此代码块在浮窗中显示

Example Request

Request Header

Put /v1/users/{username}/blacklist Content-Type: application/json; charset=utf-8

          Put /v1/users/{username}/blacklist
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Request Params

username 用户名

Request Body

N/A

Example Response

Response Header

HTTP/1.1 200 NO Content Content-Type: application/json; charset=utf-8

          HTTP/1.1 200 NO Content
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Response Data

[{ "username": "javen", "nickname": "hello", "avatar" = "/avatar", "birthday": "1990-01-24 00:00:00", "gender": 0, "signature": "orz", "region": "shenzhen", "address": "shenzhen", "mtime": "2015-01-01 00:00:00", "ctime": "2015-01-01 00:00:00" }]

          [{
    "username": "javen",
    "nickname": "hello",
    "avatar" = "/avatar",
    "birthday": "1990-01-24 00:00:00",
    "gender": 0,
    "signature": "orz",
    "region": "shenzhen",
    "address": "shenzhen",
    "mtime": "2015-01-01 00:00:00",
    "ctime": "2015-01-01 00:00:00"
}]

此代码块在浮窗中显示

获取用户列表

GET /v1/users/?start={start}&count={count}

          GET /v1/users/?start={start}&count={count}

此代码块在浮窗中显示

Request Params

start 开始的记录数
count 要获取的记录个数

Example Response

< HTTP/1.1 200 < Content-Type: application/json { "total": 12580, "start": 1100, "count": 100, "users": [{ "username": "cai", "nickname": "hello", "mtime": "2015-01-01 00:00:00", "ctime": "2015-01-01 00:00:00" }, { "username": "yi", "nickname": "hello", "mtime": "2015-01-01 00:00:00", "ctime": "2015-01-01 00:00:00" }, { "username": "huang", "nickname": "hello", "mtime": "2015-01-01 00:00:00", "ctime": "2015-01-01 00:00:00" } ] }

          < HTTP/1.1 200
< Content-Type: application/json

{
    "total": 12580,
    "start": 1100,
    "count": 100,
    "users": [{
            "username": "cai",
            "nickname": "hello",
            "mtime": "2015-01-01 00:00:00",
            "ctime": "2015-01-01 00:00:00"
        },
        {
            "username": "yi",
            "nickname": "hello",
            "mtime": "2015-01-01 00:00:00",
            "ctime": "2015-01-01 00:00:00"
        },
        {
            "username": "huang",
            "nickname": "hello",
            "mtime": "2015-01-01 00:00:00",
            "ctime": "2015-01-01 00:00:00"
        }
    ]
}

此代码块在浮窗中显示

免打扰

免打扰设置

POST /v1/users/{username}/nodisturb

          POST  /v1/users/{username}/nodisturb

此代码块在浮窗中显示

Example Request

Request Header

POST /v1/users/{username}/nodisturb Content-Type: application/json; charset=utf-8

          POST  /v1/users/{username}/nodisturb
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Request Params

single 单聊免打扰，支持 add remove 数组（可选）
group 群聊免打扰，支持 add remove 数组（可选）
global 全局免打扰，0 或 1 0 表示关闭，1 表示打开（可选）

Request Body

{ "single":{ "add":[ "username1", "username2" ] }, "group":{ "add":[ 110000101 ], "remove":[ 1000001111 ] }, "global":0 }

          {   
   "single":{   
      "add":[   
         "username1",
         "username2"
      ]
   },
   "group":{   
      "add":[   
         110000101
      ],
      "remove":[   
         1000001111
      ]
   },
   "global":0
}

此代码块在浮窗中显示

Example Response

Response Header

HTTP/1.1 204 NO Content Content-Type: application/json; charset=utf-8

          HTTP/1.1 204 NO Content
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Response Data

N/A

Error Code

899003 username 不合法；
899002 用户不存在；
899051 群组不存在；
899052 设置群组
屏蔽，设置的群组屏蔽已经打开
99053 设置群组消息屏蔽，设置的群组屏蔽已经关闭

禁用用户

PUT /v1/users/{username}/forbidden?disable={disable}

          PUT /v1/users/{username}/forbidden?disable={disable}

此代码块在浮窗中显示

Request Params

disable boolean,true 代表禁用用户，false 代表激活用户

Example Response

< HTTP/1.1 204 NO CONTENT < Content-Type: application/json

          < HTTP/1.1 204 NO CONTENT
< Content-Type: application/json

此代码块在浮窗中显示

消息相关

发送消息

POST /v1/messages

          POST /v1/messages

此代码块在浮窗中显示

参数	含义
version	版本号目前是1 （必填）
target_type	发送目标类型 single - 个人，group - 群组 chatroom - 聊天室（必填）
from_type	发送消息者的身份，可为“user” （必填）
msg_type	发消息类型 text - 文本，image - 图片, custom - 自定义消息（msg_body为json对象即可，服务端不做校验）voice - 语音（必填）
target_id	目标id single填username group 填Group id chatroom 填chatroomid（必填）
target_appkey	跨应用目标appkey（选填）
from_id	发送者的username （必填
from_name	发送者展示名（选填）
target_name	接受者展示名（选填）
no_offline	消息是否离线存储 true或者false，默认为false，表示需要离线存储（选填）
no_notification	消息是否在通知栏展示 true或者false，默认为false，表示在通知栏展示（选填）
notification	自定义通知栏展示（选填）
notification->title	通知的标题（选填）
notification->alert	通知的内容（选填）
msg_body	Json对象的消息体限制为4096byte
msg_type为text时，msg_body的格式如下
msg_body -> text	消息内容（必填）
msg_body-> extras	选填的json对象开发者可以自定义extras里面的key value（选填）
msg_type为image时,msg_body为上传图片返回的json，格式如下
msg_body->media_id	String 文件上传之后服务器端所返回的key，用于之后生成下载的url（必填）
msg_body->media_crc32	long 文件的crc32校验码，用于下载大图的校验（必填）
msg_body->width	int 图片原始宽度（必填）
msg_body->height	int 图片原始高度（必填）
msg_body->format	String 图片格式（必填）
msg_body->hash	String 图片hash值（可选）
msg_body->fsize	int 文件大小（字节数）（必填）
msg_type为voice时,msg_body为上传语音返回的json，格式如下
msg_body->media_id	String 文件上传之后服务器端所返回的key，用于之后生成下载的url（必填）
msg_body->media_crc32	long 文件的crc32校验码，用于下载大图的校验（必填）
msg_body->duration	int 音频时长（必填）
msg_body->hash	String 音频hash值（可选）
msg_body->fsize	int 文件大小（字节数）（必填）

Example Request

msg_type:text { "version": 1, "target_type": "single", "target_id": "javen", "from_type": "user", "from_id": "fang", "msg_type": "text", "msg_body": { "extras": {}, "text": "Hello, JMessage!" } } msg_type:image { "version": 1, "target_type": "single", "target_id": "javen", "from_type": "user", "from_id": "fang", "msg_type": "image", "msg_body": { "media_id": "qiniu/image/CE0ACD035CBF71F8", "media_crc32":2778919613, "width":3840, "height":2160, "fsize":3328738, "format":"jpg" } } msg_type:voice { "version": 1, "target_type": "single", "target_id": "ppppp", "from_type": "user", "from_id": "user_caiyh", "msg_type": "voice", "msg_body": { "media_id": "qiniu/voice/j/A96B61EB3AF0E5CDE66D377DEA4F76B8", "media_crc32":1882116055, "hash":"FoYn15bAGRUM9gZCAkvf9dolVH7h", "fsize" :12344; "duration": 6 } }

          msg_type:text
{
    "version": 1,
    "target_type": "single",
    "target_id": "javen",
    "from_type": "user",
    "from_id": "fang",
    "msg_type": "text",
    "msg_body": {
        "extras": {},
        "text": "Hello, JMessage!"
    }
}

msg_type:image
{
    "version": 1,
    "target_type": "single",
    "target_id": "javen",
    "from_type": "user",
    "from_id": "fang",
    "msg_type": "image",
    "msg_body": {
    "media_id": "qiniu/image/CE0ACD035CBF71F8",
    "media_crc32":2778919613,
    "width":3840,
    "height":2160,
    "fsize":3328738,
    "format":"jpg"
    }
}

msg_type:voice

{
    "version": 1,
    "target_type": "single",
    "target_id": "ppppp",
    "from_type": "user",
     "from_id": "user_caiyh",
    "msg_type": "voice",
    "msg_body": {
    "media_id": "qiniu/voice/j/A96B61EB3AF0E5CDE66D377DEA4F76B8",
    "media_crc32":1882116055,
    "hash":"FoYn15bAGRUM9gZCAkvf9dolVH7h",
    "fsize" :12344;
     "duration": 6
    }
}

此代码块在浮窗中显示

msg_type:custom { "version": 1, "target_type": "single", "target_id": "ppppp", "from_type": "user", "from_id": "user_caiyh", "msg_type": "voice", "msg_body": { json define yourself } }

          msg_type:custom

{
    "version": 1,
    "target_type": "single",
    "target_id": "ppppp",
    "from_type": "user",
     "from_id": "user_caiyh",
    "msg_type": "voice",
    "msg_body": {
           json define yourself
    }
}

此代码块在浮窗中显示

Request Params

JSON Object.
遵循协议文档：IM 消息协议

Example Response

< HTTP/1.1 201 Created < Content-Type: application/json < {"msg_id": 43143728109, "msg_ctime":1493794522950}

          < HTTP/1.1 201 Created
< Content-Type: application/json
<
{"msg_id": 43143728109, "msg_ctime":1493794522950}

此代码块在浮窗中显示

msg_ctime: 消息创建的时间戳

Error Code

899003 参数错误，Request Body 参数不符合要求
899002 用户不存在，target_id 或者 from_id 不存在
899016 from_id 没有权限发送 message

消息撤回

POST /v1/messages/{username}/{msgid}/retract

          POST /v1/messages/{username}/{msgid}/retract

此代码块在浮窗中显示

Example Request

Request Header

POST /v1/messages/{username}/{msgid}/retract

          POST /v1/messages/{username}/{msgid}/retract

此代码块在浮窗中显示

Request Body

N/A

Request Params

参数	含义	备注
msgid	消息 msgid
username	发送此 msg 的用户名

Example Response

Response Header

HTTP/1.1 204 No Content Content-Type: application/json; charset=utf-8

          HTTP/1.1 204 No Content
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Error Code • 855001 超出撤回消息时间有效撤回时间为消息发出后 3 分钟之内 • 855003 撤回消息不存在 • 855004 消息已经撤回

媒体文件下载与上传

文件下载

GET /v1/resource?mediaId={mediaId}

          GET /v1/resource?mediaId={mediaId}

此代码块在浮窗中显示

Example Request

Request Header

GET /v1/resource?mediaId={mediaId}

          GET /v1/resource?mediaId={mediaId}

此代码块在浮窗中显示

Request Body

N/A

Request Params

参数	含义	备注
mediaId	资源的 mediaId，包括用户的 avatar 字段

Example Response

Response Header

HTTP/1.1 200 no content Content-Type: application/json; charset=utf-8

          HTTP/1.1 200 no content
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Response Data

{"url":"http://........."}

          {"url":"http://........."}

此代码块在浮窗中显示

文件上传

POST /v1/resource?type=image

          POST /v1/resource?type=image

此代码块在浮窗中显示

Example Request

文件上传采用 form 表单上传 curl 示例: 图片上传 curl -F "filename=@/home/test.jpg" https://api.im.jpush.cn/v1/resource?type=image -u "appkey:secret"

文件上传 curl -F "filename=@/home/test.mp3" https://api.im.jpush.cn/v1/resource?type=file -u "appkey:secret"

语音上传 curl -F "filename=@/home/test.mp3" https://api.im.jpush.cn/v1/resource?type=voice -u "appkey:secret"

注：文件大小限制 8m，暂时只支持图片格式 jpg bmp gif png 等

参数	含义	备注
filename	磁盘本地文件路径
type	文件类型支持是"image", "file", "voice"

Response Header

Example Response

HTTP/1.1 200 Content-Type: application/json; charset=utf-8

          HTTP/1.1 200
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Response Data 图片 Response

{ "media_id": "qiniu/image/F39AA12204DAB6A2", "media_crc32": 1338734977, "width": 720, "height": 1280, "format": "jpg", "fsize": 52468 }

          {
    "media_id": "qiniu/image/F39AA12204DAB6A2",
    "media_crc32": 1338734977,
    "width": 720,
    "height": 1280,
    "format": "jpg",
    "fsize": 52468
}

此代码块在浮窗中显示

media_id String 文件上传之后服务器端所返回的 key
media_crc32 long 文件的 crc32 校验码
width int 图片原始宽度
height int 图片原始高度
format String 图片格式
fsize int 文件大小（字节数）
hash String 可选，用于 crc 校验码不存在时的替代的验证

文件 Response

{ "media_id": "qiniu/file/j/1BB3B833AEABFF62E883C5CE421867A9", "media_crc32": 1415584260, "fname": "0839d1c0-48e9-4032-9333-f3691a7d9e48.dmp", "fsize": 176512, "hash": "FtH0kPT0YI89HAw1K9wv_vVKiNab" }

          {
    "media_id": "qiniu/file/j/1BB3B833AEABFF62E883C5CE421867A9",
    "media_crc32": 1415584260,
    "fname": "0839d1c0-48e9-4032-9333-f3691a7d9e48.dmp",
    "fsize": 176512,
    "hash": "FtH0kPT0YI89HAw1K9wv_vVKiNab"
}

此代码块在浮窗中显示

media_id String 文件上传之后服务器端所返回的 key，用于之后生成下载的 url
media_crc32 long 文件的 crc32 校验码
hash String 可选，用于 crc 校验码不存在时的替代的验证
fsize int 文件大小（字节数）
fname String 发送与接收到的文件名

语音 Response

{ "media_id": "qiniu/voice/j/9C4312B1EA0FB28337566D1A29A244B5", "media_crc32": 1882116055, "hash": "FoYn15bAGRUM9gZCAkvf9dolVH7h", "format": "m4a", "fsize": 238105 }

          {
    "media_id": "qiniu/voice/j/9C4312B1EA0FB28337566D1A29A244B5",
    "media_crc32": 1882116055,
    "hash": "FoYn15bAGRUM9gZCAkvf9dolVH7h",
    "format": "m4a",
    "fsize": 238105
}

此代码块在浮窗中显示

media_id String 文件上传之后服务器端所返回的 key，用于之后生成下载的 url
media_crc32 long 文件的 crc32 校验码
hash String 可选，用于 crc 校验码不存在时的替代的验证
fsize int 文件大小（字节数）
format String 源文件格式

Group 对象字段总览

参数	含义	字符长度限制
name	群组名称	Byte(0~64)
desc	群组描述	Byte(0~250)
owner_username	群主的username	Byte(4-128)
MaxMemberCount	群组默认500人
ctime	创建时间
mtime	最后修改时间
avatar	群组头像

群组维护

创建群组

POST /v1/groups/

          POST /v1/groups/

此代码块在浮窗中显示

群组 MaxMemberCount（人数限制）定义

Example Request

{ "owner_username": "tom", "name": "群聊天室", "members_username": ["eddie", "annie"], "flag": 1, "desc": "运动" }

          {
    "owner_username": "tom",
    "name": "群聊天室",
    "members_username": ["eddie", "annie"],
    "flag": 1,
    "desc": "运动"
}

此代码块在浮窗中显示

Request Params

owner_username （必填）群主 username
name （必填）群组名字
- 支持的字符：全部，包括 Emoji。
members_username 成员 username
avatar （选填）群组头像，上传接口所获得的 media_id
desc （选填）群描述
- 支持的字符：全部，包括 Emoji。
flag （选填）类型
- 1 - 私有群（默认）
- 2 - 公开群
- 不指定 flag，默认为 1

Example Response

< HTTP/1.1 201 Created < Content-Type: application/json < { "gid":12345, "owner_username": 123456, "name": "display_name", "members_username": [], "desc":"doubi", "MaxMemberCount" = 500 }

          < HTTP/1.1 201 Created
< Content-Type: application/json
<

{
    "gid":12345,
    "owner_username": 123456,
    "name": "display_name",
    "members_username": [],
    "desc":"doubi",
    "MaxMemberCount" = 500
}

此代码块在浮窗中显示

获取群组详情

GET /v1/groups/{Group id}

          GET /v1/groups/{Group id}

此代码块在浮窗中显示

Request Params

Group id 群组 ID。由创建群组时分配。

Example Response

< HTTP/1.1 200 OK < Content-Type: application/json < { "gid": 12345, "name" : "jpush", "desc" : "push", "appkey" : "dcf71ef5082057832bd44fbd", "MaxMemberCount" : 500, "mtime" : "2014-07-01 00:00:00", "ctime" : "2014-06-05 00:00:00" }

          < HTTP/1.1 200 OK
< Content-Type: application/json
<

{
      "gid": 12345,
      "name" : "jpush",
      "desc" : "push",
      "appkey" : "dcf71ef5082057832bd44fbd",
      "MaxMemberCount" : 500,
      "mtime" : "2014-07-01 00:00:00",
      "ctime" : "2014-06-05 00:00:00"
}

此代码块在浮窗中显示

更新群组信息

PUT /v1/groups/{Group id}

          PUT /v1/groups/{Group id}

此代码块在浮窗中显示

Request Params

name 群名称
desc 群描述
avatar 群组头像 media_id

PUT /v1/groups/{Group id}

          PUT /v1/groups/{Group id}

此代码块在浮窗中显示

Request Body

{ "the key you want to update" : "the value you want to update" }

          { "the key you want to update" : "the value you want to update" }

此代码块在浮窗中显示

Example Response

HTTP/1.1 204 NO Content

          HTTP/1.1 204 NO Content

此代码块在浮窗中显示

删除群组

删除某个群组。

该群组的所有成员都会收到群组被解散通知。

DELETE /v1/groups/{Group id}

          DELETE /v1/groups/{Group id}

此代码块在浮窗中显示

Request Params

Group id 群组 ID。

Example Response

< HTTP/1.1 204 NO CONTENT < Content-Type: application/json

          < HTTP/1.1 204 NO CONTENT
< Content-Type: application/json

此代码块在浮窗中显示

更新群组成员

批量增加与删除某 gid 群组的成员。

群组成员将收到增加与删除成员的通知。

POST /v1/groups/{Group id}/members

          POST /v1/groups/{Group id}/members

此代码块在浮窗中显示

Request Params

gid 群组 ID
add json 数组表示要添加到群组的用户(可选)
remove json 数组表示要从群组删除的用户（可选）
两者至少要有一个

Example Request

{ "add":[ "test1", "test2" ], "remove":[ "test3", "test4" ] }

          {
    "add":[
        "test1", "test2"
    ],
    "remove":[
        "test3", "test4"
    ]
}

此代码块在浮窗中显示

Example Response

< HTTP/1.1 204 NO CONTENT < Content-Type: application/json

          < HTTP/1.1 204 NO CONTENT
< Content-Type: application/json

此代码块在浮窗中显示

添加群组成员 V2

批量增加群组的成员。

群组成员将收到增加的通知。

POST /v2/groups/{Group id}/addMembers

          POST /v2/groups/{Group id}/addMembers

此代码块在浮窗中显示

Request Params

gid 群组 ID

Example Request

["test1", "test2"]

          ["test1", "test2"]

此代码块在浮窗中显示

Example Response

< HTTP/1.1 204 NO CONTENT < Content-Type: application/json

          < HTTP/1.1 204 NO CONTENT
< Content-Type: application/json

此代码块在浮窗中显示

删除群组成员 V2

批量删除群组的成员。

群组成员将收到删除的通知。

POST /v2/groups/{Group id}/delMembers

          POST /v2/groups/{Group id}/delMembers

此代码块在浮窗中显示

Request Params

gid 群组 ID

Example Request

["test1", "test2"]

          ["test1", "test2"]

此代码块在浮窗中显示

Example Response

< HTTP/1.1 204 NO CONTENT < Content-Type: application/json

          < HTTP/1.1 204 NO CONTENT
< Content-Type: application/json

此代码块在浮窗中显示

获取群组成员列表

GET /v1/groups/{Group id}/members/

          GET /v1/groups/{Group id}/members/

此代码块在浮窗中显示

Request Params

Group id 群组 ID。

Example Response

JsonObject UID 数组

< HTTP/1.1 200 OK < Content-Type: application/json; charset=utf-8 [{ "username": "javen", "nickname": "hello", "avatar" = "/avatar", "birthday": "1990-01-24 00:00:00", "gender": 0, "signature": "orz", "region": "shenzhen", "address": "shenzhen", "flag": 0 }]

          < HTTP/1.1 200 OK
< Content-Type: application/json; charset=utf-8

[{
    "username": "javen",
    "nickname": "hello",
    "avatar" = "/avatar",
    "birthday": "1990-01-24 00:00:00",
    "gender": 0,
    "signature": "orz",
    "region": "shenzhen",
    "address": "shenzhen",
    "flag": 0
}]

此代码块在浮窗中显示

flag
- 0 - 普通群成员
- 1 - 群主

获取某用户的群组列表

GET /v1/users/{username}/groups/

          GET /v1/users/{username}/groups/

此代码块在浮窗中显示

Request Params

username 用户名。

Example Response

ctime 群组
创建时间
mtime 群组最后修改时间

< HTTP/1.1 200 OK < Content-Type: application/json [{ "gid": 12345, "name": "jpush", "desc": "push", "appkey": "dcf71ef5082057832bd44fbd", "MaxMemberCount": 500, "mtime": "2014-07-01 00:00:00", "ctime": "2014-06-05 00:00:00" }]

          < HTTP/1.1 200 OK
< Content-Type: application/json

[{
    "gid": 12345,
    "name": "jpush",
    "desc": "push",
    "appkey": "dcf71ef5082057832bd44fbd",
    "MaxMemberCount": 500,
    "mtime": "2014-07-01 00:00:00",
    "ctime": "2014-06-05 00:00:00"
}]

此代码块在浮窗中显示

获取当前应用的群组列表

GET /v1/groups/?start={start}&count={count}

          GET /v1/groups/?start={start}&count={count}

此代码块在浮窗中显示

Request Params

start 开始的记录数。
count 本次读取的记录数量。最大值为 500

Example Response

< HTTP/1.1 200 OK < Content-Type: application/json { "total": 1233, "start": 1100, "count": 1, "groups": [{ "gid": 12345, "name": "jpush", "desc": "push", "appkey": "dcf71ef5082057832bd44fbd", "MaxMemberCount": 500, "mtime": "2014-07-01 00:00:00", "ctime": "2014-06-05 00:00:00" }] }

          < HTTP/1.1 200 OK
< Content-Type: application/json

{
    "total": 1233,
    "start": 1100,
    "count": 1,
    "groups": [{
        "gid": 12345,
        "name": "jpush",
        "desc": "push",
        "appkey": "dcf71ef5082057832bd44fbd",
        "MaxMemberCount": 500,
        "mtime": "2014-07-01 00:00:00",
        "ctime": "2014-06-05 00:00:00"
    }]
}

此代码块在浮窗中显示

群消息屏蔽

POST /v1/users/{username}/groupsShield

          POST /v1/users/{username}/groupsShield

此代码块在浮窗中显示

Request Params

N/A

Example Request Body

{ "add": [ 110000101], "remove": [ 1000001111] }

          {         
    "add": [ 110000101],
    "remove": [ 1000001111]
}

此代码块在浮窗中显示

参数	含义
add	添加群消息屏蔽的 gid 数组（可选）
remove	移除群消息屏蔽的 gid 数组（可选）

Example Response

< HTTP/1.1 204 OK < Content-Type: application/json

          < HTTP/1.1 204 OK
< Content-Type: application/json

此代码块在浮窗中显示

群成员禁言

PUT /groups/messages/{gid}/silence?status={status}

          PUT  /groups/messages/{gid}/silence?status={status}

此代码块在浮窗中显示

Request body

[ "username1", "username2"] 备注：username json数组

          [ "username1", "username2"]
备注：username json数组

此代码块在浮窗中显示

Request Params

status：开启或关闭禁言 true表示开启 false表示关闭

          status：开启或关闭禁言 true表示开启 false表示关闭

此代码块在浮窗中显示

Example Response

< HTTP/1.1 204 OK < Content-Type: application/json

          < HTTP/1.1 204 OK
< Content-Type: application/json

此代码块在浮窗中显示

移交群主

PUT /groups/owner/{gid}

          PUT  /groups/owner/{gid}

此代码块在浮窗中显示

Request body

{ "appkey":"xxxxxxx", "username": "xxxxxxx" } 注：跨应用下的用户或者 { "username": "xxxxxxx" } 注：本应用下的用户

          {
    "appkey":"xxxxxxx",
    "username": "xxxxxxx"
}
 注：跨应用下的用户

或者

{
    "username": "xxxxxxx"
}
注：本应用下的用户

此代码块在浮窗中显示

Request Params

Example Response

HTTP/1.1 204 NO Content

          HTTP/1.1 204 NO Content

此代码块在浮窗中显示

Error Code

899003 gid 不合法；Request Body json 格式不符合要求，json 参数不符合要求；
899006 gid 不存在；

好友

添加好友

POST /v1/users/{username}/friends

          POST  /v1/users/{username}/friends

此代码块在浮窗中显示

Request Params

json 数组表示要添加的用户名列表最大限制 500 个

Example Request

["user01","user02"]

          ["user01","user02"]

此代码块在浮窗中显示

Example Response

< HTTP/1.1 201 < Content-Type: application/json; charset=utf-8

          < HTTP/1.1 201
< Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Response Data N/A

Error Code

899003 Request Body json 格式不符合要求，json 参数不符合要求；
899002 用户不存在；
899070 已经添加了好友；

删除好友

DELETE /v1/users/{username}/friends

          DELETE  /v1/users/{username}/friends

此代码块在浮窗中显示

Request Params

json 数组表示要删除的用户名列表最大限制 500 个

Example Request

["user01","user02"]

          ["user01","user02"]

此代码块在浮窗中显示

Example Response

< HTTP/1.1 204 NO Content < Content-Type: application/json; charset=utf-8

          < HTTP/1.1 204 NO Content
< Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Response Data N/A

Error Code

899003 Request Body json 格式不符合要求，json 参数不符合要求；
899002 用户不存在；

更新好友备注

PUT /v1/users/{username}/friends

            PUT  /v1/users/{username}/friends

此代码块在浮窗中显示

Request Params

note_name 表示要添加的好友列表，格式：Byte(64) 支持的字符：不包括 "\n" "\r"。
others 其他备注信息，格式：Byte(250) 支持的字符：全部，包括 Emoji。
username 用户 username；
支持批量修改最大限制 500 个

Example Request

[{ "note_name": "new note name", "others": “好友备注文档 " ," username ":" user01 " }]

          [{
        "note_name": "new note name",
        "others": “好友备注文档 " ,"
        username ":"
        user01 "
}]

此代码块在浮窗中显示

Example Response

< HTTP/1.1 204 NO Content < Content-Type: application/json; charset=utf-8

          < HTTP/1.1 204 NO Content
< Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Response Data N/A

Error Code

899003 Request Body json 格式不符合要求，json 参数不符合要求；
899002 用户不存在；

获取好友列表

GET /v1/users/{username}/friends

           GET  /v1/users/{username}/friends

此代码块在浮窗中显示

Request Params

N/A

Example Request

Example Response

< HTTP/1.1 200 NO Content < Content-Type: application/json; charset=utf-8

          < HTTP/1.1 200 NO Content
< Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Response Data

          [{
    "username": "javen",
    "nickname": "hello",
    "avatar" = "/avatar",
    "birthday": "1990-01-24 00:00:00",
    "gender": 0,
    "signature": "orz",
    "region": "shenzhen",
    "address": "shenzhen",
    "mtime": "2015-01-01 00:00:00",
    "ctime": "2015-01-01 00:00:00",
    "note_name": "= =",
    "others": "test",
    "appkey": "pojkasouduioadk"
}]

此代码块在浮窗中显示

Error Code

899003 Request Body json 格式不符合要求，json 参数不符合要求；
899002 用户不存在；

跨应用

跨应用管理群组成员

POST /v1/cross/groups/{gid}/members

          POST  /v1/cross/groups/{gid}/members

此代码块在浮窗中显示

Request Params

add json 数组表示要添加到群组的用户(可选)
remove json 数组表示要从群组删除的用户（可选）
appkey 管理用户所属的 appkey 必填

add remove 两者至少要有一个

Example Request

[{ "appkey":" 4f7aef34fb361292c566a1cd", "add": [ "test1", "test2" ], "remove": [ "name3", "name4" ] }]

          [{
 "appkey":" 4f7aef34fb361292c566a1cd",
 "add": [
 "test1",
 "test2"
 ],
 "remove": [
 "name3",
 "name4"
 ]
}]

此代码块在浮窗中显示

Example Response

< HTTP/1.1 204 NO Content < Content-Type: application/json; charset=utf-8

          < HTTP/1.1 204 NO Content
< Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Response Data N/A

备注：当群组没有成员的时候群会被删除 Error Code

899003 Request Body json 格式不符合要求，json 参数不符合要求；
899002 用户不存在；
899012 没有足够的位置添加群成员；
899014 用户不存在于群组；
899011 用户已经存在于群组；

跨应用获取群组成员列表

GET /v1/cross/groups/{Group id}/members/

          GET /v1/cross/groups/{Group id}/members/

此代码块在浮窗中显示

Request Params

Group id 群组 ID。

Example Response

JsonObject UID 数组

          < HTTP/1.1 200 OK
< Content-Type: application/json; charset=utf-8

[{
    "username": "javen",
    "nickname": "hello",
    "avatar" = "/avatar",
    "birthday": "1990-01-24 00:00:00",
    "gender": 0,
    "signature": "orz",
    "region": "shenzhen",
    "address": "shenzhen",
    "flag": 0,
    "appkey": "appkey"
}]

此代码块在浮窗中显示

flag
- 0 - 普通群成员
- 1 - 群主

跨应用获取用户群组

GET /v1/cross/users/{username}/groups

          GET /v1/cross/users/{username}/groups

此代码块在浮窗中显示

Request Params

username 用户名

Example Response

< HTTP/1.1 200 OK < Content-Type: application/json; charset=utf-8 [{ "gid": 12345, "name": "jpush", "desc": "push", "appkey": "dcf71ef5082057832bd44fbd", "max_member_count": 200, "mtime": "2014-07-01 00:00:00", "ctime": "2014-06-05 00:00:00", "appkey": "appkey" }]

          < HTTP/1.1 200 OK
< Content-Type: application/json; charset=utf-8
[{
    "gid": 12345,
    "name": "jpush",
    "desc": "push",
    "appkey": "dcf71ef5082057832bd44fbd",
    "max_member_count": 200,
    "mtime": "2014-07-01 00:00:00",
    "ctime": "2014-06-05 00:00:00",
    "appkey": "appkey"
}]

此代码块在浮窗中显示

跨应用添加黑名单

Put /v1/cross/users/{username}/blacklist

          Put /v1/cross/users/{username}/blacklist

此代码块在浮窗中显示

Example Request

Request Header

Put /v1/cross/users/{username}/blacklist Content-Type: application/json; charset=utf-8

          Put /v1/cross/users/{username}/blacklist
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Request Params

username 添加的用户的数组
appkey 用户所属的 appkey

Request Body

[{ "appkey": "appkey", "usernames": ["test1", "test2"] }]

          [{
    "appkey": "appkey",
    "usernames": ["test1", "test2"]
}]

此代码块在浮窗中显示

Example Response

Response Header

HTTP/1.1 204 NO Content Content-Type: application/json; charset=utf-8

          HTTP/1.1 204 NO Content
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Response Data

N/A

跨应用移除黑名单

Delete /v1/cross/users/{username}/blacklist

          Delete /v1/cross/users/{username}/blacklist

此代码块在浮窗中显示

Example Request

Request Header

Delete /v1/cross/users/{username}/blacklist Content-Type: application/json; charset=utf-8

          Delete /v1/cross/users/{username}/blacklist
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Request Params

username 移除的用户的数组
appkey 用户所属的 appkey

Request Body

[{ "appkey":"appkey", "usernames":[ "test1", "test2"] } ]

           [{
 "appkey":"appkey",
 "usernames":[ "test1", "test2"]
 } ]

此代码块在浮窗中显示

Example Response

Response Header

HTTP/1.1 204 NO Content Content-Type: application/json; charset=utf-8

          HTTP/1.1 204 NO Content
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Response Data

N/A

跨应用黑名单列表

Get /v1/cross/users/{username}/blacklist

          Get /v1/cross/users/{username}/blacklist

此代码块在浮窗中显示

Example Request

Request Header

Get /v1/cross/users/{username}/blacklist Content-Type: application/json; charset=utf-8

          Get /v1/cross/users/{username}/blacklist
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Request Params

username 用户名

Request Body

N/A

Example Response

Response Header

HTTP/1.1 200 Content-Type: application/json; charset=utf-8

          HTTP/1.1 200
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Response Data

          [{
    "username": "javen",
    "nickname": "hello",
    "avatar" = "/avatar",
    "birthday": "1990-01-24 00:00:00",
    "gender": 0,
    "signature": "orz",
    "region": "shenzhen",
    "address": "shenzhen",
    "mtime": "2015-01-01 00:00:00",
    "ctime": "2015-01-01 00:00:00",
    "appkey": "appkey"
}]

此代码块在浮窗中显示

跨应用免打扰设置

POST /v1/cross/users/{username}/nodisturb

          POST  /v1/cross/users/{username}/nodisturb

此代码块在浮窗中显示

Example Request

Request Header

POST /v1/cross/users/{username}/nodisturb Content-Type: application/json; charset=utf-8

          POST  /v1/cross/users/{username}/nodisturb
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Request Params

single 单聊免打扰，支持 add remove 数组（可选）
group 群聊免打扰，支持 add remove 数组（可选）
appkey 目标的 appkey

Request Body

[{ "appkey":"appkey1", "single":{ "add":[ "username1", "username2" ] }, "group":{ "add":[ 110000101 ], "remove":[ 1000001111 ] } } ]

          [{
   "appkey":"appkey1",
   "single":{
      "add":[
         "username1",
         "username2"
      ]
   },
   "group":{
      "add":[
         110000101
      ],
      "remove":[
         1000001111
      ]
   }
}
]

此代码块在浮窗中显示

Example Response

Response Header

HTTP/1.1 204 NO Content Content-Type: application/json; charset=utf-8

          HTTP/1.1 204 NO Content
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Response Data

N/A

Error Code

899003 username 不合法；
899002 用户不存在；
899051 群组不存在；
899052 设置群组消息屏蔽，设置的群组屏蔽已经打开
899053 设置群组消息屏蔽，设置的群组屏蔽已经关闭

跨应用添加好友

POST /v1/cross/users/{username}/friends

          POST  /v1/cross/users/{username}/friends

此代码块在浮窗中显示

Example Request

Request Header

POST /v1/cross/users/{username}/friends Content-Type: application/json; charset=utf-8

          POST  /v1/cross/users/{username}/friends
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Request Params

appkey 用户所属的 appkey （必填）
users username 的 json 数组最多 500 个（必填）

Request Body

{ "appkey": "appkey", "users": ["user01", "user02"] }

          {
    "appkey": "appkey",
    "users": ["user01", "user02"]
}

此代码块在浮窗中显示

Example Response

Response Header

HTTP/1.1 201 Created Content-Type: application/json; charset=utf-8

          HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Response Data

N/A

跨应用删除好友

DELETE /v1/cross/users/{username}/friends

          DELETE  /v1/cross/users/{username}/friends

此代码块在浮窗中显示

Example Request

Request Header

DELETE /v1/cross/users/{username}/friends Content-Type: application/json; charset=utf-8

          DELETE  /v1/cross/users/{username}/friends
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Request Params

appkey 用户所属的 appkey （必填）
users username 的 json 数组最多 500 个（必填）

Request Body

{ "appkey": "appkey", "users": ["user01", "user02"] }

          
{
    "appkey": "appkey",
    "users": ["user01", "user02"]
}

此代码块在浮窗中显示

Example Response

Response Header

HTTP/1.1 204 NO Content Content-Type: application/json; charset=utf-8

          HTTP/1.1 204 NO Content
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Response Data

N/A

跨应用更新好友备注

PUT /v1/cross/users/{username}/friends

          PUT  /v1/cross/users/{username}/friends

此代码块在浮窗中显示

Example Request

Request Header

PUT /v1/cross/users/{username}/friends Content-Type: application/json; charset=utf-8

          PUT  /v1/cross/users/{username}/friends
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Request Params

appkey 用户所属的 appkey （必填）
note_name 表示要添加的好友列表，格式：Byte(64) 支持的字符：不包括 "\n" "\r"。
others 其他备注信息，格式：Byte(250) 支持的字符：全部，包括 Emoji。

Request Body

[{ "note_name": "new note name", "others": “好友备注文档 " ," username ":" user01 ", " appkey ":" appkey " }]

          [{
        "note_name": "new note name",
        "others": “好友备注文档 " ,"
        username ":"
        user01 ", "
        appkey ":"
        appkey "
}]

此代码块在浮窗中显示

Example Response

Response Header

HTTP/1.1 204 NO Content Content-Type: application/json; charset=utf-8

          HTTP/1.1 204 NO Content
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Response Data

N/A

跨应用管理聊天室成员

POST /cross/chatroom/{room_id}/members

          POST  /cross/chatroom/{room_id}/members

此代码块在浮窗中显示

Request Params

add json 数组表示要添加到聊天室的用户(可选)
remove json 数组表示要从聊天室删除的用户（可选）
appkey 管理用户所属的 appkey 必填

add remove 两者至少要有一个

Example Request

[{ "appkey":" 4f7aef34fb361292c566a1cd", "add": [ "test1", "test2" ], "remove": [ "name3", "name4" ] }]

          [{
 "appkey":" 4f7aef34fb361292c566a1cd",
 "add": [
 "test1",
 "test2"
 ],
 "remove": [
 "name3",
 "name4"
 ]
}]

此代码块在浮窗中显示

Example Response

< HTTP/1.1 204 NO Content < Content-Type: application/json; charset=utf-8

          < HTTP/1.1 204 NO Content
< Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Response Data

N/A

敏感词

添加敏感词

POST /v1/sensitiveword

          POST  /v1/sensitiveword

此代码块在浮窗中显示

Example Request

Request Header

POST /v1/sensitiveword Content-Type: application/json; charset=utf-8

          POST  /v1/sensitiveword
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Request Params N/A

Request Body

敏感词数组一个词长度最多为 10，默认支持 100 个敏感词，有更高需求可联系商务

["FUCK"]

          ["FUCK"]

此代码块在浮窗中显示

Example Response

Response Header

HTTP/1.1 204 NO Content Content-Type: application/json; charset=utf-8

          HTTP/1.1 204 NO Content
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Response Data

N/A

修改敏感词

PUT /v1/sensitiveword

          PUT  /v1/sensitiveword

此代码块在浮窗中显示

Example Request

Request Header

PUT /v1/sensitiveword Content-Type: application/json; charset=utf-8

          PUT  /v1/sensitiveword
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Request Params

N/A

Request Body

old_word 旧敏感词
new_word 新敏感词

{ "new_word": "fuck", "old_word": "FUCK" }

          {
    "new_word": "fuck",
    "old_word": "FUCK"
}

此代码块在浮窗中显示

Example Response

Response Header

HTTP/1.1 204 NO Content Content-Type: application/json; charset=utf-8

          HTTP/1.1 204 NO Content
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Response Data

N/A

删除敏感词

DELETE /v1/sensitiveword

          DELETE /v1/sensitiveword

此代码块在浮窗中显示

Example Request

Request Header

DELETE /v1/sensitiveword Content-Type: application/json; charset=utf-8

          DELETE  /v1/sensitiveword
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Request Params

N/A

Request Body

word 被删除的敏感词

{"word":"fuck"}

          {"word":"fuck"}

此代码块在浮窗中显示

Example Response

Response Header

HTTP/1.1 204 NO Content Content-Type: application/json; charset=utf-8

          HTTP/1.1 204 NO Content
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Response Data

N/A

获取敏感词列表

GET /v1/sensitiveword

          GET /v1/sensitiveword

此代码块在浮窗中显示

Example Request

Request Header

GET /v1/sensitiveword?start={start}&count={count} Content-Type: application/json; charset=utf-8

          GET  /v1/sensitiveword?start={start}&count={count}
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Request Params

start：起始序号从 0 开始
count: 查询条数，最多 2000

Request Body

N/A

Example Response

Response Header

HTTP/1.1 200 Content-Type: application/json; charset=utf-8

          HTTP/1.1 200
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Response Data

{ "start": 2, "count": 1, "words": [ { "name": "fuck", "itime": "1970-01-17 16:49:11" } ], "total": 3 }

          {
"start": 2,
"count": 1,
"words": [
{
"name": "fuck",
"itime": "1970-01-17 16:49:11"
}
],
"total": 3
}

此代码块在浮窗中显示

更新敏感词功能状态

PUT /v1/sensitiveword/status

          PUT /v1/sensitiveword/status

此代码块在浮窗中显示

Example Request

Request Header

PUT /v1/sensitiveword/status?status=0 Content-Type: application/json; charset=utf-8

          PUT  /v1/sensitiveword/status?status=0
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Request Params

status : 敏感词开关状态， 1 表示开启过滤， 0 表示关闭敏感词过滤

Request Body

N/A

Example Response

Response Header

HTTP/1.1 204 Content-Type: application/json; charset=utf-8

          HTTP/1.1 204
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Response Data

N/A

获取敏感词功能状态

GET /v1/sensitiveword/status

          GET /v1/sensitiveword/status

此代码块在浮窗中显示

Example Request

Request Header

GET /v1/sensitiveword/status Content-Type: application/json; charset=utf-8

          GET  /v1/sensitiveword/status
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Request Params

N/A

Request Body

N/A

Example Response

Response Header

HTTP/1.1 200 Content-Type: application/json; charset=utf-8

          HTTP/1.1 200
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

Response Data

{"status": 1}

           {"status": 1}

此代码块在浮窗中显示

聊天室字段总览

参数	含义	字符长度限制
name	聊天室名字（必填)	Byte(0~64)
owner_username	聊天室创建者（必填）	Byte (4~128)
description	聊天室描述（选填）	Byte(250)
members_username	聊天室成员列表（选填）
ctime	创建时间
max_member_count	最大成员数
total_member_count	当前总人数
flag	禁言标志	0表示不禁言 1表示开启禁言

聊天室维护

创建聊天室

POST /v1/chatroom/

          POST /v1/chatroom/

此代码块在浮窗中显示

Request Body

{ "owner_username": "liming", "name": "测试聊天室", "description": "测试", "members_username": [] }

          {
    "owner_username": "liming",
    "name": "测试聊天室",
    "description": "测试",
    "members_username": []
}

此代码块在浮窗中显示

Request Params

owner_username （必填）聊天室拥有者
name （必填）聊天室名称
members_username （选填）成员 username
description （选填）描述

Example Response

HTTP/1.1 201 Created Content-Type: application/json { "chatroom_id": 1000000 }

           HTTP/1.1 201 Created
 Content-Type: application/json

{
"chatroom_id": 1000000
}

此代码块在浮窗中显示

获取聊天室详情

POST /v1/chatroom/batch

          POST /v1/chatroom/batch

此代码块在浮窗中显示

Request Params

[10000001,10000002] roomid数组

          [10000001,10000002] roomid数组

此代码块在浮窗中显示

Example Response

HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 [ { "id": 10000001, "owner_username": "xiaoming", "max_member_count": 10000, "appkey": "4f7aef34fb361292c566a1cd", "name": "test", "description": "test", "total_member_count": 2, "ctime": "2017-11-27 18:38:25" }， { "id": 10000002, "owner_username": "xiaoming", "max_member_count": 10000, "appkey": "4f7aef34fb361292c566a1cd", "name": "test", "description": "test", "total_member_count": 2, "ctime": "2017-11-27 18:38:25" } ]

          HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
    {
        "id": 10000001,
        "owner_username": "xiaoming",
        "max_member_count": 10000,
        "appkey": "4f7aef34fb361292c566a1cd",
        "name": "test",
        "description": "test",
        "total_member_count": 2,
        "ctime": "2017-11-27 18:38:25"
    }，
 {
        "id": 10000002,
        "owner_username": "xiaoming",
        "max_member_count": 10000,
        "appkey": "4f7aef34fb361292c566a1cd",
        "name": "test",
        "description": "test",
        "total_member_count": 2,
        "ctime": "2017-11-27 18:38:25"
    }
]

此代码块在浮窗中显示

GET 获取用户聊天室列表

GET /v1/users/{username}/chatroom

           GET /v1/users/{username}/chatroom

此代码块在浮窗中显示

Example Request

GET /v1/users/xiaoming/chatroom

          GET /v1/users/xiaoming/chatroom

此代码块在浮窗中显示

Example Response

HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 [ { "id": 100000, "owner_username": "xiaoming", "max_member_count": 10000, "appkey": "4f7aef34fb361292c566a1cd", "name": "test", "description": "test", "total_member_count": 2， "ctime": "2017-11-27 18:38:25" }， { "id": 10000001, "owner_username": "xiaoming", "max_member_count": 10000, "appkey": "4f7aef34fb361292c566a1cd", "name": "test", "description": "test", "total_member_count": 2， "ctime": "2017-11-27 18:38:25" } ]

          HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
    {
        "id": 100000,
        "owner_username": "xiaoming",
        "max_member_count": 10000,
        "appkey": "4f7aef34fb361292c566a1cd",
        "name": "test",
        "description": "test",
        "total_member_count": 2，
       "ctime": "2017-11-27 18:38:25"
    }，
 {
        "id": 10000001,
        "owner_username": "xiaoming",
        "max_member_count": 10000,
        "appkey": "4f7aef34fb361292c566a1cd",
        "name": "test",
        "description": "test",
        "total_member_count": 2，
        "ctime": "2017-11-27 18:38:25"
    }
]

此代码块在浮窗中显示

GET 获取应用下聊天室列表

GET /v1/chatroom?start={start}&count={count}

          GET /v1/chatroom?start={start}&count={count}

此代码块在浮窗中显示

Example Request

GET /v1/chatroom?start=0&count=10

          GET  /v1/chatroom?start=0&count=10

此代码块在浮窗中显示

Example Response

HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 { "total": 1, "rooms": [ { "id": 62, "owner_username": "xiaoming", "max_member_count": 10000, "appkey": "4f7aef34fb361292c566a1cd", "name": "test", "description": "test"， total_member_count": 11, "ctime": "2017-11-27 18:38:25" } ], "start": 0, "count": 1 }

          HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "total": 1,
    "rooms": [
        {
            "id": 62,
            "owner_username": "xiaoming",
            "max_member_count": 10000,
            "appkey": "4f7aef34fb361292c566a1cd",
            "name": "test",
            "description": "test"，
             total_member_count": 11,
            "ctime": "2017-11-27 18:38:25"
        }
    ],
    "start": 0,
    "count": 1
}

此代码块在浮窗中显示

更新聊天室信息

PUT /v1/chatroom/{room_id}

           PUT /v1/chatroom/{room_id}

此代码块在浮窗中显示

Example Request

PUT /v1/chatroom/111000001

           PUT /v1/chatroom/111000001

此代码块在浮窗中显示

Request Body

{ "owner_username": "135380113231", "name": "中国人", "description": "说什么来这" }

          {
    "owner_username": "135380113231",
    "name": "中国人",
    "description": "说什么来这"
}

此代码块在浮窗中显示

Example Response

HTTP/1.1 204 Content-Type: application/json; charset=utf-8

          HTTP/1.1 204
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

删除聊天室

DELETE /v1/chatroom/{room_id}

          DELETE /v1/chatroom/{room_id}

此代码块在浮窗中显示

Example Request

DELETE /v1/chatroom/100000

          DELETE  /v1/chatroom/100000

此代码块在浮窗中显示

Example Response

HTTP/1.1 204 Content-Type: application/json; charset=utf-8

          HTTP/1.1 204
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

修改用户禁言状态

PUT /v1/chatroom/{room_id}/forbidden/{username}?status={status}

           PUT /v1/chatroom/{room_id}/forbidden/{username}?status={status}

此代码块在浮窗中显示

status 0 表示不禁言 1 表示开启禁言必填

Example Request

PUT /v1/chatroom/100000/forbidden/caiyh?status=1

          PUT  /v1/chatroom/100000/forbidden/caiyh?status=1

此代码块在浮窗中显示

Example Response

HTTP/1.1 204 OK Content-Type: application/json; charset=utf-8

           HTTP/1.1 204 OK
 Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

获取聊天室成员列表

GET /v1/chatroom/{room_id}/members?start={start}&count={count}

          GET /v1/chatroom/{room_id}/members?start={start}&count={count}

此代码块在浮窗中显示

Request Params

room_id 聊天室 ID。

Example Response

username 用户名
ctime 创建时间
flag 禁言标记

HTTP/1.1 200 OK Content-Type: application/json { "total": 2, "users": [ { "username": "13538013231", "flag": 0, "room_ctime": "2017-11-17 08:57:54", "mtime": "2017-10-30 17:24:17", "ctime": "2017-10-30 17:24:17" }, { "username": "xia_12", "flag": 0, "room_ctime": "2017-11-16 19:13:07", "mtime": "2017-02-08 17:56:04", "ctime": "2017-02-08 17:56:04" } ], "count": 2, "start": 0 }

           HTTP/1.1 200 OK
 Content-Type: application/json

{
    "total": 2,
    "users": [
        {
            "username": "13538013231",
            "flag": 0,
            "room_ctime": "2017-11-17 08:57:54",
            "mtime": "2017-10-30 17:24:17",
            "ctime": "2017-10-30 17:24:17"
        },
        {
            "username": "xia_12",
            "flag": 0,
            "room_ctime": "2017-11-16 19:13:07",
            "mtime": "2017-02-08 17:56:04",
            "ctime": "2017-02-08 17:56:04"
        }
    ],
    "count": 2,
    "start": 0
}

此代码块在浮窗中显示

添加聊天室成员

PUT /v1/chatroom/{room_id}/members

           PUT /v1/chatroom/{room_id}/members

此代码块在浮窗中显示

Request Params

username 的 json 数组最多支持 3000 个

Example Response

HTTP/1.1 204 Content-Type: application/json; charset=utf-8

          HTTP/1.1 204
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

移除聊天室成员

DELETE /v1/chatroom/{room_id}/members

            DELETE /v1/chatroom/{room_id}/members

此代码块在浮窗中显示

Request Params

username 的 json 数组最多支持 3000 个

Example Response

HTTP/1.1 204 Content-Type: application/json; charset=utf-8

          HTTP/1.1 204
Content-Type: application/json; charset=utf-8

此代码块在浮窗中显示

配置

设置 SDK-API 用户注册开关

打开或者关闭 SDK-API 用户注册。

PUT /v1/sdkregister/status?status={status}

          PUT /v1/sdkregister/status?status={status}

此代码块在浮窗中显示

Example Request

PUT /v1/sdkregister/status?status=0

          PUT /v1/sdkregister/status?status=0

此代码块在浮窗中显示

Request Params

JSON Array.

status：0 为关闭，不提供 SDK-API 注册功能，1 为开启

Example Response

HTTP/1.1 204 Created Content-Type: application/json Response Data N/A

           HTTP/1.1 204 Created
 Content-Type: application/json

Response Data
  N/A

此代码块在浮窗中显示

获得 SDK-API 用户注册开关

get /v1/sdkregister/status

          get /v1/sdkregister/status

此代码块在浮窗中显示

Example Request

get /sdkregister/status

          get /sdkregister/status

此代码块在浮窗中显示

Example Response

HTTP/1.1 200 Content-Type: application/json Response Data { "status": 0 } status： 0为关闭，不提供SDK-API 注册功能，1为开启

           HTTP/1.1 200
 Content-Type: application/json

Response Data
{
"status": 0
}
status： 0为关闭，不提供SDK-API 注册功能，1为开启

此代码块在浮窗中显示

HTTP 返回

HTTP 返回码参考文档：HTTP-Status-Code

Example Error Response

HTTP/1.1 401 Unauthorized Content-Type: application/json { "error": { "code": 899008, "message": "Basic authentication failed" } }

           HTTP/1.1 401 Unauthorized
 Content-Type: application/json

{
  "error": {
        "code": 899008,
        "message": "Basic authentication failed"
     }
}

此代码块在浮窗中显示

业务错误码定义

IM Server ErrorCode

文档内容是否对您有帮助？

本页目录

User 对象字段总览
用户注册
- 注册用户
用户维护
消息相关
- 发送消息
- 消息撤回
媒体文件下载与上传
- 文件上传
Group 对象字段总览
群组维护
好友
跨应用
敏感词
聊天室字段总览
聊天室维护
配置
- 设置 SDK-API 用户注册开关
- 获得 SDK-API 用户注册开关
HTTP 返回
- Example Error Response
业务错误码定义