# Manage chat room attributes (/en/api-reference/api-ref/im/chatroom-management/manage-chatroom-attributes)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
This page shows how to manage custom attributes by calling Agora Chat RESTful APIs, including adding, removing, modifying, and retrieving attributes that are stored as key-value maps.
Before calling the following methods, ensure that you understand the call frequency limit of Agora Chat RESTful API calls described in [Limitations](../limitations#call-limit-of-server-sides).
## Common parameters [#common-parameters]
The following table lists common request and response parameters of the Agora Chat RESTful APIs:
### Request parameters [#request-parameters]
| Parameter | Type | Description | Required |
| :--------- | :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `host` | String | The domain name assigned by the Agora 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 username 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)
* "\_", "-", "."
Do not use any of the 26 uppercase English letters (A-Z). Ensure that each username under the same App ID is unique.
| 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 Agora Chat service. |
| `application` | String | A unique internal ID assigned to each app by the Agora Chat service. You can safely ignore this parameter. |
| `applicationName` | String | The unique identifier assigned to each app by the Agora Chat service. |
| `uri` | String | The request URI. |
| `entities ` | JSON | The response entity. |
| `data` | JSON | The details of the response. |
| `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).
## Set custom attributes [#set-custom-attributes]
Adds new custom attributes or modifies existing ones set by the current user.
This method is only used to modify the existing key-value pairs set by the current user. To perform the overwrite operation, see [Forcibly set custom attributes](overwrite).
### HTTP request [#http-request]
```html
PUT https://{host}/app-id/{app_id}/metadata/chatroom/{chatroom_id}/user/{username}
```
#### Path parameter [#path-parameter]
For the parameters and detailed descriptions, see [Common parameters](#param).
#### Request header [#request-header]
| Parameter | Type | Description | Required |
| :-------------- | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `Accept` | String | `application/json` | Yes |
| `Content-Type` | String | `application/json` | Yes |
| `Authorization` | String | The authentication token of the user or administrator, in the format of `Bearer ${token}`, where `Bearer` is a fixed character, followed by an English space, and then the obtained token value. | Yes |
#### Request body [#request-body]
| Parameter | Type | Required | Description |
| :----------- | :----- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `metaData` | JSON | Yes | The custom attributes that are stored as a collection of key-value pairs in the format `Map`. Keys in a map are unique attribute names that map to the corresponding attribute values. Note the following limitations: Each chat room can have a maximum of 100 custom attributes.The size of all custom attributes in an app can be a maximum of 10 GB.Each map can contain a maximum of 10 key-value pairs.Each key can contain a maximum of 128 characters.Each value can contain a maximum of 4,096 characters. The following character sets are supported:26 lowercase English letters (a-z)26 uppercase English letters (A-Z)10 numbers (0-9)"\_", "-", "." |
| `autoDelete` | String | No | Whether to automatically delete the custom attributes set by a chat room member when this member leaves the chat room:(Default) `DELETE`: Delete the custom attributes. `NO_DELETE`: Do not delete the custom attributes. |
### HTTP response [#http-response]
#### Response body [#response-body]
| Field | Type | Description |
| :----------------- | :----- | :------------------------------------------------------------------------------------------------------ |
| `data.successKeys` | Array | The keys of the custom attributes that are successfully set. |
| `data.errorKeys` | Object | The keys of the custom attributes that fail to be set paired with the corresponding error descriptions. |
For other fields and detailed descriptions, see [Common parameters](#param).
### Example [#example]
#### Request example [#request-example]
```bash
# Replaces with the app token generated from your token server.
curl -X PUT -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer ' -d '{
"metaData": {
"key1": "value1",
"key2": "value2"
},
"autoDelete": "DELETE"
}' 'http://XXXX/app-id/XXXX/metadata/chatroom/662XXXX13/user/user1'
```
#### Response example [#response-example]
```json
{
"uri":"https://XXXX/app-id/XXXX/metadata/chatroom",
"timestamp":1716887320215,
"action":"put",
"data":
{
"successKeys": ["key1"],
"errorKeys": {"key2":"errorDesc"},
}
}
```
## Retrieve custom attributes [#retrieve-custom-attributes]
Retrieves the specified custom attributes of a chat room.
### HTTP request [#http-request-1]
```html
POST https://{host}/app-id/{app_id}/metadata/chatroom/{chatroom_id}
```
#### Path parameter [#path-parameter-1]
For the parameters and detailed descriptions, see [Common parameters](#param).
#### Request header [#request-header-1]
| Parameter | Type | Description | Required |
| :-------------- | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `Accept` | String | `application/json` | Yes |
| `Content-Type` | String | `application/json` | Yes |
| `Authorization` | String | The authentication token of the user or administrator, in the format of `Bearer ${token}`, where `Bearer` is a fixed character, followed by an English space, and then the obtained token value. | Yes |
#### Request body [#request-body-1]
| Parameter | Type | Required | Description |
| :-------- | :---- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `keys` | Array | No | The keys of the custom attributes to retrieve. If you pass an empty array to this parameter, all custom attributes of the specified chat room are returned. |
### HTTP response [#http-response-1]
#### Response body [#response-body-1]
| Field | Type | Description |
| :----- | :----- | :------------------------------------------------------ |
| `data` | Object | The key-value pairs of the retrieved custom attributes. |
For other fields and detailed descriptions, see [Common parameters](#param).
### Example [#example-1]
#### Request example [#request-example-1]
```bash
# Replaces with the app token generated from your token server.
curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer ' -d '{
"keys": ["key1","key2"]
}' 'http://XXXX/app-id/XXXX/metadata/chatroom/662XXXX13'
```
#### Response example [#response-example-1]
```json
{
"uri": "https://XXXX/app-id/XXXX/metadata/chatroom",
"timestamp": 1716891388636,
"action": "post",
"data":
{
"key1": "value1",
"key2": "value2"
}
}
```
## Remove custom attributes [#remove-custom-attributes]
Removes custom attributes set by the current user.
This method is only used to remove the key-value pairs set by the current user. To remove the key-value pairs set by others, see [Forcibly remove custom attributes](#force).
You can remove a maximum of 10 custom attributes at each call of this API.
### HTTP request [#http-request-2]
```html
DELETE https://{host}/app-id/{app_id}/metadata/chatroom/{chatroom_id}/user/{username}
```
#### Path parameter [#path-parameter-2]
For the parameters and detailed descriptions, see [Common parameters](#param).
#### Request header [#request-header-2]
| Parameter | Type | Description | Required |
| :-------------- | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `Accept` | String | `application/json` | Yes |
| `Content-Type` | String | `application/json` | Yes |
| `Authorization` | String | The authentication token of the user or administrator, in the format of `Bearer ${token}`, where `Bearer` is a fixed character, followed by an English space, and then the obtained token value. | Yes |
#### Request body [#request-body-2]
| Parameter | Type | Required | Description |
| :-------- | :---- | :------- | :-------------------------------------------------------------------------------------- |
| `keys` | Array | No | The keys of the custom attributes to remove. You can pass in at most 10 keys each time. |
### HTTP response [#http-response-2]
#### Response body [#response-body-2]
| Field | Type | Description |
| :----------------- | :----- | :---------------------------------------------------------------------------------------------------------- |
| `data.successKeys` | Array | The keys of the custom attributes that are successfully removed. |
| `data.errorKeys` | Object | The keys of the custom attributes that fail to be removed paired with the corresponding error descriptions. |
For other fields and detailed descriptions, see [Common parameters](#param).
### Example [#example-2]
#### Request example [#request-example-2]
```bash
# Replaces with the app token generated from your token server.
DELETE -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer ' -d '{
"keys": ["key1","key2"]
}' 'http://XXXX/app-id/XXXX/metadata/chatroom/662XXXX13/user/user1'
```
#### Response example [#response-example-2]
```json
{
"uri":"https://XXXX/app-id/XXXX/metadata/chatroom",
"status":"ok",
"timestamp":1716887320215,
"action":"delete",
"data":
{
"successKeys": ["key1"],
"errorKeys": {"key2":"errorDesc"}
}
}
```
## Forcibly set custom attributes [#forcibly-set-custom-attributes]
In addition to adding new custom attributes or modifying the existing ones set by the current user, this method can also be used to overwrite the custom attributes set by others.
### HTTP request [#http-request-3]
```html
PUT https://{host}/app-id/{app_id}/metadata/chatroom/{chatroom_id}/user/{username}/forced
```
#### Path parameter [#path-parameter-3]
For the parameters and detailed descriptions, see [Common parameters](#param).
#### Request header [#request-header-3]
| Parameter | Type | Description | Required |
| :-------------- | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `Accept` | String | `application/json` | Yes |
| `Content-Type` | String | `application/json` | Yes |
| `Authorization` | String | The authentication token of the user or administrator, in the format of `Bearer ${token}`, where `Bearer` is a fixed character, followed by an English space, and then the obtained token value. | Yes |
#### Request body [#request-body-3]
| Parameter | Type | Required | Description |
| :----------- | :----- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `metaData` | JSON | Yes | The custom attributes that are stored as a collection of key-value pairs in the format `Map`. Keys in a map are unique attribute names that map to the corresponding attribute values. Note the following limitations: Each chat room can have a maximum of 100 custom attributes.The size of all custom attributes in an app can be a maximum of 10 GB.Each map can contain a maximum of 10 key-value pairs.Each key can contain a maximum of 128 characters.Each value can contain a maximum of 4,096 characters. The following character sets are supported:26 lowercase English letters (a-z)26 uppercase English letters (A-Z)10 numbers (0-9)"\_", "-", "." |
| `autoDelete` | String | No | Whether to automatically delete the custom attributes set by a chat room member when this member leaves the chat room:(Default) `DELETE`: Delete the custom attributes. `NO_DELETE`: Do not delete the custom attributes. |
### HTTP response [#http-response-3]
#### Response body [#response-body-3]
| Field | Type | Description |
| :----------------- | :----- | :------------------------------------------------------------------------------------------------------ |
| `data.successKeys` | Array | The keys of the custom attributes that are successfully set. |
| `data.errorKeys` | Object | The keys of the custom attributes that fail to be set paired with the corresponding error descriptions. |
For other fields and detailed descriptions, see [Common parameters](#param).
### Example [#example-3]
#### Request example [#request-example-3]
```bash
# Replaces with the app token generated from your token server.
curl -X PUT -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer ' -d '{
"metaData": {
"key1": "value1",
"key2": "value2"
},
"autoDelete": "DELETE"
}' 'http://XXXX/app-id/XXXX/metadata/chatroom/662XXXX13/user/user1/forced'
```
#### Response example [#response-example-3]
```json
{
"data":
{
"successKeys": ["key1"],
"errorKeys": {"key2":"errorDesc"}
}
}
```
## Forcibly remove custom attributes [#forcibly-remove-custom-attributes]
In addition to removing the custom attributes set by the current user, this method can also be used to remove custom attributes set by others.
### HTTP request [#http-request-4]
```html
DELETE https://{host}/app-id/{app_id}/metadata/chatroom/{chatroom_id}/user/{username}/forced
```
#### Path parameter [#path-parameter-4]
For the parameters and detailed descriptions, see [Common parameters](#param).
#### Request header [#request-header-4]
| Parameter | Type | Description | Required |
| :-------------- | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `Accept` | String | `application/json` | Yes |
| `Content-Type` | String | `application/json` | Yes |
| `Authorization` | String | The authentication token of the user or administrator, in the format of `Bearer ${token}`, where `Bearer` is a fixed character, followed by an English space, and then the obtained token value. | Yes |
#### Request body [#request-body-4]
| Parameter | Type | Required | Description |
| :-------- | :---- | :------- | :---------------------------------------------------------------------------- |
| `keys` | Array | No | The keys of the custom attributes to remove. You can pass in at most 10 keys. |
### HTTP response [#http-response-4]
#### Response body [#response-body-4]
| Field | Type | Description |
| :----------------- | :----- | :---------------------------------------------------------------------------------------------------------- |
| `data.successKeys` | Array | The keys of the custom attributes that are successfully removed. |
| `data.errorKeys` | Object | The keys of the custom attributes that fail to be removed paired with the corresponding error descriptions. |
For other fields and detailed descriptions, see [Common parameters](#param).
### Example [#example-4]
#### Request example [#request-example-4]
```bash
# Replaces with the app token generated from your token server.
curl -X DELETE -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer ' -d '{
"keys": ["key1","key2"]
}' 'https://XXXX/app-id/XXXX/metadata/chatroom/662XXXX13/user/user1/forced'
```
#### Response example [#response-example-4]
```json
{
"data":
{
"successKeys": ["key1"],
"errorKeys": {"key2":"errorDesc"}
}
}
```
## Status codes [#status-codes]
For details, see [HTTP Status Codes](../http-status-codes).