User Metadata | AgoraChat Documentation Beta

Edit me

Setting user metadata

Set the user metadata for the specified user. Only the user himself or the app administrator has permission to do the settings.

HTTP Request

PUT	/{org_name}/{app_name}/metadata/user/{username}

Request Headers

Parameter	Description
Content-Type	application/x-www-form-urlencoded
Authorization	Bearer ${token}

Request Body

The content of a user attribute is one or more plain text key-value pairs. By default the total length of properties for a single user must not exceed 2KB. By default the total length of all properties for all users under one app must not exceed 10GB.

The keys used in the request example are avater, ext, nickname. However, of course, this is not fixed just an example, it is entirely up to you to decide what the key values are.

The following fields are used for user metadata on the SDK side

Field	Type	Remark
nickname	String	Nickname
avatarurl	String	Avatar
phone	String	Contact details
mail	String	Email
gender	Number	Gender
sign	String	Signature
birth	String	Birthday
ext	String	Custom Fields

Response Body

View the information contained in the data field in the return value

Example request

curl -X PUT -H 'Content-Type: application/x-www-form-urlencoded' -H 'Authorization: Bearer WMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw12' -d 'avatar=http://www.chat.com/avatar.png&ext=ext&nickname=nickname' 'http://a1.easecdn.com/chat-demo/testapp/metadata/user/user1'

Examples of possible results returned

Returns a value of 200, indicating success in setting user metadata

{
    "timestamp":1620445147011,
    "data":{
        "ext":"ext",
        "nickname":"nickname",
        "avatar":"http://www.chat.com/avatar.png"
    },
    "duration":166
}

Return a value of 401, only the user himself or the app administrator has the right to modify his metadata. A 401 is also returned when an ordinary user tries to modify the metadata of a non-existent user, because the ordinary user has no right to know whether a username exists or not.

{
    "desc": "unauthorized",
    "duration": 10,
    "timestamp": 1616573382270
}

Returns value 403, the user attribute value you are trying to set exceeds the length limit. The limit may be a limit on the total length of metadata under a single user, or it may be a limit on the total length of all user metadata under an app.

{
    "desc": "user metadata length exceed the limit",
    "duration": 10,
    "timestamp": 1616573382270
}

Returns a value of 404, indicating that the user does not exist.

{
    "timestamp":1620445340631,
    "desc":"Not Found",
    "duration":0
}

Returns 409, the user you are trying to modify has already been modified by “someone else”. Since we use optimistic locks on user metadata to handle concurrent modifications. When multiple threads are making changes to the same user’s metadata at the same time， only one of the threads will succeed and return 200, the others will fail and return 409.

{
   "desc": "update userMetadata failed, concurrent updates not allowed",
   "duration": 10,
   "timestamp": 1616573382270
}

Returns a value of 500, which is usually a mysql error. If the problem keep existing, please contact our technical support team.

{
   "desc": "org.hibernate.exception.JDBCConnectionException: Unable to acquire JDBC Connection",
   "duration": 10,
   "timestamp": 1616573382270
}

If the return result is 429, 503 or other 5xx ,it may mean that the interface has been restricted, please pause slightly and retry.For more information, see Interface current limit description

[Online testing using the Platform API].

Get user metadata

Gets all user attribute key-value pairs for the specified user. Returns null data if the specified user does not exist, or if the specified user’s metadata do not exist {}.

HTTP Request

GET	/{org_name}/{app_name}/metadata/user/{username}

You need to fill in {username} corresponding to the request, and you need to get the Chat username of the user property.

Request Headers

Parameter	Description
Content-Type	application/json
Authorization	Bearer ${token}

Response Body

View the information contained in the data field in the return value

Example request

curl -X GET -H 'Content-Type: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easecdn.com/chat-demo/testapp/metadata/user/user1'

Examples of possible results returned

Returns a value of 200, indicating success in obtaining user metadata

{
    "timestamp":1620446048161,
    "data":{
        "ext":"ext",
        "nickname":"nickname",
        "avatar":"http://www.chat.com/avatar.png"
    },
    "duration":2
}

Returns a value of 404, indicating that the user does not exist

{
    "timestamp":1620446033278,
    "data":{

    },
    "duration":9
}

Returns a value of 500, which is usually a mysql error. If the problem keep existing, please contact our technical support team.

{
    "desc": "org.hibernate.exception.JDBCConnectionException: Unable to acquire JDBC Connection",
    "duration": 10,
    "timestamp": 1616573382270
}

If the return result is 429, 503 or other 5xx ,It may mean that the interface has been restricted, please pause slightly and retry.For more information, see Interface current limit description

Online testing using the Platform API

Get Users’ Metadata

Query user metadata based on the specified list of usernames and list of metadata. Returns empty data if the specified user/attribute does not exist {}. Specify up to 100 users at a time.

