Platform API
User Metadata

User metadata

With user metadata, you can store key-value of additional information to a user. Use cases for the metadata are such as phone number, email or a long description of the user, which can each be fetched and rendered into the UI.

Actions

  • API endpoints are relative to the base URL allocated to your application. In this page, the /users endpoint refers to https://api-{application_id}.sendbird.com/v3/users.

Note: If you want to know the ID and base URL of your application, sign in to your dashboard, select the application, open the Overview, and then check the App credentials > App ID, API request URL.

  • It's recommended that the parameter values in API URLs are urlencoded, such as {user_id}.
ActionHTTP Request

View a metadata

GET /users/{user_id}/metadata or .../metadata/{key}
Retrieves a user metadata's one or more items that are stored in the user.

Create a matadata

POST /users/{user_id}/metadata
Creates a user metadata's items to store in the user.

Update a metadata

PUT /users/{user_id}/metadata or .../metadata/{key}
Updates existing items of a user metadata by their keys, or adds new items to the metadata.

Delete a metadata

DELETE /users/{user_id}/metadata or .../metadata/{key}
Deletes a user metadata's one or all items that are stored in the user.


View a user metadata

Retrieves a user metadata's one or more items that are stored in a user.

HTTP request

Light Color Skin
Copy
// When retrieving all items of a user metadata
GET https://api-{application_id}.sendbird.com/v3/users/{user_id}/metadata 

// When retrieving a specific item of a user metadata by its key
GET https://api-{application_id}.sendbird.com/v3/users/{user_id}/metadata/{key}

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

user_id

string

Specifies the ID of the user to retrieve the metadata in.

OptionalTypeDescription

key

string

Specifies the key of metadata item to retrieve the values of. If not specified, all items of the metadata are returned. If specified, the item which matches the parameter value is returned. Urlencoding a key is recommended.

keys

array

In a query string, specifies an array of one or more keys of metadata items to retrieve the values of. If not specified, all items of the metadata are returned. If specified, the items which match the parameter values are returned. Urlencoding each key is recommended (for example, ?keys=urlencoded_key_1, urlencoded_key_2).

Query string example
Light Color Skin
Copy
../metadata?keys=location,marriage

Response

If successful, this action returns a stored metadata in the response body

Status: 200 OK
Light Color Skin
Copy
{
    "location": "Washington",
    "marriage": "N"
}

Create a user metadata

Creates a user metadata's items to store in a user.

HTTP request

Light Color Skin
Copy
POST https://api-{application_id}.sendbird.com/v3/users/{user_id}/metadata

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

user_id

string

Specifies the ID of the user to store the metadata in.

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties
RequiredTypeDescription

metadata

nested object

Specifies a JSON object that stores key-value items. The key must not have a comma (,) and its length is limited to 128 bytes. The value must be a string and its length is limited to 190 bytes. This property can have up to 5 items.

Request body example
Light Color Skin
Copy
{
    "metadata": {
        "location": "Washington",
        "marriage": "N",
        "hasSomeone": "Y"
    }
}

Response

If successful, this action returns a stored metadata in the response body like the following.

Status: 200 OK
Light Color Skin
Copy
{
    "location": "Washington",
    "marriage": "N",
    "hasSomeone": "Y"
}

Update a user metadata

Updates existing items of a user metadata by their keys, or adds new items to the metadata.

HTTP request

Light Color Skin
Copy
// When updating existing items of a user metadata by their keys or adding new items to the metadata  
PUT https://api-{application_id}.sendbird.com/v3/users/{user_id}/metadata

// When updating a specific item of a user metadata by its key 
PUT https://api-{application_id}.sendbird.com/v3/users/{user_id}/metadata/{key}

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

user_id

string

Specifies the ID of the user to update the metadata in.

OptionalTypeDescription

key

string

Specifies the key of metadata item to update the values of. If not specified, the items in the metadata property below are updated. If specified, the item which matches the parameter value is updated only. Urlencoding a key is recommended.

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties
RequiredTypeDescription

metadata

nested object

Specifies a JSON object that stores key-value items. The key must not have a comma (,) and its length is limited to 128 bytes. The value must be a string and its length is limited to 190 bytes.

OptionalTypeDescription

upsert

boolean

Determines whether to add new items in addition to updating existing items. If true, new key-value items in the metadata property are added when there are no items with the keys. The existing items are updated with new values when there are already items with the keys. If false, only the items of which keys match the ones you specify are updated. (Default: false)

Request body example
Light Color Skin
Copy
// When updating existing items by their keys and adding new items to the metadata  
{
    "metadata": {
        "location": "Philadelphia",     // Updated  
        "favorites": "movie,music"      // Added 
    },
    "upsert": true
}

// When updating a specific item by its key
{
    "value": "Philadelphia"
}

Response

If successful, this action returns the updated and added item(s) in the metadata in the response body.


Delete a user metadata

Deletes a user metadata's one or all items that are stored in a user.

HTTP request

Light Color Skin
Copy
// When deleting all items of a user metadata
DELETE https://api-{application_id}.sendbird.com/v3/users/{user_id}/metadata  

// When deleting a specific item of a user metadata by its key
DELETE https://api-{application_id}.sendbird.com/v3/users/{user_id}/metadata/{key} 

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

user_id

string

Specifies the ID of the user who has the metadata to delete.

OptionalTypeDescription

key

string

Specifies the key of metadata item to delete. If not specified, all items of the metadata are deleted. If specified, the item which matches the parameter value is deleted only. Urlencoding a key is recommended.

Response

If successful, this action returns an empty response body.