Skip to main content

User system registration

This page shows how to call Chat RESTful APIs to create and manage the user system, including how to register, modify, delete, ban, and unban a user, get user information, and force a user to log out.

Before calling the following methods, make sure you understand the call frequency limit of the Chat RESTful APIs as described in Limitations.

Common parameters

The following table lists common request and response parameters of the Chat RESTful APIs:

Request parameters

ParameterTypeDescriptionRequired
hostStringThe domain name assigned by the Chat service to access RESTful APIs. For how to get the domain name, see Get the information of your project.Yes
org_nameStringThe unique identifier assigned to each company (organization) by the Chat service. For how to get the org name, see Get the information of the Chat project.Yes
app_nameStringThe unique identifier assigned to each app by the Chat service. For how to get the app name, see Get the information of the Chat project.Yes
usernameStringThe unique login account of the user. The user ID must be 64 characters or less and cannot be empty. The following character sets are supported:
  • 26 lowercase English letters (a-z)
  • 26 uppercase English letters (A-Z)
  • 10 numbers (0-9)
  • "_", "-", "."
  • The username is case insensitive, so Aa and aa are the same username.
  • Ensure that each username under the same app is unique.
  • Do not set this parameter as a UUID, email address, phone number, or other sensitive information.
Yes

Response parameters