HTTP Request

POST	/{org_name}/{app_name}/metadata/user/get

Request Headers

Parameter	Description
Content-Type	application/json
Authorization	Bearer ${token}

Request Body

Parameter	Description
targets	List of usernames, up to 100 usernames
properties	A list of property names, the query will only return the properties contained in this list, properties that are not in this list will be ignored

Response Body

View the information contained in the data field in the return value

Example request

curl -X POST -H 'Content-Type:  application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' -d '{
  "properties": [
    "avatar",
    "ext",
    "nickname"
  ],
  "targets": [
    "user1",
    "user2",
    "user3"
  ]
}' 'http://a1.easecdn.com/chat-demo/testapp/metadata/user/get'

Examples of possible results returned

Returns a value of 200, which means that getting the user’s metadata was successful

{
    "timestamp":1620448826647,
    "data":{
        "user1":{
            "ext":"ext",
            "nickname":"nickname",
            "avatar":"http://www.chat.com/avatar.png"
        },
        "user2":{
            "ext":"ext",
            "nickname":"nickname",
            "avatar":"http://www.chat.com/avatar.png"
        },
        "user3":{
            "ext":"ext",
            "nickname":"nickname",
            "avatar":"http://www.chat.com/avatar.png"
        }
    },
    "duration":3
}

Returns value 403, the number of specified usernames exceeds 100

{
   "desc": "exceed allowed batch size 100",
   "duration": 10,
   "timestamp": 1616573382270
}

Returns a value of 500, which is usually a mysql error. If the problem keep existing, please contact our technical support team.

{
    "desc": "org.hibernate.exception.JDBCConnectionException: Unable to acquire JDBC Connection",
    "duration": 10,
    "timestamp": 1616573382270
}

If the return result is 429, 503 or other 5xx ,It may mean that the interface has been restricted, please pause slightly and retry.For more information, see Interface current limit description

Online testing using the Platform API

Get the total size of user metadata

Gets the total user attribute size, in Bytes, for all users under this app.

HTTP Request

GET	/{org_name}/{app_name}/metadata/user/capacity

Request Headers

Parameter	Description
Content-Type	application/json
Authorization	Bearer ${token}

Response Body

View the information contained in the data field in the return value

Example request

curl -X GET -H 'Content-Type: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easecdn.com/chat-demo/testapp/metadata/user/capacity'

Examples of possible results returned

Returns a value of 200, indicating success in obtaining the total size of the user’s metadata

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

Return value 401, only app admin has permission.

{
   "desc": "unauthorized",
   "duration": 10,
   "timestamp": 1616573382270
}

Returns a value of 500, which is usually a mysql error. If the problem keep existing, please contact our technical support team.

{
    "desc": "org.hibernate.exception.JDBCConnectionException: Unable to acquire JDBC Connection",
    "duration": 10,
    "timestamp": 1616573382270
}

If the return result is 429, 503 or other 5xx ,It may mean that the interface has been restricted, please pause slightly and retry.For more information, see Interface current limit description

Online testing using the Platform API

Delete User Metadata

Deletes all user metadata for the specified user. If the specified user does not exist, or if its user metadata do not exist (perhaps they have already been deleted), the deletion is also considered successful.

HTTP Request

DELETE	/{org_name}/{app_name}/metadata/user/{username}

Request Headers

Parameter	Description
Content-Type	application/json
Authorization	Bearer ${token}

Response Body

See the information contained in the data field in the return value, true means the deletion was successful

Example request

curl -X DELETE -H 'Content-Type: application/json' -H 'Authorization: Bearer YWMte3bGuOukEeiTkNP4grL7iwAAAAAAAAAAAAAAAAAAAAGL4CTw6XgR6LaXXVmNX4QCAgMAAAFnKdc-ZgBPGgBFTrLhhyK8woMEI005emtrLJFJV6aoxsZSioSIZkr5kw' 'http://a1.easecdn.com/chat-demo/testapp/metadata/user/user1'

Examples of possible results returned

A return value of 200 and a data of true means that the deletion of the user attribute was successful, note that the deletion of a non-existent user is also considered successful.

{
    "timestamp": 1620447526237,
    "data": true,
    "duration": 160
}

Returns value 401, only the user himself or the app administrator has the right to delete his user metadata.

{
   "desc": "unauthorized",
   "duration": 10,
   "timestamp": 1616573382270
}

Returns a value of 500, which is usually a mysql error. If the problem keep existing, please contact our technical support team.

{
    "desc": "org.hibernate.exception.JDBCConnectionException: Unable to acquire JDBC Connection",
    "duration": 10,
    "timestamp": 1616573382270
}

If the return result is 429, 503 or other 5xx ,It may mean that the interface has been restricted, please pause slightly and retry.For more information, see Interface current limit description

Online testing using the Platform API