User attributes management

User attributes refers to the label information added for the user, including key-value pairs.

This page shows how to call Chat RESTful APIs to manage user attributes, including adding, deleting, modifying, and retrieving user attributes.

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

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

​

Parameter	Type	Description	Required
host	String	The 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_name	String	The unique identifier assigned to each company (organization) by the Chat service. For how to get the org name, see Get the information of your project.	Yes
app_name	String	The unique identifier assigned to each app by the Chat service. For how to get the app name, see Get the information of your project.	Yes
username	String	The 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

​

Parameter	Type	Description
action	String	The request method.
organization	String	The unique identifier assigned to each company (organization) by the Chat service. This is the same as org_name.
application	String	A unique internal ID assigned to each app by the Chat service. You can safely ignore this parameter.
applicationName	String	The unique identifier assigned to each app by the Chat service . This is the same as app_name.
uri	String	The request URI.
entities	JSON	The response entity.
timestamp	Number	The Unix timestamp (ms) of the HTTP response.
duration	Number	The duration (ms) from when the HTTP request is sent to the time the response is received.

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.

Sets user attributes for a user. User attributes are composed of multiple key-value pairs of attribute names and attribute values, and each attribute name has one corresponding attribute value.

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

The total length of attributes for one user cannot exceed 2 KB, and the total length of attributes for all users under an app cannot exceed 10 GB.

_1

PUT https://{host}/{org_name}/{app_name}/metadata/user/{username}

For the parameters and detailed descriptions, see Common parameters.

Parameter	Type	Description	Required
Content-Type	String	application/x-www-form-urlencoded	Yes
Authorization	String	The 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

The request body is in the format of JSON String, and the length cannot exceed 4 KB. The request body contains the following fields:

Field	Type	Description	Required
Key	String	Attribute name	Yes
Value	String	Attribute value	Yes

When you call this RESTful API to set the user's nickname, avatar, contact information, email address, gender, signature, birthday and extension fields, you must pass in the following keys to make sure that the client can obtain the settings from the server:

Field	Type	Description
nickname	String	The user nickname, which can contain at most 64 characters.
avatarurl	String	The user avatar URL, which can contain at most 256 characters.
phone	String	The user's phone number, which can contain at most 32 characters.
mail	String	The user's email address, which can contain at most 64 characters.
gender	Number	The user gender: 1：Male; 2：Female; (Default) 0: Unknown; Other values are invalid.
sign	String	The user's signature, which can contain at most 256 characters.
birth	String	The user's birthday, which can contain at most 64 characters.
ext	String	The extension fields.

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

Parameter	Type	Description
data	JSON	The details of the response. It contains the user attribute key-value pair you set in this request.

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.

The user attributes used in this example are named ext, nickname, and avatar. You can customize user attributes according to actual business scenarios.

_2

# Replace {YourAppToken} with the app token generated in your server.

_2

curl -X PUT -H 'Content-Type: application/x-www-form-urlencoded' -H 'Authorization: Bearer {YourAppToken}' -d 'avatarurl=http://www.agorachat.com/avatar.png&ext=ext&nickname=nickname' 'http://XXXX/XXXX/XXXX/metadata/user/XXXX'

_9

{

_9

"timestamp": 1620445147011,

_9

"data": {

_9

"ext": "ext",

_9

"nickname": "nickname",

_9

"avatarurl": "http://XXXX.png"

_9

},

_9

"duration": 166

_9

}

Retrieves the user attributes of the specified user.

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

_1

GET https://{host}/{org_name}/{app_name}/metadata/user/{username}

For the parameters and detailed descriptions, see Common parameters.

Parameter	Type	Description	Required
Content-Type	String	application/json	Yes
Authorization	String	The 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

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

Parameter	Type	Description
data	JSON	The details of the response. It contains all user attribute key-value pairs for this user. If data is empty, ensure that the username exists or the user has at least one user attribute.

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.

_2

# Replace {YourAppToken} with the app token generated in your server.

_2

curl -X GET -H 'Authorization: Bearer {YourAppToken}' -H 'Content-Type: application/json''http://XXXX/XXXX/XXXX/metadata/user/XXXX'

_9

{

_9

"timestamp": 1620445147011,

_9

"data": {

_9

"ext": "ext",

_9

"nickname": "nickname",

_9

"avatar": "http://XXXX.png"

_9

},

_9

"duration": 166

_9

}

Retrieves the user attributes of multiple users by specifying the user name list and user attribute list.

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

_1

POST https://{host}/{org_name}/{app_name}/metadata/user/get

For the parameters and detailed descriptions, see Common parameters.

Parameter	Type	Description	Required
Content-Type	String	application/json	Yes
Authorization	String	The 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

The request body is a JSON object with the following fields:

Parameter	Type	Description	Required
targets	JSONArray	A list of usernames to be queried, containing up to 100 usernames.	Yes
properties	JSONArray	A list of attribute names to be queried.	Yes

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

Parameter	Type	Description
data	JSON	The details of the response. It contains all user attribute key-value pairs for this user. If data is empty, ensure that the username exists or the user has at least one user attribute.

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.

_13

# Replace {YourAppToken} with the app token generated in your server.

_13

curl -X POST -H 'Authorization: Bearer {YourAppToken}' -H 'Content-Type: application/json' -d '{

_13

"properties": [

_13

"avatar",

_13

"ext",

_13

"nickname"

_13

],

_13

"targets": [

_13

"user1",

_13

"user2",

_13

"user3"

_13

]

_13

}' 'http://XXXX/XXXX/XXXX/metadata/user/get'

_21

{

_21

"timestamp": 1620448826647,

_21

"data": {

_21

"user1": {

_21

"ext": "ext",

_21

"nickname": "nickname",

_21

"avatar": "http://XXXX.png"

_21

},

_21

"user2": {

_21

"ext": "ext",

_21

"nickname": "nickname",

_21

"avatar": "http://XXXX.png"

_21

},

_21

"user3": {

_21

"ext": "ext",

_21

"nickname": "nickname",

_21

"avatar": "http://XXXX.png"

_21

}

_21

},

_21

"duration": 3

_21

}

Retrieves the total size of user attributes under the app.

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

_1

GET https://{host}/{org_name}/{app_name}/metadata/user/capacity

For the parameters and detailed descriptions, see Common parameters.

Parameter	Type	Description	Required
Authorization	String	The 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

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

Parameter	Type	Description
data	Number	The total length of the user attributes under the app, in bytes.

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.

_1

curl -X GET -H 'Authorization: Bearer {YourAppToken}''http://XXXX/XXXX/XXXX/metadata/user/capacity'

_5

{

_5

"timestamp": 1620447051368,

_5

"data": 1673,

_5

"duration": 55

_5

}

Deletes all the user attributes of the specified user.

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

_1

DELETE https://{host}/{org_name}/{app_name}/metadata/user/{username}

For the parameters and detailed descriptions, see Common parameters.

Parameter	Type	Description	Required
Authorization	String	The 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

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

Parameter	Type	Description
data	Bool	Whether the user attribute is deleted successfully. If data is true, the user attribute is deleted. If the specified user does not exist, or the user attribute of the specified user does not exist, the deletion is still considered successful.

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.

_1

curl -X DELETE -H 'Authorization: Bearer {YourAppToken}' 'http://XXXX/XXXX/XXXX/metadata/user/XXXX'

_5

{

_5

"timestamp": 1616573382270,

_5

"duration": 10,

_5

"data": true

_5

}

For details, see HTTP Status Codes.