Skip to main content

Manage chat room attributes

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.

Common parameters

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

Request parameters

ParameterTypeDescriptionRequired
hostStringThe 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.Yes
org_nameStringThe unique identifier assigned to each company (organization) by the Agora Chat service. For how to get the org name, see Get the information of your project.Yes
app_nameStringThe unique identifier assigned to each app by the Agora Chat service. For how to get the app name, see Get the information of your project.Yes
usernameStringThe 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)
  • 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.
    Yes

    Response parameters

    ParameterTypeDescription
    actionStringThe request method.
    organizationStringThe unique identifier assigned to each company (organization) by the Agora Chat service. This is the same as org_name.
    applicationStringA unique internal ID assigned to each app by the Agora Chat service. You can safely ignore this parameter.
    applicationNameStringThe unique identifier assigned to each app by the Agora Chat service. This is the same as app_name.
    uriStringThe request URI.
    entities JSONThe response entity.
    dataJSONThe details of the response.
    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.

    Set custom attributes

    Adds new custom chat room 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.

    HTTP request


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

    Path parameter

    For the parameters and detailed descriptions, see Common parameters.

    Request header

    ParameterTypeDescriptionRequired
    AcceptStringapplication/jsonYes
    Content-TypeStringapplication/jsonYes
    AuthorizationStringThe 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

    ParameterTypeRequiredDescription
    metaDataJSONYesThe custom attributes that are stored as a collection of key-value pairs in the format Map<String,String>. 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,086 characters.
    The following character sets are supported:
    • 26 lowercase English letters (a-z)
    • 26 uppercase English letters (A-Z)
    • 10 numbers (0-9)
    • "_", "-", "."
    autoDeleteStringNoWhether 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

    Response body

    FieldTypeDescription
    data.successKeysArrayThe keys of the custom attributes that are successfully set.
    data.errorKeysObjectThe 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.

    Example

    Request example


    _8
    # Replaces <YourAppToken> with the app token generated from your token server.
    _8
    curl -X PUT -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken> ' -d '{
    _8
    "metaData": {
    _8
    "key1": "value1",
    _8
    "key2": "value2"
    _8
    },
    _8
    "autoDelete": "DELETE"
    _8
    }' 'http://XXXX/XXXX/XXXX/metadata/chatroom/662XXXX13/user/user1'

    Response example


    _7
    {
    _7
    "data":
    _7
    {
    _7
    "successKeys": ["key1"],
    _7
    "errorKeys": {"key2":"errorDesc"},
    _7
    }
    _7
    }

    Retrieve custom attributes

    Retrieves the specified custom attributes of a chat room.

    HTTP request


    _1
    POST https://{host}/{org_name}/{app_name}/metadata/chatroom/{chatroom_id}

    Path parameter

    For the parameters and detailed descriptions, see Common parameters.

    Request header

    ParameterTypeDescriptionRequired
    AcceptStringapplication/jsonYes
    Content-TypeStringapplication/jsonYes
    AuthorizationStringThe 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

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

    Response body

    FieldTypeDescription
    dataObjectThe key-value pairs of the retrieved custom attributes.

    For other fields and detailed descriptions, see Common parameters.

    Example

    Request example


    _4
    # Replaces <YourAppToken> with the app token generated from your token server.
    _4
    curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken> ' -d '{
    _4
    "keys": ["key1","key2"]
    _4
    }' 'http://XXXX/XXXX/XXXX/metadata/chatroom/662XXXX13'

    Response example


    _7
    {
    _7
    "data":
    _7
    {
    _7
    "key1": "value1",
    _7
    "key2": "value2"
    _7
    }
    _7
    }

    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.

    HTTP request


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

    Path parameter

    For the parameters and detailed descriptions, see Common parameters.

    Request header

    ParameterTypeDescriptionRequired
    AcceptStringapplication/jsonYes
    Content-TypeStringapplication/jsonYes
    AuthorizationStringThe 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

    ParameterTypeRequiredDescription
    keysArrayNoThe keys of the custom attributes to remove.

    HTTP response

    Response body

    FieldTypeDescription
    data.successKeysArrayThe keys of the custom attributes that are successfully removed.
    data.errorKeysObjectThe 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.

    Example

    Request example


    _4
    # Replaces <YourAppToken> with the app token generated from your token server.
    _4
    DELETE -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken> ' -d '{
    _4
    "keys": ["key1","key2"]
    _4
    }' 'http://XXXX/XXXX/XXXX/metadata/chatroom/662XXXX13/user/user1'

    Response example


    _7
    {
    _7
    "data":
    _7
    {
    _7
    "successKeys": ["key1"],
    _7
    "errorKeys": {"key2":"errorDesc"}
    _7
    }
    _7
    }

    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


    _1
    PUT https://{host}/{org_name}/{app_name}/metadata/chatroom/{chatroom_id}/user/{username}/forced

    Path parameter

    For the parameters and detailed descriptions, see Common parameters.

    Request header

    ParameterTypeDescriptionRequired
    AcceptStringapplication/jsonYes
    Content-TypeStringapplication/jsonYes
    AuthorizationStringThe 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

    ParameterTypeRequiredDescription
    metaDataJSONYesThe custom attributes that are stored as a collection of key-value pairs in the format Map<String,String>. 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,086 characters.
    The following character sets are supported:
    • 26 lowercase English letters (a-z)
    • 26 uppercase English letters (A-Z)
    • 10 numbers (0-9)
    • "_", "-", "."
    autoDeleteStringNoWhether 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

    Response body

    FieldTypeDescription
    data.successKeysArrayThe keys of the custom attributes that are successfully set.
    data.errorKeysObjectThe 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.

    Example

    Request example


    _8
    # Replaces <YourAppToken> with the app token generated from your token server.
    _8
    curl -X PUT -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken> ' -d '{
    _8
    "metaData": {
    _8
    "key1": "value1",
    _8
    "key2": "value2"
    _8
    },
    _8
    "autoDelete": "DELETE"
    _8
    }' 'http://XXXX/XXXX/XXXX/metadata/chatroom/662XXXX13/user/user1/forced'

    Response example


    _7
    {
    _7
    "data":
    _7
    {
    _7
    "successKeys": ["key1"],
    _7
    "errorKeys": {"key2":"errorDesc"}
    _7
    }
    _7
    }

    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


    _1
    DELETE https://{host}/{org_name}/{app_name}/metadata/chatroom/{chatroom_id}/user/{username}/forced

    Path parameter

    For the parameters and detailed descriptions, see Common parameters.

    Request header

    ParameterTypeDescriptionRequired
    AcceptStringapplication/jsonYes
    Content-TypeStringapplication/jsonYes
    AuthorizationStringThe 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

    ParameterTypeRequiredDescription
    keysArrayNoThe keys of the custom attributes to remove.

    HTTP response

    Response body

    FieldTypeDescription
    data.successKeysArrayThe keys of the custom attributes that are successfully removed.
    data.errorKeysObjectThe 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.

    Example

    Request example


    _4
    # Replaces <YourAppToken> with the app token generated from your token server.
    _4
    DELETE -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken> ' -d '{
    _4
    "keys": ["key1","key2"]
    _4
    }' 'http://XXXX/XXXX/XXXX/metadata/chatroom/662XXXX13/user/user1/forced'

    Response example


    _7
    {
    _7
    "data":
    _7
    {
    _7
    "successKeys": ["key1"],
    _7
    "errorKeys": {"key2":"errorDesc"}
    _7
    }
    _7
    }

    Status codes

    For details, see HTTP Status Codes.