IM REST API
Group对象字段总览
群组维护
好友
跨应用
敏感词
聊天室字段总览
聊天室维护
配置
- 设置SDK-API用户注册开关
- 获得SDK-API用户注册开关
  - Example Request
  - Example Response
HTTP 返回
- Example Error Response
业务错误码定义

IM REST API

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

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

HTTP 验证

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

Authorization: Basic base64_auth_string

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

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

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/

Example Request

[{
    "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"
}]

Response Params

JSON Array.

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

Admin 注册

Admin Register 管理员注册 (管理员api发送消息接口的权限)

POST /v1/admins/

Example Request

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

Request Params

username Byte(4-128) 支持字符
- 开头：字母或者数字
- 字母、数字、下划线
- 英文点、减号、@
password Byte(4-128) 字符不限
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; charset=utf-8

GetAdminsListByAppkey 获取应用管理员列表

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

Example Request

Request Header

GET /admins?start=1&count=30
Accept: application/json

Request Body

N/A

request params

start 起始记录位置从0开始
count 查询条数最多支持500条

Example Response

Response Header

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

Response Data

{
    "total": 1233,
    "start": 1100,
    "count": 3,
    "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"
        }
    ]
}

用户维护

获取用户信息

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

说明

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

更新用户信息

PUT /v1/users/{username}

Example Request

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

用户在线状态查询

Get /v1/users/{username}/userstat

Example Request

Request Header

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

Response Data

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

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

Error Code

错误码

899003 username不合法
899002 用户不存在

批量用户在线状态查询

Post /v1/users/userstat

Example Request

Request Header

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

Response Data

[{
    "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 用户不存在

修改密码

PUT /v1/users/{username}/password

Request Header

PUT /v1/users/javen/password

Example Request

{
     "new_password": "654321" 
}

Request Params

new_password （必填）新密码

Example Response

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

Response Data

删除用户

DELETE /v1/users/{username}

Request Params

username 用户名。
Example Response

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

批量删除用户

DELETE /v1/users/

Request Body

["USER1","USER2"]

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

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

添加黑名单

Put /v1/users/{username}/blacklist

Example Request

Request Header

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

Request Params

JsonArray
username的JsonArray
Request Body

[
 "test1",
 "test2"
 ]

Example Response

Response Header

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

Response Data

N/A

移除黑名单

Delete /v1/users/{username}/blacklist

Example Request

Request Header

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

Request Params

JsonArray
username的JsonArray
Request Body

[
 "test1",
 "test2"
 ]

Example Response

Response Header

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

Response Data

N/A

黑名单列表

Get /v1/users/{username}/blacklist

Example Request

Request Header

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

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

获取用户列表

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

免打扰

免打扰设置

POST  /v1/users/{username}/nodisturb

Example Request

Request Header

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
}

Example Response

Response Header

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}

Request Params

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

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

消息相关

发送消息

POST /v1/messages

参数	含义
version	版本号目前是1 （必填）
target_type	发送目标类型 single - 个人，group - 群组 chatroom - 聊天室（必填）
from_type	发送消息者身份当前只限admin用户，必须先注册admin用户（必填）
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": "admin",
    "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": "admin",
    "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": "admin",
     "from_id": "admin_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": "admin",
     "from_id": "admin_caiyh", 
    "msg_type": "voice",
    "msg_body": {
        json define yourself
    }
}

Request Params

JSON Object.
遵循协议文档：IM 消息协议
此api只能用admin用户发送

Example Response

< 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

Example Request

Request Header

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

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

媒体文件下载与上传

文件下载

GET /v1/resource?mediaId={mediaId}

Example Request

Request Header

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

Response Data

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

文件上传

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

Response Data图片 Response

