IM REST API

IM REST API

The JMessage API provides developers with an HTTP API for related IM functionality.

Addresses of these API are unified (note that unlike the Push API): https://api.im.jpush.cn

HTTP Authentication

Authentication uses the HTTP Basic mechanism, which adds a field (Key/Value pair) to the HTTP Header (header):

Authorization: Basic base64_auth_string

The generation algorithm of base64_auth_string is: base64(appKey:masterSecret)

That is, add a colon to the appKey, plus the string assembled by masterSecret, and do a base64 conversion.

Overview of User Object Fields

Parameter	Meaning	Limits of character length
username	User login name	Byte(4~128)
password	Login password	Byte(4~128)
appkey	Appkey to which the user belongs
nickname	User nickname	Byte(0~64)
birthday	Birthday	yyyy-MM-dd HH:mm:ss
gender	Gender 0 - Unknown, 1 - Male, 2 - Female
signature	User signature	Byte(0~250)
region	User area	Byte(0~250)
address	Detailed address	Byte(0~250)
ctime	User creation time
mtime	Last modified time
extras	User-defined json objects	Byte(0~512)

User Registration

Register as user

Batch registration of users to JMessage server, up to 500 users in one batch registration

POST /v1/users/

Example Request

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

Request Params

JSON Array.

username (required)
- At the beginning: letters or numbers
- letters, numbers, underscores
- English, minus, @
password (required) JMessage server will be saved with MD5 encryption.
nickname (optional)
- Unsupported characters: English characters: \n \r\n
avatar (optional)
- Need to fill in the media_id obtained from the uploading interface of files
birthday (optional) example: 1990-01-24
- yyyy-MM-dd
signature (optional)
- Supported characters: All, including Emoji
gender (optional)
- 0 - Unknown, 1 - Male, 2 - Female
region (optional)
- Supported characters: All, including Emoji
address (optional)
- Supported characters: All, including Emoji
extras (optional) user-defined json objects

Example Response

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

Response Params

JSON Array.

username
Error: When an error occurs in the registration of a user, there is an error object in the object indicating the cause of the error.
- 899003: parameter error, Request Body does not meet the requirements
- 899001: user already exists

Admin Registration

Admin Register (Administrator api sends permissions of message interface)

POST /v1/admins/

Example Request

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

Request Params

username Byte(4-128) supported character
- At the beginning: letters or numbers
- letters, numbers, underscores
- English, minus, @
password Byte(4-128) Characters are not limited
nickname (optional)
- Unsupported characters: English characters: \n \r\n
avatar (optional)
- Need to fill in the media_id obtained from the uploading interface of files
birthday (optional) birthday example: 1990-01-24
- yyyy-MM-dd
signature (optional)
- Supported characters: All, including Emoji
gender (optional)
- 0 - Unknown, 1 - Male, 2 - Female
region (optional)
- Supported characters: All, including Emoji
address (optional)
- Supported characters: All, including Emoji
extras (optional) user-defined json objects

Example Response

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

GetAdminsListByAppkey: Get admin list of app

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

Example Request

Request Header

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

Request Body

request params

start: record position of starting, starts from 0
count: query number, supports up to 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"
    }]}

User Maintenance

Get user information

GET /v1/users/{username}

Request Params

username: Fill to the request path

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

Instructions

In addition to the username mtime ctime, these three sub-sections, if there is no json for the the remaining fields, then there is no corresponding key.

Update user information

PUT /v1/users/{username}

Example Request

{
    "nickname": "Hello JMessage"
}

Request Params

nickname (optional)
- Unsupported characters: English characters: \n \r\n
avatar (optional)
- Need to fill in the media_id obtained from the uploading interface of files
birthday (optional) birthday example: 1990-01-24
- yyyy-MM-dd
signature (optional)
- Supported characters: All, including Emoji
gender (optional)
- 0 - Unknown, 1 - Male, 2 - Female
region (optional)
- Supported characters: All, including Emoji
address (optional) address
- Supported characters: All, including Emoji
extras (optional) user-defined json objects

