• IM REST API
    • User对象字段总览
    • 用户注册
      • 注册用户
        • Example Request
        • Request Params
        • Example Response
        • Response Params
    • Admin 注册
      • Admin Register 管理员注册 (管理员api发送消息接口的权限)
        • Example Request
        • Request Params
        • Example Response
      • GetAdminsListByAppkey 获取应用管理员列表
        • Example Request
        • Request Header
        • Request Body
        • request params
        • Example Response
        • Response Header
        • Response Data
    • 用户维护
      • 获取用户信息
        • Request Params
        • Example Response
      • 更新用户信息
        • Example Request
        • Request Params
        • Example Response
      • 用户在线状态查询
        • Example Request
        • Example Response
        • Error Code
      • 批量用户在线状态查询
        • Example Request
        • Example Response
        • Error Code
      • 修改密码
        • Request Header
        • Example Request
        • Request Params
        • Example Response
        • Response Data
      • 删除用户
      • 批量删除用户
      • 添加黑名单
      • 移除黑名单
      • 黑名单列表
      • 获取用户列表
      • 免打扰
        • 免打扰设置
      • 禁用用户
    • 消息相关
      • 发送消息
        • Example Request
        • Request Params
        • Example Response
      • 消息撤回
        • Example Request
        • Example Response
    • 媒体文件下载与上传
      • 文件下载
      • Example Request
      • Example Response
    • 文件上传
      • Example Request
      • Example Response
  • Group对象字段总览
  • 群组维护
    • 创建群组
    • 获取群组详情
    • 更新群组信息
    • 删除群组
    • 更新群组成员
    • 获取群组成员列表
    • 获取某用户的群组列表
    • 获取当前应用的群组列表
    • 群消息屏蔽
    • 群成员禁言
    • 移交群主
  • 好友
    • 添加好友
    • 删除好友
    • 更新好友备注
    • 获取好友列表
  • 跨应用
    • 跨应用管理群组成员
    • 跨应用获取群组成员列表
    • 跨应用获取用户群组
    • 跨应用添加黑名单
    • 跨应用移除黑名单
    • 跨应用黑名单列表
    • 跨应用免打扰设置
    • 跨应用添加好友
    • 跨应用删除好友
    • 跨应用更新好友备注
    • 跨应用管理聊天室成员
  • 敏感词
    • 添加敏感词
    • 修改敏感词
    • 删除敏感词
    • 获取敏感词列表
    • 更新敏感词功能状态
    • 获取敏感词功能状态
  • 聊天室字段总览
  • 聊天室维护
    • 创建聊天室
      • Request Body
      • Example Response
    • 获取聊天室详情
      • Request Params
      • Example Response
    • GET 获取用户聊天室列表
      • Example Request
      • Example Response
    • GET 获取应用下聊天室列表
      • Example Request
      • Example Response
    • 更新聊天室信息
      • Example Request
      • Request Body
      • Example Response
    • 删除聊天室
      • Example Request
      • Example Response
    • 修改用户禁言状态
      • Example Request
      • Example Response
    • 获取聊天室成员列表
    • 添加聊天室成员
    • 移除聊天室成员
  • 配置
    • 设置SDK-API用户注册开关
      • Example Request
      • Request Params
      • Example Response
    • 获得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个用户。

    1. POST /v1/users/

    Example Request

    1. [{
    2.     "username": "dev_fang",
    3.     "password": "password"
    4. }]

    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

    1. < HTTP/1.1 201 Created
    2. < Content-Type: application/json
    3. < 
    4. [{
    5.     "username": "dev_fang"
    6. }]

    Response Params

    JSON Array.

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

    Admin 注册

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

    1. POST /v1/admins/

    Example Request

    1. {
    2.     "username": "dev_fang",
    3.     "password": "password"
    4. }

    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

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

    GetAdminsListByAppkey 获取应用管理员列表

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

    Example Request

    Request Header

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

    Request Body

    1. N/A

    request params

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

    Example Response

    Response Header

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

    Response Data

    1. {
    2.     "total": 1233,
    3.     "start": 1100,
    4.     "count": 3,
    5.     "users": [{
    6.             "username": "cai",
    7.             "nickname": "hello",
    8.             "mtime": "2015-01-01 00:00:00",
    9.             "ctime": "2015-01-01 00:00:00"
    10.         },
    11.         {
    12.             "username": "yi",
    13.             "nickname": "hello",
    14.             "mtime": "2015-01-01 00:00:00",
    15.             "ctime": "2015-01-01 00:00:00"
    16.         },
    17.         {
    18.             "username": "huang",
    19.             "nickname": "hello",
    20.             "mtime": "2015-01-01 00:00:00",
    21.             "ctime": "2015-01-01 00:00:00"
    22.         }
    23.     ]
    24. }

    用户维护

    获取用户信息

    1. GET /v1/users/{username}

    Request Params

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

    Example Response

    1. {
    2.     "username": "javen",
    3.     "nickname": "hello",
    4.     "avatar": "/avatar",
    5.     "birthday": "1990-01-24 00:00:00",
    6.     "gender": 0,
    7.     "signature": "orz",
    8.     "region": "shenzhen",
    9.     "address": "shenzhen",
    10.     "mtime": "2015-01-01 00:00:00",
    11.     "ctime": "2015-01-01 00:00:00"
    12. }

    说明

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

    更新用户信息

    1. PUT /v1/users/{username}

    Example Request

    1. {
    2.     "nickname": "Hello JMessage"
    3. }

    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

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

    用户在线状态查询

    1. Get /v1/users/{username}/userstat

    Example Request

    Request Header 

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

    Request Params

    • username 用户名
      Request Body

    N/A

    Example Response

    Response Header

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

    Response Data

    1. {
    2.     "login": true,
    3.     "online": false
    4. }

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

    Error Code

    错误码

    • 899003 username不合法
    • 899002 用户不存在

    批量用户在线状态查询

    1. Post /v1/users/userstat

    Example Request

    Request Header 

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

    Request Params

    N/A

    Request Body

    ["USER1","USER2"]

    Example Response

    Response Header

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

    Response Data

    1. [{
    2.     "devices": [],
    3.     "username": "caiyh01"
    4. }, {
    5.     "devices": [{
    6.         "login": false,
    7.         "online": false,
    8.         "platform": "a"
    9.     }],
    10.     "username": "Rauly"
    11. }]
    • devices 设备登陆状态数组，没有登陆过数组为空
    • platform SDK各平台：a-Android，i-iOS，j-JS，w-Windows

    Error Code

    错误码

    • 899003 username不合法
    • 899002 用户不存在

    修改密码

    1. PUT /v1/users/{username}/password

    Request Header

    1. PUT /v1/users/javen/password

    Example Request

    1. {
    2.      "new_password": "654321" 
    3. }

    Request Params

    • new_password （必填）新密码

    Example Response

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

    Response Data

    • N/A

    删除用户

    1. DELETE /v1/users/{username}

    Request Params

    • username 用户名。
      Example Response
    1. < HTTP/1.1 204 NO CONTENT
    2. < Content-Type: application/json; charset=utf-8

    批量删除用户

    1. DELETE /v1/users/

    Request Body

    1. ["USER1","USER2"]
    • username 用户名数组。（最多支持同时删除100个用户）
      Example Response
    1. < HTTP/1.1 200 NO CONTENT
    2. < Content-Type: application/json; charset=utf-8

    添加黑名单

    1. Put /v1/users/{username}/blacklist

    Example Request

    Request Header 

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

    Request Params

    • JsonArray
    • username的JsonArray
      Request Body
    1. [
    2.  "test1",
    3.  "test2"
    4.  ]

    Example Response

    Response Header 

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

    Response Data

    N/A

    移除黑名单

    1. Delete /v1/users/{username}/blacklist

    Example Request

    Request Header 

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

    Request Params

    • JsonArray
    • username的JsonArray
      Request Body
    1. [
    2.  "test1",
    3.  "test2"
    4.  ]

    Example Response

    Response Header

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

    Response Data

    N/A

    黑名单列表

    1. Get /v1/users/{username}/blacklist

    Example Request

    Request Header 

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

    Request Params

    • username 用户名
      Request Body

    N/A

    Example Response

    Response Header 

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

    Response Data

    1. [{
    2.     "username": "javen",
    3.     "nickname": "hello",
    4.     "avatar" = "/avatar",
    5.     "birthday": "1990-01-24 00:00:00",
    6.     "gender": 0,
    7.     "signature": "orz",
    8.     "region": "shenzhen",
    9.     "address": "shenzhen",
    10.     "mtime": "2015-01-01 00:00:00",
    11.     "ctime": "2015-01-01 00:00:00"
    12. }]

    获取用户列表

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

    Request Params

    • start 开始的记录数
    • count 要获取的记录个数
      Example Response
    1. < HTTP/1.1 200 
    2. < Content-Type: application/json
    4. {
    5.     "total": 12580,
    6.     "start": 1100,
    7.     "count": 100,
    8.     "users": [{
    9.             "username": "cai",
    10.             "nickname": "hello",
    11.             "mtime": "2015-01-01 00:00:00",
    12.             "ctime": "2015-01-01 00:00:00"
    13.         },
    14.         {
    15.             "username": "yi",
    16.             "nickname": "hello",
    17.             "mtime": "2015-01-01 00:00:00",
    18.             "ctime": "2015-01-01 00:00:00"
    19.         },
    20.         {
    21.             "username": "huang",
    22.             "nickname": "hello",
    23.             "mtime": "2015-01-01 00:00:00",
    24.             "ctime": "2015-01-01 00:00:00"
    25.         }
    26.     ]
    27. }

    免打扰

    免打扰设置

    1. POST  /v1/users/{username}/nodisturb

    Example Request

    Request Header 

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

    Request Params

    • single 单聊免打扰，支持add remove数组 （可选）
    • group 群聊免打扰，支持add remove数组（可选）
    • global 全局免打扰，0或1 0表示关闭，1表示打开 （可选）
      Request Body
    1. {   
    2.    "single":{   
    3.       "add":[   
    4.          "username1",
    5.          "username2"
    6.       ]
    7.    },
    8.    "group":{   
    9.       "add":[   
    10.          110000101
    11.       ],
    12.       "remove":[   
    13.          1000001111
    14.       ]
    15.    },
    16.    "global":0
    17. }

    Example Response

    Response Header

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

    Response Data

    N/A

    Error Code

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

    禁用用户

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

    Request Params

    • disable boolean,true代表禁用用户，false代表激活用户
      Example Response
    1. < HTTP/1.1 204 NO CONTENT
    2. < Content-Type: application/json

    消息相关

    发送消息

    1. 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_bodyJson对象的消息体 限制为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_idString 文件上传之后服务器端所返回的key，用于之后生成下载的url（必填）
    msg_body->media_crc32long 文件的crc32校验码，用于下载大图的校验 （必填）
    msg_body->widthint 图片原始宽度（必填）
    msg_body->heightint 图片原始高度（必填）
    msg_body->format String 图片格式（必填）
    msg_body->hash String 图片hash值（可选）
    msg_body->fsizeint 文件大小（字节数）（必填）
    msg_type为voice时,msg_body为上传语音返回的json，格式如下
    msg_body->media_idString 文件上传之后服务器端所返回的key，用于之后生成下载的url（必填）
    msg_body->media_crc32long 文件的crc32校验码，用于下载大图的校验 （必填）
    msg_body->durationint 音频时长（必填）
    msg_body->hash String 音频hash值（可选）
    msg_body->fsizeint 文件大小（字节数）（必填）

    Example Request

    1. msg_type:text
    2. {
    3.     "version": 1, 
    4.     "target_type": "single",
    5.     "target_id": "javen",
    6.     "from_type": "admin",
    7.     "from_id": "fang", 
    8.     "msg_type": "text",
    9.     "msg_body": {
    10.         "extras": {},
    11.         "text": "Hello, JMessage!"  
    12.     }
    13. }
    15. msg_type:image
    16. {
    17.     "version": 1, 
    18.     "target_type": "single",
    19.     "target_id": "javen",
    20.     "from_type": "admin",
    21.     "from_id": "fang", 
    22.     "msg_type": "image",
    23.     "msg_body": {
    24.     "media_id": "qiniu/image/CE0ACD035CBF71F8",
    25.     "media_crc32":2778919613,
    26.     "width":3840,
    27.     "height":2160,
    28.     "fsize":3328738,
    29.     "format":"jpg"
    30.     }
    31. }
    33. msg_type:voice
    35. {
    36.     "version": 1, 
    37.     "target_type": "single",
    38.     "target_id": "ppppp",
    39.     "from_type": "admin",
    40.      "from_id": "admin_caiyh", 
    41.     "msg_type": "voice",
    42.     "msg_body": {
    43.     "media_id": "qiniu/voice/j/A96B61EB3AF0E5CDE66D377DEA4F76B8",
    44.     "media_crc32":1882116055,
    45.     "hash":"FoYn15bAGRUM9gZCAkvf9dolVH7h",
    46.     "fsize" :12344;
    47.      "duration": 6
    48.     }
    49. }
    1. msg_type:custom
    3. {
    4.     "version": 1, 
    5.     "target_type": "single",
    6.     "target_id": "ppppp",
    7.     "from_type": "admin",
    8.      "from_id": "admin_caiyh", 
    9.     "msg_type": "voice",
    10.     "msg_body": {
    11.         json define yourself
    12.     }
    13. }

    Request Params

    • JSON Object.

    • 遵循协议文档：IM 消息协议

    • 此api只能用admin用户发送

    Example Response

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

    msg_ctime: 消息创建的时间戳

    Error Code

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

    消息撤回

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

    Example Request

    Request Header 

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

    Request Body

    N/A

    Request Params

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

    Example Response

    Response Header

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

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

    媒体文件下载与上传

    文件下载

    1. GET /v1/resource?mediaId={mediaId}

    Example Request

    Request Header 

    1. GET /v1/resource?mediaId={mediaId}

    Request Body

    N/A

    Request Params

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

    Example Response

    Response Header

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

    Response Data

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

    文件上传

    1. 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

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

    Response Data图片 Response

    1. {
    2.     "media_id": "qiniu/image/F39AA12204DAB6A2",
    3.     "media_crc32": 1338734977,
    4.     "width": 720,
    5.     "height": 1280,
    6.     "format": "jpg",
    7.     "fsize": 52468
    8. }
    • media_id String 文件上传之后服务器端所返回的key
    • media_crc32 long 文件的crc32校验码
    • width int 图片原始宽度
    • height int 图片原始高度
    • format String 图片格式
    • fsize int 文件大小 （字节数）
    • hash String 可选，用于crc校验码不存在时的替代的验证
      文件 Response 
    1. {
    2.     "media_id": "qiniu/file/j/1BB3B833AEABFF62E883C5CE421867A9",
    3.     "media_crc32": 1415584260,
    4.     "fname": "0839d1c0-48e9-4032-9333-f3691a7d9e48.dmp",
    5.     "fsize": 176512,
    6.     "hash": "FtH0kPT0YI89HAw1K9wv_vVKiNab"
    7. }
    • media_id String 文件上传之后服务器端所返回的key，用于之后生成下载的url
    • media_crc32 long 文件的crc32校验码
    • hash String 可选，用于crc校验码不存在时的替代的验证
    • fsize int 文件大小（字节数）
    • fname String 发送与接收到的文件名
      语音 Response
    1. {
    2.     "media_id": "qiniu/voice/j/9C4312B1EA0FB28337566D1A29A244B5",
    3.     "media_crc32": 1882116055,
    4.     "hash": "FoYn15bAGRUM9gZCAkvf9dolVH7h",
    5.     "format": "m4a",
    6.     "fsize": 238105
    7. }
    • 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群主的usernameByte(4-128)
    MaxMemberCount群组默认500人
    ctime创建时间
    mtime最后修改时间
    avatar群组头像

    群组维护

    创建群组

    1. POST /v1/groups/

    群组MaxMemberCount（人数限制）定义

    Example Request

    1. {
    2.     "owner_username": "tom", 
    3.     "name": "群聊天室", 
    4.     "members_username": ["eddie", "annie"], 
    5.     "flag": 1,
    6.     "desc": "运动"
    7. }

    Request Params

    • owner_username （必填）群主username
    • name （必填）群组名字
      • 支持的字符：全部，包括 Emoji。
    • members_username 成员 username
    • avatar （选填）群组头像，上传接口所获得的media_id
    • desc （选填） 群描述
      • 支持的字符：全部，包括 Emoji。

    • flag （选填） 类型

      • 1 - 私有群（默认）
      • 2 - 公开群
      • 不指定flag，默认为1
        Example Response
    1. < HTTP/1.1 201 Created
    2. < Content-Type: application/json
    3. < 
    5. {
    6.     "gid":12345, 
    7.     "owner_username": 123456, 
    8.     "name": "display_name", 
    9.     "members_username": [], 
    10.     "desc":"doubi",
    11.     "MaxMemberCount" = 500
    12. }

    获取群组详情

    1. GET /v1/groups/{Group id}

    Request Params

    • Group id 群组ID。由创建群组时分配。
      Example Response
    1. < HTTP/1.1 200 OK
    2. < Content-Type: application/json
    3. < 
    5. {
    6.       "gid": 12345, 
    7.       "name" : "jpush", 
    8.       "desc" : "push", 
    9.       "appkey" : "dcf71ef5082057832bd44fbd", 
    10.       "MaxMemberCount" : 500,  
    11.       "mtime" : "2014-07-01 00:00:00", 
    12.       "ctime" : "2014-06-05 00:00:00"
    13. }

    更新群组信息

    1. PUT /v1/groups/{Group id}

    Request Params

    • name 群名称
    • desc 群描述
    • avatar 群组头像media_id
    1. PUT /v1/groups/{Group id}

    Request Body

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

    Example Response

    1. HTTP/1.1 204 NO Content

    删除群组

    删除某个群组。

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

    1. DELETE /v1/groups/{Group id}

    Request Params

    • Group id 群组ID。
      Example Response
    1. < HTTP/1.1 204 NO CONTENT
    2. < Content-Type: application/json

    更新群组成员

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

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

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

    Request Params

    • gid 群组ID
    • add json数组 表示要添加到群组的用户(可选)
    • remove json数组 表示要从群组删除的用户（可选）
    • 两者至少要有一个
      Example Request 
    1. {    
    2.     "add":[
    3.         "test1", "test2"
    4.     ],
    5.     "remove":[
    6.         "test3", "test4"
    7.     ]
    8. }

    Example Response

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

    获取群组成员列表

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

    Request Params

    • Group id 群组ID。
      Example Response

    • JsonObject UID数组

    1. < HTTP/1.1 200 OK
    2. < Content-Type: application/json; charset=utf-8
    4. [{
    5.     "username": "javen",
    6.     "nickname": "hello",
    7.     "avatar" = "/avatar",
    8.     "birthday": "1990-01-24 00:00:00",
    9.     "gender": 0,
    10.     "signature": "orz",
    11.     "region": "shenzhen",
    12.     "address": "shenzhen",
    13.     "flag": 0
    14. }]
    • flag
      • 0 - 普通群成员
      • 1 - 群主

    获取某用户的群组列表

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

    Request Params

    • username 用户名。
      Example Response

    • ctime 群组

    • 创建时间
    • mtime 群组最后修改时间 
    1. < HTTP/1.1 200 OK
    2. < Content-Type: application/json
    4. [{
    5.     "gid": 12345,
    6.     "name": "jpush",
    7.     "desc": "push",
    8.     "appkey": "dcf71ef5082057832bd44fbd",
    9.     "MaxMemberCount": 500,
    10.     "mtime": "2014-07-01 00:00:00",
    11.     "ctime": "2014-06-05 00:00:00"
    12. }]

    获取当前应用的群组列表

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

    Request Params

    • start 开始的记录数。
    • count 本次读取的记录数量。最大值为500
      Example Response
    1. < HTTP/1.1 200 OK
    2. < Content-Type: application/json
    4. {
    5.     "total": 1233,
    6.     "start": 1100,
    7.     "count": 1,
    8.     "groups": [{
    9.         "gid": 12345,
    10.         "name": "jpush",
    11.         "desc": "push",
    12.         "appkey": "dcf71ef5082057832bd44fbd",
    13.         "MaxMemberCount": 500,
    14.         "mtime": "2014-07-01 00:00:00",
    15.         "ctime": "2014-06-05 00:00:00"
    16.     }]
    17. }

    群消息屏蔽

    1. POST /v1/users/{username}/groupsShield

    Request Params

    N/A

    Example Request Body

    1. {         
    2.     "add": [ 110000101],
    3.     "remove": [ 1000001111]
    4. }
    参数含义
    add添加群消息屏蔽的gid数组 （可选）
    remove移除群消息屏蔽的gid数组 （可选）

    Example Response

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

    群成员禁言

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

    Request body

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

    Request Params

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

    Example Response

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

    移交群主

    1. PUT  /groups/owner/{gid}

    Request body

    1. { 
    2.     "appkey":"xxxxxxx",
    3.     "username": "xxxxxxx"
    4. }  
    5.  注：跨应用下的用户
    7. 或者
    9. { 
    10.     "username": "xxxxxxx"
    11. }  
    12. 注：本应用下的用户

    Request Params

    Example Response

    1. HTTP/1.1 204 NO Content

    Error Code

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

    好友

    添加好友

    1. POST  /v1/users/{username}/friends

    Request Params

    • json数组 表示要添加的用户名列表 最大限制500个
      Example Request 
    1. ["user01","user02"]

    Example Response

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

    Response DataN/A

    Error Code

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

    删除好友

    1. DELETE  /v1/users/{username}/friends

    Request Params

    • json数组 表示要删除的用户名列表 最大限制500个
      Example Request 
    1. ["user01","user02"]

    Example Response

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

    Response DataN/A

    Error Code

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

    更新好友备注

    1.   PUT  /v1/users/{username}/friends

    Request Params

    • note_name 表示要添加的好友列表， 格式：Byte(64) 支持的字符：不包括 "\n" "\r"。
    • others 其他备注信息，格式：Byte(250) 支持的字符：全部，包括 Emoji。
    • username 用户username；
    • 支持批量修改 最大限制500个
      Example Request 
    1. [{
    2.         "note_name": "new note name",
    3.         "others": “好友备注文档 " ,"
    4.         username ":"
    5.         user01 "
    6. }]

    Example Response

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

    Response DataN/A

    Error Code

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

    获取好友列表

    1.  GET  /v1/users/{username}/friends

    Request Params

    N/A

    Example Request

    Example Response

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

    Response Data

    1. [{
    2.     "username": "javen",
    3.     "nickname": "hello",
    4.     "avatar" = "/avatar",
    5.     "birthday": "1990-01-24 00:00:00",
    6.     "gender": 0,
    7.     "signature": "orz",
    8.     "region": "shenzhen",
    9.     "address": "shenzhen",
    10.     "mtime": "2015-01-01 00:00:00",
    11.     "ctime": "2015-01-01 00:00:00",
    12.     "note_name": "= =",
    13.     "others": "test",
    14.     "appkey": "pojkasouduioadk"
    15. }]

    Error Code

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

    跨应用

    跨应用管理群组成员

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

    Request Params

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

    Example Request 

    1. [{ 
    2.  "appkey":" 4f7aef34fb361292c566a1cd",
    3.  "add": [
    4.  "test1",
    5.  "test2"
    6.  ],
    7.  "remove": [
    8.  "name3",
    9.  "name4"
    10.  ]
    11. }]

    Example Response

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

    Response DataN/A

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

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

    跨应用获取群组成员列表

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

    Request Params

    • Group id 群组ID。
      Example Response

    • JsonObject UID数组

    1. < HTTP/1.1 200 OK
    2. < Content-Type: application/json; charset=utf-8
    4. [{
    5.     "username": "javen",
    6.     "nickname": "hello",
    7.     "avatar" = "/avatar",
    8.     "birthday": "1990-01-24 00:00:00",
    9.     "gender": 0,
    10.     "signature": "orz",
    11.     "region": "shenzhen",
    12.     "address": "shenzhen",
    13.     "flag": 0,
    14.     "appkey": "appkey"
    15. }]
    • flag
      • 0 - 普通群成员
      • 1 - 群主

    跨应用获取用户群组

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

    Request Params

    • username 用户名
      Example Response
    1. < HTTP/1.1 200 OK
    2. < Content-Type: application/json; charset=utf-8
    3. [{
    4.     "gid": 12345,
    5.     "name": "jpush",
    6.     "desc": "push",
    7.     "appkey": "dcf71ef5082057832bd44fbd",
    8.     "max_member_count": 200,
    9.     "mtime": "2014-07-01 00:00:00",
    10.     "ctime": "2014-06-05 00:00:00",
    11.     "appkey": "appkey"
    12. }]

    跨应用添加黑名单

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

    Example Request

    Request Header 

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

    Request Params

    • username 添加的用户的数组
    • appkey 用户所属的appkey
      Request Body
    1. [{
    2.     "appkey": "appkey",
    3.     "usernames": ["test1", "test2"]
    4. }]

    Example Response

    Response Header 

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

    Response Data

    N/A

    跨应用移除黑名单

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

    Example Request

    Request Header 

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

    Request Params

    • username 移除的用户的数组
    • appkey 用户所属的appkey
      Request Body
    1.  [{
    2.  "appkey":"appkey",
    3.  "usernames":[ "test1", "test2"]
    4.  } ]

    Example Response

    Response Header

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

    Response Data

    N/A

    跨应用黑名单列表

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

    Example Request

    Request Header 

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

    Request Params

    • username 用户名
      Request Body

    N/A

    Example Response

    Response Header 

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

    Response Data

    1. [{
    2.     "username": "javen",
    3.     "nickname": "hello",
    4.     "avatar" = "/avatar",
    5.     "birthday": "1990-01-24 00:00:00",
    6.     "gender": 0,
    7.     "signature": "orz",
    8.     "region": "shenzhen",
    9.     "address": "shenzhen",
    10.     "mtime": "2015-01-01 00:00:00",
    11.     "ctime": "2015-01-01 00:00:00",
    12.     "appkey": "appkey"
    13. }]

    跨应用免打扰设置

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

    Example Request

    Request Header 

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

    Request Params

    • single 单聊免打扰，支持add remove数组 （可选）
    • group 群聊免打扰，支持add remove数组（可选）
    • appkey 目标的appkey
      Request Body
    1. [{
    2.    "appkey":"appkey1",
    3.    "single":{
    4.       "add":[ 
    5.          "username1",
    6.          "username2"
    7.       ]
    8.    },
    9.    "group":{ 
    10.       "add":[
    11.          110000101
    12.       ],
    13.       "remove":[
    14.          1000001111
    15.       ]
    16.    }
    17. }
    18. ]

    Example Response

    Response Header

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

    Response Data

    N/A

    Error Code

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

    跨应用添加好友

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

    Example Request

    Request Header 

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

    Request Params

    • appkey 用户所属的appkey （必填）
    • users username的json数组 最多500个（必填）
      Request Body
    1. {
    2.     "appkey": "appkey",
    3.     "users": ["user01", "user02"]
    4. }

    Example Response

    Response Header

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

    Response Data

    N/A

    跨应用删除好友

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

    Example Request

    Request Header 

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

    Request Params

    • appkey 用户所属的appkey （必填）
    • users username的json数组 最多500个（必填）
      Request Body
    2. {
    3.     "appkey": "appkey",
    4.     "users": ["user01", "user02"]
    5. }

    Example Response

    Response Header

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

    Response Data

    N/A

    跨应用更新好友备注

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

    Example Request

    Request Header 

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

    Request Params

    • appkey 用户所属的appkey （必填）
    • note_name 表示要添加的好友列表， 格式：Byte(64) 支持的字符：不包括 "\n" "\r"。
    • others 其他备注信息，格式：Byte(250) 支持的字符：全部，包括 Emoji。
      Request Body
    1. [{
    2.         "note_name": "new note name",
    3.         "others": “好友备注文档 " ,"
    4.         username ":"
    5.         user01 ", "
    6.         appkey ":"
    7.         appkey "
    8. }]

    Example Response

    Response Header

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

    Response Data

    N/A

    跨应用管理聊天室成员

    1. POST  /cross/chatroom/{room_id}/members

    Request Params

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

    Example Request 

    1. [{ 
    2.  "appkey":" 4f7aef34fb361292c566a1cd",
    3.  "add": [
    4.  "test1",
    5.  "test2"
    6.  ],
    7.  "remove": [
    8.  "name3",
    9.  "name4"
    10.  ]
    11. }]

    Example Response

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

    Response Data

    N/A

    敏感词

    添加敏感词

    1. POST  /v1/sensitiveword

    Example Request

    Request Header 

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

    Request Params N/A

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

    1. ["FUCK"]

    Example Response

    Response Header

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

    Response Data

    N/A

    修改敏感词

    1. PUT  /v1/sensitiveword

    Example Request

    Request Header 

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

    Request Params

    N/A

    Request Body+ old_word 旧敏感词+ new_word 新敏感词

    1. {
    2.     "new_word": "fuck",
    3.     "old_word": "FUCK"
    4. }

    Example Response

    Response Header

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

    Response Data

    N/A

    删除敏感词

    1. DELETE /v1/sensitiveword

    Example Request

    Request Header 

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

    Request Params

    N/A

    Request Body+ word 被删除的敏感词

    1. {"word":"fuck"}

    Example Response

    Response Header

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

    Response Data

    N/A

    获取敏感词列表

    1. GET /v1/sensitiveword

    Example Request

    Request Header 

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

    Request Params

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

    N/A

    Example Response

    Response Header

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

    Response Data

    1. {
    2. "start": 2,
    3. "count": 1,
    4. "words": [
    5. {
    6. "name": "fuck",
    7. "itime": "1970-01-17 16:49:11"
    8. }
    9. ],
    10. "total": 3
    11. }

    更新敏感词功能状态

    1. PUT /v1/sensitiveword/status

    Example Request

    Request Header 

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

    Request Params

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

    N/A

    Example Response

    Response Header

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

    Response Data

    N/A

    获取敏感词功能状态

    1. GET /v1/sensitiveword/status

    Example Request

    Request Header 

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

    Request Params

    N/A

    Request Body

    N/A

    Example Response

    Response Header

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

    Response Data

    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表示开启禁言

    聊天室维护

    创建聊天室

    1. POST /v1/chatroom/

    Request Body

    1. {
    2.     "owner_username": "liming",
    3.     "name": "测试聊天室",
    4.     "description": "测试",
    5.     "members_username": []
    6. }

    Request Params

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

    Example Response

    1.  HTTP/1.1 201 Created
    2.  Content-Type: application/json
    4. {
    5. "chatroom_id": 1000000
    6. }

    获取聊天室详情

    1. POST /v1/chatroom/batch

    Request Params

    1. [10000001,10000002] roomid数组

    Example Response

    1. HTTP/1.1 200 OK 
    2. Content-Type: application/json; charset=utf-8  
    4. [
    5.     {
    6.         "id": 10000001,
    7.         "owner_username": "xiaoming",
    8.         "max_member_count": 10000,
    9.         "appkey": "4f7aef34fb361292c566a1cd",
    10.         "name": "test",
    11.         "description": "test",  
    12.         "total_member_count": 2,
    13.         "ctime": "2017-11-27 18:38:25"
    14.     }，
    15.  {
    16.         "id": 10000002,
    17.         "owner_username": "xiaoming",
    18.         "max_member_count": 10000,
    19.         "appkey": "4f7aef34fb361292c566a1cd",
    20.         "name": "test",
    21.         "description": "test",
    22.         "total_member_count": 2,
    23.         "ctime": "2017-11-27 18:38:25"
    24.     }
    25. ]

    GET 获取用户聊天室列表

    1.  GET /v1/users/{username}/chatroom

    Example Request

    1. GET /v1/users/xiaoming/chatroom

    Example Response

    1. HTTP/1.1 200 OK 
    2. Content-Type: application/json; charset=utf-8 
    4. [
    5.     {
    6.         "id": 100000,
    7.         "owner_username": "xiaoming",
    8.         "max_member_count": 10000,
    9.         "appkey": "4f7aef34fb361292c566a1cd",
    10.         "name": "test",
    11.         "description": "test",
    12.         "total_member_count": 2，
    13.        "ctime": "2017-11-27 18:38:25"
    14.     }，
    15.  {
    16.         "id": 10000001,
    17.         "owner_username": "xiaoming",
    18.         "max_member_count": 10000,
    19.         "appkey": "4f7aef34fb361292c566a1cd",
    20.         "name": "test",
    21.         "description": "test",
    22.         "total_member_count": 2，
    23.         "ctime": "2017-11-27 18:38:25"
    24.     }
    25. ]

    GET 获取应用下聊天室列表

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

    Example Request

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

    Example Response

    1. HTTP/1.1 200 OK 
    2. Content-Type: application/json; charset=utf-8 
    4. {
    5.     "total": 1,
    6.     "rooms": [
    7.         {
    8.             "id": 62,
    9.             "owner_username": "xiaoming",
    10.             "max_member_count": 10000,
    11.             "appkey": "4f7aef34fb361292c566a1cd",
    12.             "name": "test",
    13.             "description": "test"，
    14.              total_member_count": 11,
    15.             "ctime": "2017-11-27 18:38:25"
    16.         }
    17.     ],
    18.     "start": 0,
    19.     "count": 1
    20. }

    更新聊天室信息

    1.  PUT /v1/chatroom/{room_id}

    Example Request

    1.  PUT /v1/chatroom/111000001

    Request Body

    1. {
    2.     "owner_username": "135380113231",
    3.     "name": "中国人",
    4.     "description": "说什么来这"
    5. }

    Example Response

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

    删除聊天室

    1. DELETE /v1/chatroom/{room_id}

    Example Request

    1. DELETE  /v1/chatroom/100000

    Example Response

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

    修改用户禁言状态

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

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

    Example Request

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

    Example Response

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

    获取聊天室成员列表

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

    Request Params

    • room_id 聊天室ID。
      Example Response

    • username 用户名

    • ctime 创建时间
    • flag 禁言标记
    1.  HTTP/1.1 200 OK
    2.  Content-Type: application/json
    4. {
    5.     "total": 2, 
    6.     "users": [
    7.         {
    8.             "username": "13538013231", 
    9.             "flag": 0, 
    10.             "room_ctime": "2017-11-17 08:57:54", 
    11.             "mtime": "2017-10-30 17:24:17", 
    12.             "ctime": "2017-10-30 17:24:17"
    13.         }, 
    14.         {
    15.             "username": "xia_12", 
    16.             "flag": 0, 
    17.             "room_ctime": "2017-11-16 19:13:07", 
    18.             "mtime": "2017-02-08 17:56:04", 
    19.             "ctime": "2017-02-08 17:56:04"
    20.         }
    21.     ], 
    22.     "count": 2, 
    23.     "start": 0
    24. }

    添加聊天室成员

    1.  PUT /v1/chatroom/{room_id}/members

    Request Params

    • username的json数组 最多支持3000个
      Example Response
    1. HTTP/1.1 204  
    2. Content-Type: application/json; charset=utf-8

    移除聊天室成员

    1.   DELETE /v1/chatroom/{room_id}/members

    Request Params

    • username的json数组 最多支持3000个
      Example Response
    1. HTTP/1.1 204  
    2. Content-Type: application/json; charset=utf-8

    配置

    设置SDK-API用户注册开关

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

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

    Example Request

    1. PUT /v1/sdkregister/status?status=0

    Request Params

    JSON Array.

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

    Example Response

    1.  HTTP/1.1 204 Created
    2.  Content-Type: application/json
    4. Response Data
    5.   N/A

    获得SDK-API用户注册开关

    1. get /v1/sdkregister/status

    Example Request

    1. get /sdkregister/status

    Example Response

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

    HTTP 返回

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

    Example Error Response

    1.  HTTP/1.1 401 Unauthorized
    2.  Content-Type: application/json
    4. { 
    5.   "error": {
    6.         "code": 899008, 
    7.         "message": "Basic authentication failed"
    8.      }
    9. }

    业务错误码定义

    IM Server ErrorCode