Channel Metadata, Metacounter

With channel metadata and channel metacounter, you can store additional information within a channel. channel metadata items allow you to store key-value pairs within a channel instance. If your aim is to store integers with atomic increasing/decreasing operations, use channel metacounter items instead.

Use cases for channel metaData/metacounter items could include 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.

  • API endpoints are relative to the base URL. In this section, the /{channel_type}/{channel_url}/metadata endpoint refers to https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/metadata.

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.

  • {channel_type}: either open_channels or group_channels.
  • All values in URL must be urlencoded (for example, {channel_type}, {channel_url}).
Action HTTP Request Description
Create a channel metadata POST /{channel_type}/{channel_url}/metadata Creates a channel metadata item to store in the channel.
View the channel metadata GET /{channel_type}/{channel_url}/metadata or GET /{channel_type}/{channel_url}/metadata/{key_name} Returns channel metadata items that are stored in the channel.
Update the channel metadata PUT /{channel_type}/{channel_url}/metadata/{key_name} or PUT /{channel_type}/{channel_url}/metadata Updates channel metadata items that are stored in the channel.
Delete the channel metadata DELETE /{channel_type}/{channel_url}/metadata/{key_name} or DELETE /{channel_type}/{channel_url}/metadata Deletes the channel metadata items that are stored in the channel.
Create a channel metacounter POST /{channel_type}/{channel_url}/metacounter Creates a channel metacounter item to store in the channel.
View the channel metacounter GET /{channel_type}/{channel_url}/metacounter or GET /{channel_type}/{channel_url}/metacounter/{key_name} Returns channel metacounter items that are stored in the channel.
Update the channel metacounter PUT /{channel_type}/{channel_url}/metacounter/{key_name} or PUT /{channel_type}/{channel_url}/metacounter Updates channel metacounter items that are stored in the channel.
Delete the channel metacounter DELETE /{channel_type}/{channel_url}/metacounter/{key_name} or DELETE /{channel_type}/{channel_url}/metacounter Deletes the channel metacounter items that are stored in the channel.

Create a channel metadata

Creates a channel metadata item to store in the channel.

POST https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/metadata
Property name Type Description
metadata nested object A JSON object that you can store key-value pairs in. A key cannot 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.
Request body example
{
    "metadata": {
        "background": "blue",
        "text_size": "large",
        "description": "This is a chat to discuss the upcoming project."
    }
}

Returns a channel metadata object.

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

View the channel metadata

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

// When getting multiple items
GET https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/metadata  

// When getting an item by key
GET https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/metadata/{key_name}
Parameter name Type Description
keys string If this parameter is not included, all stored channel metadata items are returned. To receive specific values, format your parameter as key1, key2, key3,..., where all keys must be urlencoded.
Request example
?keys=background,description

Returns the corresponding channel metadata item(s).

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

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

Update the channel metadata

Updates the channel metadata item(s) stored in the channel.

// When updating multiple items
PUT https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/metadata

// When updating an item by key
PUT https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/metadata/{key_name}
Property name Type Description
metadata nested object A JSON object that you can store key-value pairs in. A key cannot 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.
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 in the items 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 channel 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 channel metadata

Deletes channel metadata item(s) stored in the channel.

Note: This deletes all of a channel's stored channel metadata items.

// When deleting all items
DELETE https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/metadata  

// When deleting an item by key
DELETE https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/metadata/{key_name}
Status: 200 OK
{}

Create a channel metacounter

Creates a channel metacounter item to store in the channel.

POST https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/metacounter
Property name Type Description
metacounter nested object A JSON object that you can store key-value pairs in. A key cannot contain a comma(,) and its length is limited to 128 bytes. A value must be an integer and its length is limited to 190 bytes.
Request body example
{
    "metacounter": {
        "likes":0
    }
}

Returns a channel metacounter object.

Status: 200 OK
{
    "likes": 0
}

View the channel metacounter

Returns the channel metacounter item(s) stored in the channel.

// When getting multiple items
GET https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/metacounter/  

// When getting item by key
GET https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/metacounter/{key_name}
Parameter name Type Description
keys string If you do not include this parameter, all stored channel metacounter items is returned. To receive specific values, format your parameter as key1, key2, key3,... , where all keys must be urlencoded.
Request example
?keys=likes,dislikes

Returns the corresponding channel metacounter items.

Status: 200 OK
// When getting multiple items
{
    "likes": 0,
    "dislikes": 3
}

// When getting item by key
{
    "key_name": value
}

Update the channel metacounter

Updates the channel metacounter item(s) stored in the channel.

// When updating multiple items
PUT https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/metacounter  

// When updating item by key
PUT https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/metacounter/{key_name}
Property name Type Description
metacounter nested object A JSON object that you can store key-value pairs in. A key cannot 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.
mode (optional) string Acceptable values are increase, decrease, and set. increase increments the channel metacounter item by the value specified in the metacounter field, while decrease decrements. set sets the item to the exact value. (Default: set)
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 in the items that matches the key you specify. (Default: false)
Request body example
// When updating multiple items
{
    "metacounter": {
        "likes": 1
    },
    "mode": "increase",
    "upsert": false
}

// When updating item by key
{
    "value": 2,
    "mode": "increase",
    "upsert": false
}

Returns the corresponding channel metacounter item(s).

Status: 200 OK
// When updating multiple items
{
    "likes": 1
}

// When updating item by key
{
    "likes": 3
}

Delete the channel metacounter

Deletes the channel metacounter item(s) stored in the channel.

Note: This deletes all of a channel's stored channel metadata items.

// When deleting all items
DELETE https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/metacounter  

// When deleting an item by key
DELETE https://{region_identifier}.sendbird.com/v3/{channel_type}/{channel_url}/metacounter/{key_name}
Status: 200 OK
{}