Example Response

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

Query user online status

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

Example Response

Response Header

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

Response Data

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

This interface is not applicable to multi-end online. Please use batch status interface for multi-end online.

Error Code

899003: username is illegal
899002: user does not exist

Query bulk user online status

Post /v1/users/userstat

Example Request

Request Header

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

Request Params

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: Array of device login status. Array as empty if no login.
Platform SDK Platforms: a-Android, i-iOS, j-JS, w-Windows

Error Code

899003: username is illegal
899002: user does not exist

Change password

PUT /v1/users/{username}/password

Request Header

PUT /v1/users/javen/password

Example Request

{
    "new_password": "654321"
}

Request Params

new_password （required）

Example Response

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

Response Data

Delete users

DELETE /v1/users/{username}

Request Params

username

Example Response

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

Delete users in batches

DELETE /v1/users/

Request Body

["USER1","USER2"]

username: Array of usernames. (Maximum support for deleting 100 users at the same time)

Example Response

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

Add blacklist

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

Remove blacklist

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

List of blacklist

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

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 user list

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

Request Params

start: Number of records started
count: Number of records to retrieve

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

Do-Not-Disturb

Do-Not-Disturb settings

POST  /v1/users/{username}/nodisturb

Example Request

Request Header

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

Request Params

single: single chat DND, supports add remove array (optional)
group: group chat DND, supports add remove array (optional)
global: global DND, 0 or 1 0 means closed, 1 means open (optional)

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

Error Code

899003: username is illegal;
899002: user does not exist;
899051: group does not exist
899052: sets group
Blocked, group blocking is turned on
99053: sets group message block and the group blocking is turned off

Disable users

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

Request Params

disable boolean, true for disabled users, false for activated users

Example Response

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

Message Related

Send a message

POST /v1/messages

Parameter	Meaning
version	Version number is currently 1 (required)
target_type	Target type: single - person, group – group, chatroom - chat room (required)
from_type	The sender’s identity is currently restricted to the admin user and must be registered as an admin user (required)
msg_type	Message type: text, image, custom message (msg_body is json object, server does not check) voice (required)
target_id	Target id: single to fill username, group to fill group id, chatroom to fill chatroomid (required)
target_appkey	Cross-app target appkey (optional)
from_id	Sender’s username (required)
from_name	Sender’s display name (optional)
target_name	Recipient’s display name (optional)
no_offline	Whether the message is stored offline, true or false, defaults to false, indicating that it needs to be stored offline (optional)
no_notification	Whether the message is displayed in the notification bar, true or false, the default is false, which means to display in the notification bar (optional)
notification	Custom notification bar display (optional)
notification->title	Title of the notification (optional)
notification->alert	Content of notification (optional)
msg_body	The body of the Json object is limited to 4096 bytes
When msg_type is text, the format of msg_body is as follows
msg_body -> text	Message content (required)
msg_body-> extras	Optional json objects. Developers can customize the extra key value (optional)
When msg_type is an image, msg_body is the json returned by the uploaded image in the following format
msg_body->media_id	String: The key returned by the server after the file is uploaded. It is used to generate the downloaded URL (required)
msg_body->media_crc32	The crc32 checksum of a long file, used to download the checksum of the large image (required)
msg_body->width	Int: Original width of image (required)
msg_body->height	Int: Original height of image (required)
msg_body->format	String: Image format (required)
msg_body->hash	String: Image hash (optional)
msg_body->fsize	Int: File size (bytes) (required)
When msg_type is voice, msg_body is the json returned by uploading voice. The format is as follows:
msg_body->media_id	String: The key returned by the server after the file is uploaded. It is used to generate the downloaded URL (required)
msg_body->media_crc32	The crc32 checksum of a long file, used to download the checksum of the large image (required)
msg_body->duration	Int: Audio duration (required)
msg_body->hash	String: Audio hash (optional)
msg_body->fsize	Int: File size (bytes) (required)

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.
Follow the protocol document: IM Message Protocol
This api can only be sent by admin user

