# User attributes management (/en/api-reference/api-ref/im/user-attributes-management)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

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](./limitations#call-limit-of-server-sides).

## Common parameters [#common-parameters]

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

### Request parameters [#request-parameters]

| 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](/en/realtime-media/im/get-started/enable#get-the-information-of-the-agora-chat-project).                                                                                                                                                                                                                                                                                                                | Yes      |
| `app_id`   | String | The unique identifier automatically assigned to each project by Agora                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | 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)
* 10 numbers (0-9)
* "\_", "-", "."<CalloutContainer type="info">
  <CalloutDescription>
    Do not use any of the 26 uppercase English letters (A-Z). Ensure that each `username` under the same App ID is unique. Do not set this parameter as a UUID, email address, phone number, or other sensitive information.
  </CalloutDescription>
</CalloutContainer> | Yes      |

### Response parameters [#response-parameters]

| Parameter         | Type   | Description                                                                                          |
| :---------------- | :----- | :--------------------------------------------------------------------------------------------------- |
| `action`          | String | The request method.                                                                                  |
| `organization`    | String | The unique identifier assigned to each company (organization) by the Chat service.                   |
| `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 .                                     |
| `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.           |

## Authorization [#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:

```html
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](/en/realtime-media/im/build/secure-access-and-authentication/authentication).

## Setting user attributes [#setting-user-attributes]

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.

### HTTP request [#http-request]

```html
PUT https://{host}/app-id/{app_id}/metadata/user/{username}
```

#### Path parameter [#path-parameter]

For the parameters and detailed descriptions, see [Common parameters](#param).

#### Request header [#request-header]

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

#### Request body [#request-body]

The request body is in the format of JSON String. The request body contains the following fields:

| Field   | Type   | Description     | Required |
| :------ | :----- | :-------------- | :------- |
| `Key`   | String | Attribute name  | Yes      |
| `Value` | String | Attribute value | Yes      |

Keys listed in the following table are used by default when user attributes are set on the client side, including the nickname, avatar URL, contact information, email address, gender, signature, birthday and extension fields. When you call this RESTful API to set these user attributes, 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; `0`: Unknown.             |
| `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.                                              |

### HTTP response [#http-response]

#### Response body [#response-body]

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](#param).

If the returned HTTP status code is not `200`, the request fails. You can refer to [Status codes](./http-status-codes) for possible reasons.

### Example [#example]

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

#### Request example [#request-example]

```bash
# Replace {YourAppToken} with the app token generated in your server.
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/app-id/XXXX/metadata/user/XXXX'
```

#### Response example [#response-example]

```json
{
    "timestamp": 1620445147011,
    "data": {
        "ext": "ext",
        "nickname": "nickname",
        "avatarurl": "http://XXXX.png"
    },
    "duration": 166
}
```

## Retrieving user attributes [#retrieving-user-attributes]

Retrieves the user attributes of the specified user.

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

### HTTP request [#http-request-1]

```html
GET https://{host}/app-id/{app_id}/metadata/user/{username}
```

#### Path parameter [#path-parameter-1]

For the parameters and detailed descriptions, see [Common parameters](#param).

#### Request header [#request-header-1]

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

### HTTP response [#http-response-1]

#### Response body [#response-body-1]

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](#param).

If the returned HTTP status code is not `200`, the request fails. You can refer to [Status codes](./http-status-codes) for possible reasons.

### Example [#example-1]

#### Request example [#request-example-1]

```bash
# Replace {YourAppToken} with the app token generated in your server.
curl -X GET -H 'Authorization: Bearer {YourAppToken}' -H 'Content-Type:  application/json''http://XXXX/app-id/XXXX/metadata/user/XXXX'
```

#### Response example [#response-example-1]

```json
{
    "timestamp": 1620445147011,
    "data": {
        "ext": "ext",
        "nickname": "nickname",
        "avatar": "http://XXXX.png"
    },
    "duration": 166
}
```

## Retrieving the user attributes of multiple users [#retrieving-the-user-attributes-of-multiple-users]

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.

### HTTP request [#http-request-2]

```html
POST https://{host}/app-id/{app_id}/metadata/user/get
```

#### Path parameter [#path-parameter-2]

For the parameters and detailed descriptions, see [Common parameters](#param).

#### Request header [#request-header-2]

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

#### Request body [#request-body-1]

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      |

### HTTP response [#http-response-2]

#### Response body [#response-body-2]

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](#param).

If the returned HTTP status code is not `200`, the request fails. You can refer to [Status codes](./http-status-codes) for possible reasons.

### Example [#example-2]

#### Request example [#request-example-2]

```bash
# Replace {YourAppToken} with the app token generated in your server.
curl -X POST -H 'Authorization: Bearer {YourAppToken}' -H 'Content-Type:  application/json' -d '{
  "properties": [
    "avatar",
    "ext",
    "nickname"
  ],
  "targets": [
    "user1",
    "user2",
    "user3"
  ]
}' 'http://XXXX/app-id/XXXX/metadata/user/get'
```

#### Response example [#response-example-2]

```json
{
    "timestamp": 1620448826647,
    "data": {
        "user1": {
            "ext": "ext",
            "nickname": "nickname",
            "avatar": "http://XXXX.png"
        },
        "user2": {
            "ext": "ext",
            "nickname": "nickname",
            "avatar": "http://XXXX.png"
        },
        "user3": {
            "ext": "ext",
            "nickname": "nickname",
            "avatar": "http://XXXX.png"
        }
    },
    "duration": 3
}
```

## Retrieving the total size of user attributes in the app [#retrieving-the-total-size-of-user-attributes-in-the-app]

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.

### HTTP request [#http-request-3]

```html
GET https://{host}/app-id/{app_id}/metadata/user/capacity
```

#### Path parameter [#path-parameter-3]

For the parameters and detailed descriptions, see [Common parameters](#param).

#### Request header [#request-header-3]

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

### HTTP response [#http-response-3]

#### Response body [#response-body-3]

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](#param).

If the returned HTTP status code is not `200`, the request fails. You can refer to [Status codes](./http-status-codes) for possible reasons.

### Example [#example-3]

#### Request example [#request-example-3]

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

#### Response example [#response-example-3]

```json
{
    "timestamp": 1620447051368,
    "data": 1673,
    "duration": 55
}
```

## Deleting user attributes [#deleting-user-attributes]

Deletes all the user attributes of the specified user.

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

### HTTP request [#http-request-4]

```html
DELETE https://{host}/app-id/{app_id}/metadata/user/{username}
```

#### Path parameter [#path-parameter-4]

For the parameters and detailed descriptions, see [Common parameters](#param).

#### Request header [#request-header-4]

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

### HTTP response [#http-response-4]

#### Response body [#response-body-4]

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](#param).

If the returned HTTP status code is not `200`, the request fails. You can refer to [Status codes](./http-status-codes) for possible reasons.

### Example [#example-4]

#### Request example [#request-example-4]

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

#### Response example [#response-example-4]

```json
{
    "timestamp": 1616573382270,
    "duration": 10,
    "data": true
}
```

## Status codes [#status-codes]

For details, see [HTTP Status Codes](./http-status-codes).