Home
/
Chat
/
Platform API

User & channel metadata

With metadata and metacounter which consist of key-value items, you can store additional information to users and channels. This page explains how to manage user metadata, channel metadata, and channel metacounter.

Note : A channel metacounter is primarily used to track and update discrete indicators in a channel. Use channel metacounter instead of channel metadata when you need an integer with atomic increasing and decreasing operations.


data vs. metadata vs. sorted_metaarray

Users, channels, and messages can contain extra data within themselves using the following properties.

datametadatasorted_metaarray

Belongs to

message, channel

channel, user

message

Type

string

nested object

nested object

Value

A long text of any types of characters.

A collection of key-value pairs.

A collection of key-value pairs. A unique key can have an array of values.

* The values of a key are sorted in the chronological order of when they were added.

Maximum length

4 GB

- key: 128 bytes
- value: 190 bytes

- key: 80 bytes
- value: 128 bytes

Application

A container for long, customized data. Unlike metadata and sorted_metaarray, this property can't serve as a filter.

Suitable for classification and filtering.

Suitable for classification and filtering.

The following code shows how data, metadata, and sorted_metaarray property can be used for a user, channel, or message object.

channel and user resource
message and user resource
Light Color Skin
Copy
{
    "channels": [
        {
            "is_distinct": true,
            "is_public": false,
            "is_super": false,
            "is_ephemeral": false,
            "name": "On the upcoming AWS event",
            "channel_url": "sendbird_group_channel_25108471_a1bc35f5f0d237207bc1rd343562c878fc2fd426",
            "cover_url": "https://sendbird.com/main/img/cover/cover_43.jpg",
            "data": "{u'background_color': u'yellow', u'description': u'preparing presentation'}", # "data" contains a long string of extra data added to the channel.
            "member_count": 3,
            "members": [
                {
                    "user_id": "Jay",
                    "nickname": "Rooster",
                    "profile_url": "https://sendbird.com/main/img/profiles/profile_13_512px.png",
                    "is_active": true,
                    "is_online": false,
                    "last_seen_at": 1542762346134,
                    "state": "joined",
                    "role": "",
                    "metadata": {
                        "location": "New York", # A key in "metadata" can have only one value.
                        "marriage": "Y"
                    }
                },
                ... # More members
            ],
            ...
        },
        ... # More channels
    ]

}
Light Color Skin
Copy
{
    "messages": [
        {
            "message_id": 273778828,
            "user": {
                "user_id": "Julia",
                "nickname": "Yogini",
                "profile_url": "https://sendbird.com/main/img/profiles/profile_94_512px.png",
                "metadata": {
                    "location": "Bali", # A key in "metadata" can have only one value.
                    "marriage": "N"
                }
            },
            "data": "",
            "sorted_metaarray": [
                {
                    "key": "design",
                    "value": ["A", "B", "C"] # A key in "sorted_metaarray" can have an array of values.
                }
            ],
            ...
        },
        ... # More messages
    ]
}

Actions

  • API endpoints in this page are relative to the base URL allocated to your Sendbird application. The base URL for the following endpoints are https://api-{application_id}.sendbird.com/v3.

Note: If you want to know the ID and base URL of your application, sign in to your dashboard, go to the Settings > Application > General, and then check the Application ID, API request URL.

  • {channel_type}: either open_channels or group_channels.
  • It is recommended that the parameter values in API URLs be urlencoded, such as {channel_url}.

List of actions for user metadata

ActionHTTP Request

View a user 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 user metadata

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

Update a user 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 user metadata

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

List of actions for channel metadata

ActionHTTP Request

View a channel metadata

GET /{channel_type}/{channel_url}/metadata or .../metadata/{key}
Retrieves a channel metadata's one or more items that are stored in a specific channel.

Create a channel metadata

POST /{channel_type}/{channel_url}/metadata
Creates a channel metadata's items to store in a specific channel.

Update a channel metadata

PUT /{channel_type}/{channel_url}/metadata or .../metadata/{key}
Updates existing items of a channel metadata by their keys, or adds new items to the metadata.

Delete a channel metadata

DELETE /{channel_type}/{channel_url}/metadata or ../metadata/{key}
Deletes a channel metadata's one or all items that are stored in a specific channel.

List of actions for channel metacounter

