Platform API
Channel Metadata

Channel Metadata, Metacounter

With channel metadata and channel metacounter, you can store additional information within a channel. Two data types allow you to store a group of key-value items in a channel. When you need an integer with atomic increasing and decreasing operations, use the metacounter instead of the metadata.

Use cases for the metadata and metacounter can be tracking the number of likes, the background color, or a long description of the channel, which can each be fetched and displayed in a UI.

Actions

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

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.

  • {channel_type}: either open_channels or group_channels.
  • It's recommended that the parameter values in API URLs are urlencoded, such as {channel_url}.
Channel metadata
ActionHTTP Request

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

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

Update a 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 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.

Channel metacounter
ActionHTTP Request

View a 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 metacounter

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

Update a 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 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 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.

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 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. A key must not have a comma (,) and its length is limited to 128 bytes. A value must be a string and its length is limited to 190 bytes.

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."
    }
}

Response

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

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

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 bytes. A 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": {
        "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 item(s) 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.

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 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. A key must not have a comma (,) and its length is limited to 128 bytes. A value must be an integer.

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 like the following.

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

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