User metadata

User metadata items allow you to store key-value pairs within a user instance. Use cases for the user metadata items could include a description of the user, which can each be fetched and displayed in a UI. You can search users by the user metadata.

  • API endpoints are relative to the allocated base URL for your app. In this section, the /users endpoint refers to https://{region_identifier}.sendbird.com/v3/users.

Note: If you want region_identifier for your app, sign in to the SendBird Dashboard, select the application, open the Overview, and see the App Credentials > API URL.

  • All values in URL must be urlencoded (for example, {user_id}, {key}).
Action HTTP Request Description
Create a user matadata POST /users/{user_id}/metadata Creates a user metadata item to store in the user.
View the user metadata GET /users/{user_id}/metadata or
GET /users/{user_id}/metadata/{key}
Returns user metadata item(s) that are stored in the user.
Update the user metadata PUT /users/{user_id}/metadata/{key} or
PUT /users/{user_id}/metadata
Updates user metadata items that are stored in the user.
Delete the user metadata DELETE /users/{user_id}/metadata/{key} or
DELETE /users/{user_id}/metadata
Deletes the user metadata items that are stored in the user.

Create a user metadata

Creates a user metadata item to store in the user.

POST https://{region identifier}.sendbird.com/v3/users/{user_id}/metadata
Property name Type Description
metadata nested object A JSON object that stores key-value pairs in. The key cannot contain a comma(,) and its length is limited to 128 bytes. The value must be a string, and its length is limited to 190 bytes. The maximum number of metadata items is 5.
Request body example
{
    "metadata": {
        "background": "blue",
        "text_size": "large",
        "description": "This is a chat to discuss the upcoming project."
    }
}

Returns the user metadata object.

Status: 200 OK
{
    "background": "blue",
    "text_size": "large",
    "description": "This is a chat to discuss the upcoming project."
}

View the user metadata

Returns the user metadata item(s) stored in the user.

// When getting multiple items
GET https://{region identifier}.sendbird.com/v3/users/{user_id}/metadata  

// When getting item by key
GET https://{region identifier}.sendbird.com/v3/users/{user_id}/metadata/{key_name}
Parameter name Type Description
keys string If not specified, all stored user metadata items are returned. To receive specific values, format the parameter as key1, key2, key3,..., where all keys must be urlencoded.
Request example
?keys=background,description

Returns the corresponding user metadata item.

Status: 200 OK
// When getting multiple items
{ 
    "background": "blue",
    "description": "This is a chat to discuss the upcoming project."
}

// When getting item by key
{
    "text_size": "large"
}

Update the user metadata

Updates user metadata items that are stored in the user.

// When updating multiple items
PUT https://{region identifier}.sendbird.com/v3/users/{user_id}/metadata

// When updating an item by key
PUT https://{region identifier}.sendbird.com/v3/users/{user_id}/metadata/{key_name}
Property name Type Description
metadata nested object A JSON object that stores key-value pairs in. The key cannot contain a comma(,) and its length is limited to 128 bytes. The value must be a string and its length is limited to 190 bytes.
upsert (optional) boolean If true, you can add a new key-value pair if the key is not already present in the items. If false, you cannot add a pair, but can modify the pair that matches the key you specify. (Default: false)
Request body example
// When updating multiple items
{
    "metadata": {
        "background": "red",
        "text_size": "small",
        "text_color": "purple"
    },
    "upsert": true
}

// When updating an item by key
{
    "value": "red"
}

Returns the updated user metadata item(s).

Status: 200 OK
// When updating multiple items
{
    "background": "red",
    "text_size": "small",
    "text_color": "purple"
}

// When updating an item by key
{
    "background": "red"
}

Delete the user metadata

Deletes the user metadata items that are stored in the user.

Note: Be cautious that this api can delete all of user's stored user metadata items.

// When deleting all items
DELETE https://{region identifier}.sendbird.com/v3/users/{user_id}/metadata  

// When deleting an item by key
DELETE https://{region identifier}.sendbird.com/v3/users/{user_id}/metadata/{key_name}
Status: 200 OK
{}