ActionHTTP Request

View a channel metacounter

GET /{channel_type}/{channel_url}/metacounter or .../metacounter/{key}
Retrieves channel metacounter's one or more items that are stored in a specific channel.

Create a channel metacounter

POST /{channel_type}/{channel_url}/metacounter
Creates a channel metacounter's items to store in a specific channel.

Update a channel metacounter

PUT /{channel_type}/{channel_url}/metacounter or .../metacounter/{key}
Updates existing items of a channel metacounter by their keys, or adds new items to the metacounter.

Delete a channel metacounter

DELETE /{channel_type}/{channel_url}/metacounter or .../metacounter/{key}
Deletes a channel metacounter's one or all items that are stored in a specific channel.


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.

Required
Parameter nameTypeDescription

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 characters. The value must be a string and its length is limited to 190 characters. 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.

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 characters. The value must be a string and its length is limited to 190 characters. This property can have up to 5 items.

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 items 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.


View a channel metadata

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

HTTP request

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

// When retrieving a specific item of a channel metadata by its key
GET https://api-{application_id}.sendbird.com/v3/{channel_type}/{channel_url}/metadata/{key}

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

channel_type

string

Specifies the type of the channel. Either open_channels or group_channels.

channel_url

string

Specifies the URL of the target channel.

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=background_image,description

Response

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

Status: 200 OK
Light Color Skin
Copy
{
    "background_image": "https://sendbird.com/main/img/bg/theme_013.png",
    "description": "A chat room for discussing the upcoming project."
}

Create a channel metadata

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

HTTP request

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

Parameters

The following table lists the parameters that this action supports.

Required
Parameter nameTypeDescription

channel_type

string

Specifies the type of the channel. Either open_channels or group_channels.

channel_url

string

Specifies the URL of the channel 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 characters. The value must be a string and its length is limited to 190 characters. This property can have up to 5 items.

OptionalTypeDescription

include_ts

boolean

Determines whether to include the timestamp of when a metadata has been created in the response. (Default: false)

Request body example
Light Color Skin
Copy
{
    "metadata": {
        "background_image": "https://sendbird.com/main/img/bg/theme_013.png",
        "text_size": "large",
        "description": "A chat room for discussing the upcoming project."
    },
    "include_ts": true
}

Response

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

Status: 200 OK
Light Color Skin
Copy
{
    "metadata": {
        "background_image": "https://sendbird.com/main/img/bg/theme_013.png",
        "text_size": "large",
        "description": "A chat room for discussing the upcoming project."
    },
    "include_ts": 1606110872558
}

Update a channel metadata

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

HTTP request

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

// When updating a specific item of a channel metadata by its key
PUT https://api-{application_id}.sendbird.com/v3/{channel_type}/{channel_url}/metadata/{key}

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

channel_type

string

Specifies the type of the channel. Either open_channels or group_channels.

channel_url

string

Specifies the URL of the target channel.

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 which has key-value items to update. A key can't contain a comma (,) and its length is limited to 128 characters. A value must be a string and its length is limited to 190 characters. This property can have up to 5 items.

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": {
        "background_image": "https://sendbird.com/main/img/bg/theme_018.png",   // Updated
        "text_size": "small",   // Updated
        "text_color": "purple"  // Added
    },
    "upsert": true
}

// When updating a specific item by its key
{
    "value": "https://sendbird.com/main/img/bg/theme_018.png"
}

Response

If successful, this action returns the updated and added items in the metadata in the response body.


Delete a channel metadata

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

HTTP request

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

// When deleting a specific item of a channel metadata by its key
DELETE https://api-{application_id}.sendbird.com/v3/{channel_type}/{channel_url}/metadata/{key}

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

channel_type

string

Specifies the type of the channel. Either open_channels or group_channels.

channel_url

string

Specifies the URL of the channel which 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.


View a channel metacounter

Retrieves channel metacounter's one or more items that are stored in a channel.

HTTP request

Light Color Skin
Copy
// When retrieving all items of a channel metacounter
GET https://api-{application_id}.sendbird.com/v3/{channel_type}/{channel_url}/metacounter

// When retrieving a specific item of a channel metacounter by its key
GET https://api-{application_id}.sendbird.com/v3/{channel_type}/{channel_url}/metacounter/{key}

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

channel_type

