Skip to main content

You are viewing Agora Docs forBetaproducts and features. Switch to Docs

  • Core Products
  • Add-Ons
  • Extensions Marketplace
Android
iOS
Web
Windows
Unity
Flutter
React Native

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,096 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​


    _10
    {
    _10
    "uri":"https://XXXX/XXXX/XXXX/metadata/chatroom",
    _10
    "timestamp":1716887320215,
    _10
    "action":"put",
    _10
    "data":
    _10
    {
    _10
    "successKeys": ["key1"],
    _10
    "errorKeys": {"key2":"errorDesc"},
    _10
    }
    _10
    }

    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​


    _10
    {
    _10
    "uri": "https://XXXX/XXXX/XXXX/metadata/chatroom",
    _10
    "timestamp": 1716891388636,
    _10
    "action": "post",
    _10
    "data":
    _10
    {
    _10
    "key1": "value1",
    _10
    "key2": "value2"
    _10
    }
    _10
    }

    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.

    You can remove a maximum of 10 custom attributes at each call of this API.

    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. You can pass in at most 10 keys each time.

    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​


    _11
    {
    _11
    "uri":"https://XXXX/XXXX/XXXX/metadata/chatroom",
    _11
    "status":"ok",
    _11
    "timestamp":1716887320215,
    _11
    "action":"delete",
    _11
    "data":
    _11
    {
    _11
    "successKeys": ["key1"],
    _11
    "errorKeys": {"key2":"errorDesc"}
    _11
    }
    _11
    }

    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,096 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. You can pass in at most 10 keys.

    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
    curl -X DELETE -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' -d '{
    _4
    "keys": ["key1","key2"]
    _4
    }' 'https://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.

    vundefined