Example Response

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

msg_ctime: time stamp created the message

Error Code

899003: parameter error, Request Body parameter does not meet the requirements
899002: user does not exist, and target_id or from_id does not exist
899016: from_id does not have permission to send messages

Retract message

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

Example Request

Request Header

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

Request Body

Request Params

Parameter	Meaning	Note
msgid	Message msgid
username	Username who send this msg

Example Response

Response Header

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

Error Code

855001: Exceed the withdrawal time. The effective withdrawal time was within 3 minutes after the message was sent.
855003: Revocation message does not exist
855004: Message has been withdrawn

Download and Upload Media Files

Download Document

GET /v1/resource?mediaId={mediaId}

Example Request

Request Header

GET /v1/resource?mediaId={mediaId}

Request Body

Request Params

Parameter	Meaning	Note
mediaId	The mediaId of the resource, including the user’s avatar field

Example Response

Response Header

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

Response Data

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

Upload File

POST /v1/resource?type=image

Example Request

File uploading uses form to upload curl examples:

image uploading curl -F “filename=@/home/test.jpg” https://api.im.jpush.cn/v1/resource?type=image -u “appkey:secret “”

File uploading curl -F “filename=@/home/test.mp3” https://api.im.jpush.cn/v1/resource?type=file -u “appkey:secret”

Voice uploading curl -F “filename=@/home/test.mp3” https://api.im.jpush.cn/v1/resource?type=voice -u “appkey:secret”

Note: The file size is limited to 8m. It only supports image formats currently, including jpg bmp gif png, etc.

Parameter	Meaning	Note
filename	File path of local disk
type	File type: Supports “image”, “file”, “voice”

Response Header

Example Response

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

Response Data

Image Response

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

media_id String: The key returned by the server after the file is uploaded
Crc32 checksum of media_crc32 long file
width int: original width of picture
height int: original height of picture
format String: image format
fsize int: file size (bytes)
hash String: optional, for alternative verification when the crc checksum does not exist

File 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: The key returned by the server after the file is uploaded. It is used to generate the downloaded URL.
Crc32 checksum of media_crc32 long file
hash String; optional, for alternative verification when the crc checksum does not exist
fsize int: file size (bytes)
fname String: file names of sending and receiving

Voice Response

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

media_id String: The key returned by the server after the file is uploaded. It is used to generate the downloaded URL
Crc32 checksum for media_crc32 long file
hash String: optional, for alternative verification when the crc checksum does not exist
fsize int: file size (bytes)
format String: format of source file

Overview of Group Object Fields

Parameter	Meaning	Limits of character length
name	Group name	Byte(0~64)
desc	Group description	Byte(0~250)
owner_username	Owner’s username	Byte(4-128)
MaxMemberCount	Group default to 500 people
ctime	Creation time
mtime	Last Modified Time
avatar	Group avatar

Group Maintenance

Create a group

POST /v1/groups/

Group MaxMemberCount (number limit) definition

Example Request

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

Request Params

owner_username (required)
name (required) group name
- Supported characters: All, including Emoji.
members_username
avatar (optional) group avatar, media_id obtaine when uploading interfaces
desc (optional) group description
- Supported characters: All, including Emoji.
flag (optional) type
- 1 - private group (default)
- 2 - public group
- does not specify the flag, the default is 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 group details

GET /v1/groups/{Group id}

Request Params

Group id: assigned when creating a group

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

Update group information

PUT /v1/groups/{Group id}

Request Params

name: group name
desc: group description
atar: group 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 group

Delete a group.

All members of the group will receive notification that the group has been dissolved.

DELETE /v1/groups/{Group id}

Request Params

Group id

Example Response

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

Update group members

Batch adding and deleting members of a gid group.

Group members will receive notifications of adding and deleting members

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

Request Params