{
    "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 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 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/

群组MaxMemberCount（人数限制）定义

Example Request

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

获取群组详情

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

更新群组信息

PUT /v1/groups/{Group id}

Request Params

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

PUT /v1/groups/{Group id}

Request Body

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

Example Response

HTTP/1.1 204 NO Content

删除群组

删除某个群组。

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

DELETE /v1/groups/{Group id}

Request Params

Group id 群组ID。
Example Response

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

更新群组成员

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

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

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

Request Params

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

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

Example Response

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

获取群组成员列表

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

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

获取某用户的群组列表

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

获取当前应用的群组列表

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

群消息屏蔽

POST /v1/users/{username}/groupsShield

Request Params

N/A

Example Request Body

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

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

Example Response

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

群成员禁言

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

Request body

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

Request Params

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

Example Response

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

移交群主

PUT  /groups/owner/{gid}

Request body

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

Request Params

Example Response

HTTP/1.1 204 NO Content

Error Code

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

好友

添加好友

POST  /v1/users/{username}/friends

Request Params

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

["user01","user02"]

Example Response

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

Response DataN/A

Error Code

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

删除好友

DELETE  /v1/users/{username}/friends

Request Params

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

["user01","user02"]

Example Response

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

Response DataN/A

Error Code

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

更新好友备注

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

Example Response

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

Response DataN/A

Error Code

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

获取好友列表

 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

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

Request Params

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

Example Request

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

Example Response

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

Response DataN/A

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

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

跨应用获取群组成员列表

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

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

跨应用添加黑名单

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

Example Request

Request Header

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

Example Response

Response Header

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

Response Data

N/A

跨应用移除黑名单

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

Example Request

Request Header

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

Example Response

Response Header

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

Response Data

N/A

跨应用黑名单列表

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

Example Request

Request Header

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

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

Example Request

Request Header

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

Example Response

Response Header

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

Example Request

Request Header

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

Example Response

Response Header

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

Response Data

N/A

跨应用删除好友

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

Example Request

Request Header

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

Example Response

Response Header

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

Response Data

N/A

跨应用更新好友备注

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

Example Request

Request Header

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

Example Response

Response Header

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

Response Data

N/A

跨应用管理聊天室成员

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

Example Response

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

Response Data

N/A

敏感词

添加敏感词

POST  /v1/sensitiveword

Example Request

Request Header

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

Request Params N/A

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

["FUCK"]

Example Response

Response Header

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

Response Data

N/A

修改敏感词

PUT  /v1/sensitiveword

Example Request

Request Header

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

Example Response

Response Header

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

Response Data

N/A

删除敏感词

DELETE /v1/sensitiveword

Example Request

Request Header

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

Request Params

N/A

Request Body+ word 被删除的敏感词

{"word":"fuck"}

Example Response

Response Header

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

Response Data

N/A

获取敏感词列表

GET /v1/sensitiveword

Example Request

Request Header

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

Response Data

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

更新敏感词功能状态

PUT /v1/sensitiveword/status

Example Request

Request Header

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

Response Data

N/A

获取敏感词功能状态

GET /v1/sensitiveword/status

Example Request

Request Header

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

Response Data

 {"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/

Request Body

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

获取聊天室详情

POST /v1/chatroom/batch

Request Params

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

GET 获取用户聊天室列表

 GET /v1/users/{username}/chatroom

Example Request

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

GET 获取应用下聊天室列表

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

Example Request

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
}

更新聊天室信息

 PUT /v1/chatroom/{room_id}

Example Request

 PUT /v1/chatroom/111000001

Request Body

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

Example Response

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

删除聊天室

DELETE /v1/chatroom/{room_id}

Example Request

DELETE  /v1/chatroom/100000

Example Response

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

修改用户禁言状态

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

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

Example Request

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

Example Response

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

获取聊天室成员列表

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
}

添加聊天室成员

 PUT /v1/chatroom/{room_id}/members

Request Params

username的json数组最多支持3000个
Example Response

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

移除聊天室成员

  DELETE /v1/chatroom/{room_id}/members

Request Params

username的json数组最多支持3000个
Example Response

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

配置

设置SDK-API用户注册开关

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

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

Example Request

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

获得SDK-API用户注册开关

get /v1/sdkregister/status

Example Request

get /sdkregister/status

Example Response

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

业务错误码定义

IM Server ErrorCode