ParameterTypeDescription
actionStringThe request method.
organizationStringThe unique identifier assigned to each company (organization) by the Chat service. This is the same as org_name.
applicationStringA unique internal ID assigned to each app by the Chat service. You can safely ignore this parameter.
applicationNameStringThe unique identifier assigned to each app by the Chat service . This is the same as app_name.
uriStringThe request URI.
pathStringThe request path, which is part of the request URL. You can safely ignore this parameter.
entities JSONThe response entity.
entities.uuidStringThe user's UUID. A unique internal identifier generated by the Chat service for the user in this request. This is used for generating the user token.
entities.typeStringThe type of the object. You can safely ignore this parameter.
entities.createdNumberThe Unix timestamp (ms) when the user is registered.
entities.modifiedNumberThe Unix timestamp (ms) when the user information is last modified.
entities.usernameStringThe username. The unique account the user is logged in with.
entities.activatedBoolWhether the user is active:
  • true: The user is active.
  • false: The user is in banned. To use a banned user account, you need to call the unban-user method to unban the account.
  • timestampNumberThe Unix timestamp (ms) of the HTTP response.
    durationNumberThe duration (ms) from when the HTTP request is sent to the time the response is received.

    Authorization

    Chat RESTful APIs require Bearer HTTP authentication. Every time an HTTP request is sent, the following Authorization field must be filled in the request header:


    _1
    Authorization: Bearer ${YourAppToken}

    In order to improve the security of the project, Agora uses a token (dynamic key) to authenticate users before they log in to the chat system. Chat RESTful APIs only support authenticating users using app tokens. For details, see Authentication using App Token.

    Registering a user

    This method creates a user account.

    For each App Key, the call frequency limit of this method is 100 per second.

    HTTP request


    _1
    POST https://{host}/{org_name}/{app_name}/users

    Path parameter

    For the parameters and detailed descriptions, see Common parameters.

    Request header

    ParameterTypeDescriptionRequired
    Content-TypeStringapplication/jsonYes
    AuthorizationStringThe authentication token of the user or admin, in the format of Bearer ${YourAppToken}, where Bearer is a fixed character, followed by an English space, and then the obtained token value.Yes

    Request body

    The request body is a JSON object, which contains the following fields:

    FieldTypeDescriptionRequired
    usernameStringThe unique login account of the user. The username must be 64 bytes or less and cannot be empty.Yes
    passwordStringThe user's login password. The length cannot exceed 64 bytes.Yes
    nicknameStringThe nickname of the user displayed in the notification bar of the message push when the message is pushed. The length cannot exceed 100 bytes. The default value is null.
    This field is used to set the user nickname displayed in the message push, not the user nickname in the user attributes.
    Yes

    HTTP response

    Response body

    If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:

    FieldTypeDescription
    entities.nicknameStringThe nickname of the user displayed in the notification bar of the message push when the message is pushed.
    This field is not the user nickname of the user attributes.

    For other fields and detailed descriptions, see Common parameters.

    If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible reasons.

    Example

    Request example


    _7
    # Replace {YourAppToken} with the app token generated in your server.
    _7
    curl -X POST -H 'Content-Type: application/json' -H 'Authorization:Bearer {YourAppToken}' -i "https://XXXX/XXXX/XXXX/users" -d '
    _7
    {
    _7
    "username": "user1",
    _7
    "password": "123",
    _7
    "nickname": "testuser"
    _7
    }'

    Response example


    _21
    {
    _21
    "action": "post",
    _21
    "application": "8be024f0-XXXX-XXXX-b697-5d598d5f8402",
    _21
    "path": "/users",
    _21
    "uri": "https://a1.agora.com/XXXX/XXXX/users",
    _21
    "entities": [
    _21
    {
    _21
    "uuid": "0ffe2d80-XXXX-XXXX-8d66-279e3e1c214b",
    _21
    "type": "user",
    _21
    "created": 1542795196504,
    _21
    "modified": 1542795196504,
    _21
    "username": "user1",
    _21
    "activated": true,
    _21
    "nickname": "testuser"
    _21
    }
    _21
    ],
    _21
    "timestamp": 1542795196515,
    _21
    "duration": 0,
    _21
    "organization": "XXXX",
    _21
    "applicationName": "XXXX"
    _21
    }

    Registering multiple users

    This method registers multiple users within one request.

    For each App Key, the call frequency limit of this method is 100 per second.

    HTTP request


    _1
    POST https://{host}/{org_name}/{app_name}/users

    Path parameter

    For the parameters and detailed descriptions, see Common parameters .

    Request header

    ParameterTypeDescription
    Content-TypeStringapplication/json
    AuthorizationStringThe authentication token of the user or admin, in the format of Bearer ${YourAppToken}, where Bearer is a fixed character, followed by an English space, and then the obtained token value.

    Request body

    The request body is a JSON object, which contains the following fields:

    FieldTypeDescriptionRequired
    usernameStringThe unique login account of the user. The username must be 64 bytes or less and cannot be empty.Yes
    passwordStringThe user's login password. The length cannot exceed 64 bytes.Yes
    nicknameStringThe nickname of the user displayed in the notification bar of the message push when the message is pushed. The length cannot exceed 100 bytes. The default value is null.
    This field is used to set the user nickname displayed in the message push, not the user nickname in the user attributes.
    Yes

    HTTP response

    Response body

    If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:

    FieldTypeDescription
    entities.nicknameStringThe nickname of the user displayed in the notification bar of the message push when the message is pushed.
    This field is not the user nickname of the user attributes.
    dataJSONArrayThe details of the response. In this data array, the username and reason for the registration failure are displayed.

    For other fields and detailed descriptions, see Common parameters.

    If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible reasons.

    Example

    Request example 1

    Registering 2 users:


    _12
    # Replace {YourAppToken} with the app token generated in your server.
    _12
    curl -X POST -H 'Content-Type: application/json' -H 'Authorization:Bearer {YourAppToken}' -i "https://XXXX/XXXX/XXXX/users" -d '
    _12
    {
    _12
    "username":"user1",
    _12
    "password":"123",
    _12
    "nickname":"testuser1"
    _12
    },
    _12
    {
    _12
    "username":"user2",
    _12
    "password":"456",
    _12
    "nickname":"testuser2"
    _12
    }'

    Response example 1


    _31
    {
    _31
    "action": "post",
    _31
    "application": "22bcffa0-XXXX-XXXX-9df8-516f6df68c6d",
    _31
    "path": "/users",
    _31
    "uri": "https://XXXX/XXXX/XXXX/users",
    _31
    "entities": [
    _31
    {
    _31
    "uuid": "278b5e60-XXXX-XXXX-8f9b-d5d83ebec806",
    _31
    "type": "user",
    _31
    "created": 1541587920710,
    _31
    "modified": 1541587920710,
    _31
    "username": "user1",
    _31
    "activated": true,
    _31
    "nickname": "testuser1"
    _31
    },
    _31
    {
    _31
    "uuid": "278bac80-XXXX-XXXX-b192-73e4cd5078a5",
    _31
    "type": "user",
    _31
    "created": 1541587920712,
    _31
    "modified": 1541587920712,
    _31
    "username": "user2",
    _31
    "activated": true,
    _31
    "nickname": "testuser2"
    _31
    }
    _31
    ],
    _31
    "timestamp": 1541587920714,
    _31
    "data": [],
    _31
    "duration": 0,
    _31
    "organization": "XXXX",
    _31
    "applicationName": "XXXX"
    _31
    }

    Request example 2

    If the request body contains a user3 that has previously been registered, the registration of user3 fails while those of user1 and user2 succeed. The failure is reported in the data array of the response body.


    _17
    # Replace {YourAppToken} with the app token generated in your server.
    _17
    curl -X POST -H 'Content-Type: application/json' -H 'Authorization:Bearer {YourAppToken}' -i "https://XXXX/XXXX/XXXX/users" -d '
    _17
    {
    _17
    "username":"user1",
    _17
    "password":"123",
    _17
    "nickname":"testuser1"
    _17
    },
    _17
    {
    _17
    "username":"user2",
    _17
    "password":"456",
    _17
    "nickname":"testuser2"
    _17
    },
    _17
    {
    _17
    "username":"user3",
    _17
    "password":"789",
    _17
    "nickname":"testuser3"
    _17
    }'

    Response example 2


    _36
    {
    _36
    "action": "post",
    _36
    "application": "22bcffa0-XXXX-XXXX-9df8-516f6df68c6d",
    _36
    "path": "/users",
    _36
    "uri": "https://XXXX/XXXX/XXXX/users",
    _36
    "entities": [
    _36
    {
    _36
    "uuid": "278b5e60-XXXX-XXXX-8f9b-d5d83ebec806",
    _36
    "type": "user",
    _36
    "created": 1541587920710,
    _36
    "modified": 1541587920710,
    _36
    "username": "user1",
    _36
    "activated": true,
    _36
    "nickname": "testuser1"
    _36
    },
    _36
    {
    _36
    "uuid": "278bac80-XXXX-XXXX-b192-73e4cd5078a5",
    _36
    "type": "user",
    _36
    "created": 1541587920712,
    _36
    "modified": 1541587920712,
    _36
    "username": "user2",
    _36
    "activated": true,
    _36
    "nickname": "testuser2"
    _36
    }
    _36
    ],
    _36
    "timestamp": 1541587920714,
    _36
    "data": [
    _36
    {
    _36
    "username": "user3",
    _36
    "registerUserFailReason": "the user3 already exists"
    _36
    }
    _36
    ],
    _36
    "duration": 0,
    _36
    "organization": "XXXX",
    _36
    "applicationName": "XXXX"
    _36
    }

    Querying a user

    This method queries the detailed information of the specified user.

    For each App Key, the call frequency limit of this method is 100 per second.

    HTTP request


    _1
    GET https://{host}/{org_name}/{app_name}/users/{username}

    Path parameter

    For the parameters and detailed descriptions, see Common parameters.

    Request header

    ParameterTypeDescriptionRequired
    AcceptStringapplication/jsonYes
    AuthorizationStringThe authentication token of the user or admin, in the format of Bearer ${YourAppToken}, where Bearer is a fixed character, followed by an English space, and then the obtained token value.Yes

    HTTP response

    Response body

    If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:

    FieldTypeDescription
    entities.nicknameStringThe nickname of the user displayed in the notification bar of the message push when the message is pushed.
    This field is not the user nickname of the user attributes.
    countNumberThe number of users.

    For other fields and detailed descriptions, see Common parameters.

    If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible reasons.

    Example

    Request example


    _2
    # Replace {YourAppToken} with the app token generated in your server.
    _2
    curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer {YourAppToken}' 'http://XXXX/XXXX/XXXX/users/XXXX'

    Response example


    _19
    {
    _19
    "action": "get",
    _19
    "path": "/users",
    _19
    "uri": "http://XXXX/XXXX/XXXX/users/XXXX",
    _19
    "entities": [
    _19
    {
    _19
    "uuid": "0ffe2d80-XXXX-XXXX-8d66-279e3e1c214b",
    _19
    "type": "user",
    _19
    "created": 1542795196504,
    _19
    "modified": 1542795196504,
    _19
    "username": "XXXX",
    _19
    "activated": true,
    _19
    "nickname": "testuser"
    _19
    }
    _19
    ],
    _19
    "timestamp": 1542798985011,
    _19
    "duration": 1,
    _19
    "count": 1
    _19
    }

    Querying multiple users

    This method queries the information of multiple users in ascending order of their registration time.

    For each App Key, the call frequency limit of this method is 100 per second.

    HTTP request


    _1
    GET https://{host}/{org_name}/{app_name}/users

    Path parameter

    For the parameters and detailed descriptions, see Common parameters.

    Query parameters

    ParameterTypeDescriptionRequired
    limitNumberThe number of users whose information you want to query. The default value is 10, and the value range is [1,100].
    The user list is displayed in ascending order of their registration time by default.
    No
    cursorStringThe cursor used for paginating the user lists.
    You do not need to set cursor at the first query. When the request succeeds, you can get the user list on the first page. You can also get the cursor from the response body, and pass the cursor in the URL of the next request, until there is no longer a cursor field in the response body, which means that all the users in the app have been queried.
    No

    Request header

    ParameterTypeDescriptionRequired
    AcceptStringapplication/jsonYes
    AuthorizationStringThe authentication token of the user or admin, in the format of Bearer ${YourAppToken}, where Bearer is a fixed character, followed by an English space, and then the obtained token value.Yes

    HTTP response

    Response body

    If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:

    ParameterTypeDescription
    entities.nicknameStringThe nickname of the user displayed in the notification bar of the message push when the message is pushed. This field is not the user nickname of the user attributes.
    cursorStringThe cursor used for paginating the user lists.
    You do not need to set cursor at the first query. When the request succeeds, you can get the cursor from the response body, and pass this cursor in the URL of the next query, until there is no longer a cursor filed in the response body, which indicates that all the users in the app have been queried.
    countNumberThe number of users.

    For other fields and detailed descriptions, see Common parameters.

    If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible reasons.

    Example

    Request example 1

    Querying the information list of two users in ascending order of their registration time:


    _2
    # Replace {YourAppToken} with the app token generated in your server.
    _2
    curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer {YourAppToken}' 'http://XXXX/XXXX/XXXX/users?limit=2'

    Response example 1

    Return the information list of the 2 users:


    _32
    {
    _32
    "action": "get",
    _32
    "params": {
    _32
    "limit": ["2"]
    _32
    },
    _32
    "path": "/users",
    _32
    "uri": "http://XXXX/XXXX/XXXX/users",
    _32
    "entities": [
    _32
    {
    _32
    "uuid": "ab90eff0-XXXX-XXXX-9174-8f161649a182",
    _32
    "type": "user",
    _32
    "created": 1542356511855,
    _32
    "modified": 1542356511855,
    _32
    "username": "XXXX",
    _32
    "activated": true,
    _32
    "nickname": "testuser1"
    _32
    },
    _32
    {
    _32
    "uuid": "b2aade90-XXXX-XXXX-a974-f3368f82e4f1",
    _32
    "type": "user",
    _32
    "created": 1542356523769,
    _32
    "modified": 1542356523769,
    _32
    "username": "user2",
    _32
    "activated": true,
    _32
    "nickname": "testuser2"
    _32
    }
    _32
    ],
    _32
    "timestamp": 1542558467056,
    _32
    "duration": 1,
    _32
    "cursor": "LTgzNDAxMjM3OToxTEFnNE9sNEVlaVQ0UEdhdmJNR2tB",
    _32
    "count": 2
    _32
    }

    Request example 2

    Use the cursor in response example 1 to query the user list on the next page in ascending order of their registration time. The number of users on this page is two:


    _2
    # Replace {YourAppToken} with the app token generated in your server.
    _2
    curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer {YourAppToken}' 'http://XXXX/XXXX/XXXX/users?limit=2&cursor=LTgzNDAxMjM3OToxTEFnNE9sNEVlaVQ0UEdhdmJNR2tB'

    Response example 2

    Continue to return a list of information for two users:


    _32
    {
    _32
    "action": "get",
    _32
    "params": {
    _32
    "cursor": ["LTgzNDAxMjM3OToxTEFnNE9sNEVlaVQ0UEdhdmJNR2tB"],
    _32
    "limit": ["2"]
    _32
    },
    _32
    "path": "/users",
    _32
    "uri": "http://XXXX/XXXX/XXXX/users",
    _32
    "entities": [
    _32
    {
    _32
    "uuid": "fef7f250-XXXX-XXXX-ba39-0fed7dcc3cdd",
    _32
    "type": "user",
    _32
    "created": 1542361376245,
    _32
    "modified": 1542361376245,
    _32
    "username": "XXXX",
    _32
    "activated": true,
    _32
    "nickname": "testuser3"
    _32
    },
    _32
    {
    _32
    "uuid": "gufhj730-XXXX-XXXX-bc68-d8ij7dc3uyac",
    _32
    "type": "user",
    _32
    "created": 1542361376978,
    _32
    "modified": 1542361376978,
    _32
    "username": "XXXX",
    _32
    "activated": true,
    _32
    "nickname": "testuser4"
    _32
    }
    _32
    ],
    _32
    "timestamp": 1542559337702,
    _32
    "duration": 2,
    _32
    "count": 2
    _32
    }

    Deleting a user

    This method deletes the specified user. If the deleted user is the admin of a chat group or chat room, the group or chat room managed by that user is also deleted.

    For each App Key, the call frequency limit of this method is 100 per second.

    HTTP request


    _1
    DELETE https://{host}/{org_name}/{app_name}/users/{username}

    Path parameter

    For the parameters and detailed descriptions, see Common parameters.

    Request header

    ParameterTypeDescriptionRequired
    AcceptStringapplication/jsonYes
    AuthorizationStringThe authentication token of the user or admin, in the format of Bearer ${YourAppToken}, where Bearer is a fixed character, followed by an English space, and then the obtained token value.Yes

    HTTP response

    Response body

    If the returned HTTP status code is 200, the request succeeds. For fields and descriptions of the response body, see Common parameters.

    If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible reasons.

    Example

    Request example


    _2
    # Replace {YourAppToken} with the app token generated in your server.
    _2
    curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer {YourAppToken}' 'http://XXXX/XXXX/XXXX/users/user1'

    Response example


    _21
    {
    _21
    "action": "delete",
    _21
    "applicationName": "XXXX"
    _21
    "path": "/users",
    _21
    "uri": "https://XXXX/XXXX/XXXX/users",
    _21
    "entities": [
    _21
    {
    _21
    "uuid": "ab90eff0-XXXX-XXXX-9174-8f161649a182",
    _21
    "type": "user",
    _21
    "created": 1542356511855,
    _21
    "modified": 1542356511855,
    _21
    "username": "XXXX",
    _21
    "activated": true,
    _21
    "nickname": "user1"
    _21
    }
    _21
    ],
    _21
    "timestamp": 1542559539776,
    _21
    "duration": 39,
    _21
    "organization": "XXXX",
    _21
    "applicationName": "XXXX"
    _21
    }

    Deleting multiple users

    This method deletes multiple users in the app. If the deleted users include group or chat room admins, the groups and chat rooms managed by those users are also deleted.

    For each App Key, the call frequency limit of this method is 30 per second.

    HTTP request


    _1
    DELETE https://{host}/{org_name}/{app_name}/users

    Path parameter

    For the parameters and detailed descriptions, see Common parameters .

    Request header

    ParameterTypeDescriptionRequired
    AcceptStringapplication/jsonYes
    AuthorizationStringThe authentication token of the user or admin, in the format of Bearer ${YourAppToken}, where Bearer is a fixed character, followed by an English space, and then the obtained token value.Yes

    HTTP response

    Response body

    If the returned HTTP status code is 200, the request is successful. For fields and descriptions of the response body, see Public parameter.

    If the returned HTTP status code is not 200, the request fails. You can refer to the Status code for possible reasons.

    Example

    Request example


    _2
    # Replace {YourAppToken} with the app token generated in your server.
    _2
    curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer {YourAppToken}' 'http://XXXX/XXXX/XXXX/users'

    Response example


    _21
    {
    _21
    "action": "delete",
    _21
    "applicationName": "XXXX"
    _21
    "path": "/users",
    _21
    "uri": "https://XXXX/XXXX/XXXX/users",
    _21
    "entities": [
    _21
    {
    _21
    "uuid": "ab90eff0-XXXX-XXXX-9174-8f161649a182",
    _21
    "type": "user",
    _21
    "created": 1542356511855,
    _21
    "modified": 1542356511855,
    _21
    "username": "XXXX",
    _21
    "activated": true,
    _21
    "nickname": "user1"
    _21
    }
    _21
    ],
    _21
    "timestamp": 1542559539776,
    _21
    "duration": 39,
    _21
    "organization": "XXXX",
    _21
    "applicationName": "XXXX"
    _21
    }

    Modifying the password

    This method modifies the user password. You do not need to provide the original password.

    For each App Key, the call frequency limit of this method is 100 per second.

    HTTP request


    _1
    PUT https://{host}/{org_name}/{app_name}/users/{username}/password

    Path parameter

    For the parameters and detailed descriptions, see Common parameters.

    Request header

    ParameterTypeDescriptionRequired
    Content-TypeStringapplication/jsonYes
    AcceptStringapplication/jsonYes
    AuthorizationStringThe authentication token of the user or admin, in the format of Bearer ${YourAppToken}, where Bearer is a fixed character, followed by an English space, and then the obtained token value.Yes

    Request body

    The request body is a JSON object, which contains the following fields:

    FieldTypeDescriptionRequired
    newpasswordStringThe new user login password. The length cannot exceed 64 bytes.Yes

    For other fields and detailed descriptions, see Common parameters.

    HTTP response

    Response body

    If the returned HTTP status code is 200, the request succeeds. For fields and descriptions of the response body, see Common parametes.

    If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible reasons.

    Example

    Request example


    _2
    # Replace {YourAppToken} with the app token you generated on the server, and {YourPassword} with the new password you set
    _2
    curl -X PUT -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer {YourAppToken}' -d '{ "newpassword": "{YourPassword}" }' ' http://XXXX/XXXX/XXXX/users/user1/password'

    Response example


    _5
    {
    _5
    "action": "set user password",
    _5
    "timestamp": 1542595598924,
    _5
    "duration": 8
    _5
    }

    Banning a user

    This method disables a user account. The user goes offline immediately and is not able to log in until the ban is lifted.

    For each App Key, the call frequency limit of this method is 100 per second.

    HTTP request


    _1
    POST https://{host}/{org_name}/{app_name}/users/{username}/deactivate

    Path parameter

    For the parameters and detailed descriptions, see Common parameters.

    Request header

    ParameterTypeDescriptionRequired
    Content-TypeStringapplication/jsonYes
    AcceptStringapplication/jsonYes
    AuthorizationStringThe authentication token of the user or admin, in the format of Bearer ${YourAppToken}, where Bearer is a fixed character, followed by an English space, and then the obtained token value.Yes

    HTTP response

    Response body

    If the returned HTTP status code is 200, the request is succeeds and the response body contains the following fields:

    FieldTypeDescription
    entities.nicknameStringThe nickname of the user displayed in the notification bar of the message push when the message is pushed.
    This field is not the user nickname of the user attributes.

    For other fields and detailed descriptions, see Common parameters.

    If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible reasons.

    Example

    Request example


    _2
    # Replace {YourAppToken} with the app token generated in your server.
    _2
    curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer {YourAppToken}' 'http://XXXX/XXXX/XXXX/users/user1/deactivate'

    Response example


    _16
    {
    _16
    "action": "Deactivate user",
    _16
    "entities": [
    _16
    {
    _16
    "uuid": "4759aa70-XXXX-XXXX-925f-6fa0510823ba",
    _16
    "type": "user",
    _16
    "created": 1542595573399,
    _16
    "modified": 1542597578147,
    _16
    "username": "XXXX",
    _16
    "activated": false,
    _16
    "nickname": "user"
    _16
    }
    _16
    ],
    _16
    "timestamp": 1542602157258,
    _16
    "duration": 12
    _16
    }

    Unbanning a user

    This method unbans a deactivated user account. After the ban is lifted, the user can log in to Chat.

    For each App Key, the call frequency limit of this method is 100 per second.

    HTTP request


    _1
    POST https://{host}/{org_name}/{app_name}/users/{username}/activate

    Path parameter

    For the parameters and detailed descriptions, see Common parameters.

    Request header

    ParameterTypeDescriptionRequired
    Content-TypeStringapplication/jsonYes
    AcceptStringapplication/jsonYes
    AuthorizationStringThe authentication token of the user or admin, in the format of Bearer ${YourAppToken}, where Bearer is a fixed character, followed by an English space, and then the obtained token value.Yes

    HTTP response

    Response body

    If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:

    FieldTypeDescription
    nicknameStringThe nickname of the user displayed in the notification bar of the message push when the message is pushed.
    This field is not the user nickname of the user attributes.

    For other fields and detailed descriptions, see Common parameters. If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible reasons.

    Example

    Request example


    _2
    # Replace {YourAppToken} with the app token generated in your server.
    _2
    curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer {YourAppToken}' 'http://XXXX/XXXX/XXXX/users/user1/activate'

    Response example


    _5
    {
    _5
    "action": "activate user",
    _5
    "timestamp": 1542602404132,
    _5
    "duration": 9
    _5
    }

    Forcing a user offline

    This method forcibly moves a user offline. The offline user must log in again to use the Chat service.

    For each App Key, the call frequency limit of this method is 100 per second.

    HTTP request


    _1
    POST https://{host}/{org_name}/{app_name}/users/{username}/disconnect

    Path parameter

    For the parameters and detailed descriptions, see Common parameters.

    Request header

    ParameterTypeDescriptionRequired
    Content-TypeStringapplication/jsonYes
    AcceptStringapplication/jsonYes
    AuthorizationStringThe authentication token of the user or admin, in the format of Bearer ${YourAppToken}, where Bearer is a fixed character, followed by an English space, and then the obtained token value.Yes

    HTTP response

    Response body

    If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:

    FieldTypeDescription
    dataJSONThe details of the response.
    data.resultBoolThe logout result, only displayed as true, which indicates that the user has been forced offline.

    For other fields and detailed descriptions, see Common parameters.

    If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible reasons.

    Example

    Request example


    _2
    # Replace {YourAppToken} with the app token generated in your server.
    _2
    curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer {YourAppToken}' 'http://XXXX/XXXX/XXXX/users/XXXX/disconnect'

    Response example


    _13
    {
    _13
    "uri": "http://XXXX/XXXX/XXXX/users/XXXX/disconnect",
    _13
    "timestamp": 1642053735842,
    _13
    "organization": "1122161011178276",
    _13
    "application": "22bcffa0-XXXX-XXXX-9df8-516f6df68c6d",
    _13
    "entities": [],
    _13
    "action": "get",
    _13
    "data": {
    _13
    "result": true
    _13
    },
    _13
    "duration": 0,
    _13
    "applicationName": "XXXX"
    _13
    }

    Querying the online state of a user

    This method queries whether a user is online.

    For each App Key, the call frequency limit of this method is 100 per second.

    HTTP request


    _1
    GET https://{host}/{org_name}/{app_name}/users/{username}/status

    Path parameter

    For the parameters and detailed descriptions, see Common parameters.

    Request header

    ParameterTypeDescriptionRequired
    Content-TypeStringapplication/jsonYes
    AuthorizationStringThe authentication token of the user or admin, in the format of Bearer ${YourAppToken}, where Bearer is a fixed character, followed by an English space, and then the obtained token value.Yes

    HTTP response

    Response body

    If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:

    ParameterDescription
    usernameThe online state of a user, in the format of "username": "online state". For example, if user1 is online, returns "user1": "online". Otherwise, returns "user1": "offline".

    For the parameters and detailed descriptions, see Common parameters.

    If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible reasons.

    Example

    Request example


    _2
    # Replace {YourAppToken} with the app token generated in your server.
    _2
    curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer {YourAppToken}' 'http://XXXX/XXXX/XXXX/users/user1/status'

    Response example


    _11
    {
    _11
    "action": "get",
    _11
    "uri": "http://XXXX/XXXX/XXXX/users/user1/status",
    _11
    "entities": [],
    _11
    "data": {
    _11
    "user1": "offline"
    _11
    },
    _11
    "timestamp": 1542601284531,
    _11
    "duration": 4,
    _11
    "count": 0
    _11
    }

    Querying the online state of multiple users

    This method queries whether multiple users are online.

    For each App Key, the call frequency limit of this method is 50 per second.

    HTTP request


    _1
    POST https://{host}/{org_name}/{app_name}/users/batch/status

    Path parameter

    For the parameters and detailed descriptions, see Common parameters.

    Request header

    ParameterTypeDescriptionRequired
    Content-TypeStringapplication/jsonYes
    AuthorizationStringThe authentication token of the user or admin, in the format of Bearer ${YourAppToken}, where Bearer is a fixed character, followed by an English space, and then the obtained token value.Yes

    Request body

    ParameterTypeDescription
    usernamesArrayThe users whose online state you want to query. You can specify a maximum of 100 usernames at the same time.

    HTTP response

    Response body

    If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:

    ParameterDescription
    usernameThe online state of a user, in the format of "username": "online state". For example, if user1 is online, returns "user1": "online". Otherwise, returns "user1": "offline".

    If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible reasons.

    Example

    Request example


    _2
    # Replace {YourAppToken} with the app token generated in your server.
    _2
    curl -X POST http://XXXX/XXXX/XXXX/users/batch/status -H 'Authorization: Bearer {YourAppToken}' -H 'Content-Type: application/json' -d '{"usernames":["user1","user2"]}'

    Response example

    This API does not check whether the specified usernames are valid. If the specified username does not exist, the state of this user is reported as offline.


    _13
    {
    _13
    "action": "get batch user status",
    _13
    "data": [
    _13
    {
    _13
    "user1": "offline"
    _13
    },
    _13
    {
    _13
    "user2": "offline"
    _13
    }
    _13
    ],
    _13
    "timestamp": 1552280231926,
    _13
    "duration": 4
    _13
    }

    Querying the number of offline messages

    This method queries the number of offline messages a user has, and whether or not they have been delivered.

    For each App Key, the call frequency limit of this method is 100 per second.

    HTTP request


    _1
    GET https://{host}/{org_name}/{app_name}/users/{owner_username}/offline_msg_count

    Path parameter

    ParameterTypeRequiredDescription
    owner_usernameStringYesThe users whose number of offline messages you want to query.

    For the parameters and detailed descriptions, see Common parameters.

    Request header

    ParameterTypeDescriptionRequired
    Content-TypeStringapplication/jsonYes
    AuthorizationStringThe authentication token of the user or admin, in the format of Bearer ${YourAppToken}, where Bearer is a fixed character, followed by an English space, and then the obtained token value.Yes

    HTTP response

    Request body

    If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:

    ParameterDescription
    usernameThe number of offline messages a user has, whether or not they have been delivered, in the format of "username": "number of offline messages". For example, if user1 does not have offline messages, returns "user1": "0".

    If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible reasons.

    Example

    Request example


    _2
    # Replace {YourAppToken} with the app token generated in your server.
    _2
    curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer {YourAppToken}' 'http://XXXX/XXXX/XXXX/users/user1/offline_msg_count'

    Response example


    _11
    {
    _11
    "action": "get",
    _11
    "uri": "http://XXXX/XXX/XXXX/users/XXX/offline_msg_count",
    _11
    "entities": [],
    _11
    "data": {
    _11
    "user1": 0
    _11
    },
    _11
    "timestamp": 1542601518137,
    _11
    "duration": 3,
    _11
    "count": 0
    _11
    }

    Querying the delivery state of an offline message

    This method queries the delivery state of an offline message.

    For each App Key, the call frequency limit of this method is 100 per second.

    HTTP request


    _1
    GET https://{host}/{org_name}/{app_name}/users/{username}/offline_msg_status/{msg_id}

    Path parameter

    ParameterTypeRequiredDescription
    usernameStringYesThe user whose offline message's delivery states you want to query.
    msg_idStringYesThe message of which you want to query the delivery state.

    For the parameters and detailed descriptions, see Common parameters.

    Request header

    ParameterTypeDescriptionRequired
    Content-TypeStringapplication/jsonYes
    AuthorizationStringThe authentication token of the user or admin, in the format of Bearer ${YourAppToken}, where Bearer is a fixed character, followed by an English space, and then the obtained token value.Yes

    HTTP response

    Response body

    If the returned HTTP status code is 200, the request succeeds, and the response body contains the following fields:

    ParameterDescription
    msg_idThe delivery state of an offline message, in the format of "message id": "delivery state". The delivery state contains:
  • delivered: The offline message has been delivered to the user.
  • undelivered: The offline message is temporarily stored at the server and has not been pulled from the server and delivered to the user.
  • If the returned HTTP status code is not 200, the request fails. You can refer to Status codes for possible reasons.

    Example

    Request example


    _2
    # Replace {YourAppToken} with the app token generated in your server.
    _2
    curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer {YourAppToken}' 'http://XXXX/XXXX/XXXX/users/user1/offline_msg_status/123'

    Response example


    _11
    {
    _11
    "action": "get",
    _11
    "uri": "http://XXXX/XXXX/XXXX/users/user1/offline_msg_status/123",
    _11
    "entities": [],
    _11
    "data": {
    _11
    "123": "delivered"
    _11
    },
    _11
    "timestamp": 1542601830084,
    _11
    "duration": 5,
    _11
    "count": 0
    _11
    }

    Status codes

    For details, see HTTP Status Codes.

    Page Content