gid: group ID
add json array: Indicates the user to add to the group (optional)
remove json array: Indicates the user to remove from the group (optional)
At least one of the two

Example Request

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

Example Response

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

Add group members V2

Batch add group members

Group members will receive notifications of adding members

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

Request Params

gid group ID

Example Request

["test1", "test2"]

Example Response

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

Delete group members V2

Batch delete group members

Group members will receive notifications of deleting members

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

Request Params

gid 群组ID

Example Request

["test1", "test2"]

Example Response

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

Get a list of group members

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

Request Params

Group id

Example Response

JsonObject UID array

< 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 - common group members
- 1 - Group owner

Get the group list of some user

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

Request Params

username

Example Response

ctime: group
Creation time
Mtime: last modified time of group

< 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 the group list of current application

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

Request Params

Start: number of records started
count: number of records read this time. The maximum is 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"
    }]
}

Block group message

POST /v1/users/{username}/groupsShield

Request Param

Request Body

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

Parameter	Meaning
add	Add the gid array of the group message blocking (optional)
remove	Remove the gid array of group message blocking(optional)

Example Response

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

Ban group members

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

Request body

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

Request Params

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

Example Response

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

Friends

Add friend

POST  /v1/users/{username}/friends

Request Params

json array: Indicates the list of user names to be added. Maximum limit is 500.

Example Request

["user01","user02"]

Example Response

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

Response Data

Error Code

899003: format of Request Body json does not meet the requirements, and json parameter does not meet the requirements;
899002: user does not exist
899070: has added friends

Delete friend

DELETE  /v1/users/{username}/friends

Request Params

The json array represents the list of user names to be removed. The maximum limit is 500.

Example Request

["user01","user02"]

Example Response

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

Response Data

Error Code

899003: format of Request Body json does not meet the requirements, and json parameter does not meet the requirements;
899002: user does not exist;

Update friend notes

PUT  /v1/users/{username}/friends

Request Params

note_name indicates the list of friends to add. Format: Supported characters of byte(64) excludes “\n” “\r”.
others: Other note information, Format: byte(250) supports all characters, including Emoji.
Username;
Support batch modification with maximum limit as 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 Data

Error Code

899003: format of Request Body json does not meet the requirements, and json parameter does not meet the requirements;
899002: user does not exist;

Get friend list

GET  /v1/users/{username}/friends

Request Params

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: format of Request Body json does not meet the requirements, and json parameter does not meet the requirements;
899002: user does not exist;

Cross-application

Cross-application manage group members

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

Request Params

add json array: Indicates the user to add to the group (optional)
remove json array: Indicates the user to remove from the group (optional)
appkey: The appkey of user managed is required

at least one of the add and 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

Remarks: The group wille deleted when the group has no members

Error Code

899003: format of Request Body json does not meet the requirements, and json parameter does not meet the requirements;
899002: user does not exist;
899012: There are not enough places to add group members;
899014: users do not exist in the group
899011: users already exist in the group

Get a group member list across applications

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

Request Params

Group id

Example Response

JsonObject UID: array

< 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 - common group members
- 1 - Group owner

Get user groups across applications

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

Add a blacklist across applications

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: An array of added users
appkey: appkey to which the user belongs

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

Cross-application remove blacklist

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: An array of removed users
appkey: appkey to which the user belongs

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

Cross-application list of blacklists

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

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

Cross-application Do-Not-Disturb Settings

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: single chat DND, supports adding or removing array (optional)
group: group chat DND, supports adding or removing array (optional)
appkey: appkey of targets

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

Error Code

899003: username is illegal;
899002: user does not exist
899051: group does not exist
899052: Set the group message blocj and the setting of group block is already open
899053: Set the group message blocj and the setting of group block is already turned off

Add friends across applications

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 to which the user belongs (required)
json array of users username: up to 500 (required)

Request Body

{
   "appkey":"appkey1",    "users":         [            "username1",         "username2"       ]  
}

Example Response