string

Specifies the type of the channel. Either open_channels or group_channels.

channel_url

string

Specifies the URL of the target channel.

OptionalTypeDescription

key

string

Specifies the key of metacounter item to retrieve the values of. If not specified, all items of the metacounter 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 metacounter keys to retrieve the values of. If not specified, all items of the metacounter 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
../metacounter?keys=likes,dislikes

Response

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

Status: 200 OK
Light Color Skin
Copy
{
    "likes": 0,
    "dislikes": 3
}

Create a channel metacounter

Creates a channel metacounter's items to store in a channel.

HTTP request

Light Color Skin
Copy
POST https://api-{application_id}.sendbird.com/v3/{channel_type}/{channel_url}/metacounter

Parameters

The following table lists the parameters that this action supports.

Required
Parameter nameTypeDescription

channel_type

string

Specifies the type of the channel. Either open_channels or group_channels.

channel_url

string

Specifies the URL of the channel to store the metacounter in.

Request body

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

Properties
RequiredTypeDescription

metacounter

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 characters. The value must be an integer. This property can have up to 5 items.

Request body example
Light Color Skin
Copy
{
    "metacounter": {
        "likes": 0,
        "dislikes": 0,
        "giveups": 0
    }
}

Response

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

Status: 200 OK
Light Color Skin
Copy
{
    "likes": 0,
    "dislikes": 0,
    "giveups": 0
}

Update a channel metacounter

Updates existing items of a channel metacounter by their keys, or adds new items to the metacounter.

HTTP request

Light Color Skin
Copy
// When updating existing items of a channel metacounter by their keys or adding new items to the metacounter
PUT https://api-{application_id}.sendbird.com/v3/{channel_type}/{channel_url}/metacounter

// When updating a specific item of a channel metacounter by its key
PUT https://api-{application_id}.sendbird.com/v3/{channel_type}/{channel_url}/metacounter/{key}

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

channel_type

string

Specifies the type of the channel. Either open_channels or group_channels.

channel_url

string

Specifies the URL of the target channel.

OptionalTypeDescription

key

string

Specifies the key of metacounter item to update the values of. If not specified, the items in the metacounter 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

metacounter

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 characters. The value must be an integer. This property can have up to 5 items.

OptionalTypeDescription

mode

string

Specifies how to calculate the item value of the metacounter. Acceptable values are increase, decrease, and set. If set to increase, increments the item value of the metacounter by the value specified in the metacounter property, while decrease decrements. set sets the item value to the specified value exactly. (Default: set)

upsert

boolean

Determines whether to add new items in addition to updating existing items. If true, new key-value items in the metacounter 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 the values of existing items by their keys and adding new item to the metacounter
{
    "metacounter": {
        "likes": 1          // Updated
        "happinesses": 0    // Added
    },
    "mode": "increase",
    "upsert": true
}

// When updating the value of a specific item by its key
{
    "value": 2,
    "mode": "increase",
    "upsert": false
}

Response

If successful, this action returns the updated and added items in the metacounter in the response body.

Status: 200 OK
Light Color Skin
Copy
// When updating the values of existing items by their keys and adding new item to the metacounter
{
    "likes": 1,     # 0 + 1 = 1
    "dislikes": 0,
    "giveups": 0,
    "happinesses": 0
}

// When updating the value of a specific item by its key
{
    "likes": 3,     # 1 + 2 = 3
    "dislikes": 0,
    "giveups": 0,
    "happinesses": 0
}

Delete a channel metacounter

Deletes a channel metacounter's item that is stored in a channel.

HTTP request

Light Color Skin
Copy
// When deleting all items of a channel metacounter
DELETE https://api-{application_id}.sendbird.com/v3/{channel_type}/{channel_url}/metacounter

// When deleting a specific item of a channel metacounter by its key
DELETE https://api-{application_id}.sendbird.com/v3/{channel_type}/{channel_url}/metacounter/{key}

Parameters

The following table lists the parameters that this action supports.

Parameters
RequiredTypeDescription

channel_type

string

Specifies the type of the channel. Either open_channels or group_channels.

channel_url

string

Specifies the URL of the channel which has the metacounter to delete.

OptionalTypeDescription

key

string

Specifies the key of metacounter item to delete. If not specified, all items of the metacounter 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.