Response Header

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

Response Data

Delete friends across applications

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: The appkey to which the user belongs (required)
json array of users username: up to 500 (required)

Request Body

 {
   "appkey":"appkey1",    "users":         [            "username1",         "username2"       ]  }

Example Response

Response Header

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

Response Data

Update friend notes across applications

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: The appkey to which the user belongs (required)
note_name: Indicates the list of friends to add. Format: Supported characters of byte(64) excludes “\n” “\r”.
others: Other note information, Format: byte(250) supports all characters, including 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

Cross-application manage chat room members

POST  /cross/chatroom/{room_id}/members

Request Params

add json array: Representing the user to add to the chat room (optional)
remove json array: Indicates the user to delete from the chat room (optional)
appkey: appkey to which the managed user belongs (required)

add/remove:at least one of the two

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

Sensitive Words

Add sensitive words

POST  /v1/sensitiveword

Example Request

Request Header

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

Request Params

Request Body

Array of Sensitive Words: A word with a length of up to 10, defaults to 100 sensitive words, and contact with business team for higher demands

["FUCK"]

Example Response

Response Header

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

Response Data

Modify sensitive words

PUT  /v1/sensitiveword

Example Request

Request Header

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

Request Params

Request Body

old_word: old sensitive word,
new_word: new sensitive 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

Delete sensitive words

DELETE /v1/sensitiveword

Example Request

Request Header

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

Request Params

Request Body

word: sensitive words deleted

{"word":"fuck"}

Example Response

Response Header

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

Response Data

Get a list of sensitive words

GET /v1/sensitiveword

Example Request

Request Header

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

Request Params

start: start number, starting from 0
count: number of queries, up to 2000

Request Body

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
}

Update the status of sensitive words

PUT /v1/sensitiveword/status

Example Request

Request Header

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

Request Params

status: switch status of sensitive words, 1 means turn on filtering, 0 means turn off sensitive word filtering

Request Body

Example Response

Response Header

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

Response Data

Get the status of sensitive words

GET /v1/sensitiveword/status

Example Request

Request Header

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

Request Params

Request Body

Example Response

Response Header

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

Response Data

 {"status": 1}

Overview of chat room fields

Parameter	Meaning	Limits of character length
name	Chat room name (required)	Byte(0~64)
owner_username	Creator of Chat room (required)	Byte (4~128)
description	Chat room description (optional)	Byte(250)
members_username	Member list of chat room (optional)
ctime	Creation time
max_member_count	Maximum number of members
total_member_count	Current total number
flag	Forbidden signs	0 means not banned, 1 means open the ban

Chat room maintenance

Create a chat room

POST /v1/chatroom/

Request Body

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

Request Params

owner_username (required) owner the chat room
name (required) chat room name
members_username (optional) username of members
description (optional) Description

Example Response

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

Get chat room details

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 a list of user’s chat rooms

 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 a list of chat rooms under the app

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
}

Update chat room information

 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 chat room

DELETE /v1/chatroom/{room_id}

Example Request

DELETE  /v1/chatroom/100000

Example Response

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

Modify user banned state

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

Status 0 means not banned, 1 means open the ban (required)

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 a list of chat room members

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

Request Params

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

Add chat room members

 PUT /v1/chatroom/{room_id}/members

Request Params

json array of username: supports up to 3000

Example Response

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

Remove chat room members

DELETE /v1/chatroom/{room_id}/members

Request Params

json array of username: supports up to 3000

Example Response

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

Configuration

Set SDK-API user registration switch

Open or close the SDK-API user registration.

PUT /sdkregister/status?status={status}

Example Request

PUT /sdkregister/status?status=0

Request Params

JSON Array.

status:0 is off, indicating SDK-API registration is not provided, 1 is on

Example Response

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

Get SDK-API user registration switch

get /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 return

Reference documentation of HTTP return code: HTTP-Status-Code

Example Error Response

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

Definition of business error code

IM Server ErrorCode