Pinning Channels

Channel members can pin a channel for themselves. This is a per-user setting that does not affect other members.

Pinned channels function identically to regular channels via the API, but your UI can display them separately. When a channel is pinned, the timestamp is recorded and returned as pinned_at in the response.

When querying channels, filter by pinned: true to retrieve only pinned channels, or pinned: false to exclude them. You can also sort by pinned_at to display pinned channels first.

Pin a Channel

// Retrieve ChannelClient
val channelClient = client.channel("messaging", "example")

// Pin the channel
channelClient.pin().enqueue { /* ... */ }

// Query for channels that are pinned
val query = QueryChannelsRequest(
  filter = Filters.eq("pinned", true),
  offset = 0,
  limit = 10,
)
client.queryChannels(query).enqueue { /* ... */ }

// Unpin the channel
channelClient.unpin().enqueue { /* ... */ }

// Get a channel
const channel = client.channel("messaging", "example");

// Pin the channel
await channel.pin();

// Query for channels that are pinned
const resp = await client.queryChannels({ pinned: true });

// Query for channels for specific members and show pinned first
const pinnedFirst = await client.queryChannels(
  { members: { $in: ["amy", "ben"] } },
  { pinned_at: -1 },
);

// Unpin the channel
await channel.unpin();

// Pin the channel.
await channel.pin();

// Query for channels that are pinned.
final channels = await client.queryChannelsOnline(filter: Filter.equal('pinned', true));

// Query for channels for specific members and show pinned first.
final channels = await client.queryChannelsOnline(
  filter: Filter.in_('members', const ['amy', 'ben']),
  channelStateSort: [
    const SortOption(ChannelSortKey.pinnedAt),
  ],
);

// Unpin the channel
await channel.unpin();

ctx := context.Background()

// Get a channel
client.channel("messaging", "general")

// Pin the channel for user amy.
userID := "amy"
channelMemberResp, err := channel.Pin(ctx, userID)

// Query for channels that are pinned.
resp, err := client.QueryChannels(ctx, &QueryOption{
		UserID: userID,
		Filter: map[string]interface{}{
			"pinned": true,
		},
	})

// Query for channels for specific members and show pinned first.
resp, err = client.QueryChannels(ctx, &QueryOption{
		UserID: userID,
		Filter: map[string]interface{}{
			"members": map[string]interface{}{
        "$in": []string{"amy", "ben"},
      },
		},
		Sort: []*SortOption{
			{Field: "pinned_at", Direction: -1},
		},
})

channelMemberResp, err := channel.Unpin(ctx, userID)

// Get a channel
$channel = $client.Channel("messaging", "general")

// Pin the channel for user amy.
$userId = "amy"
$response = $channel->pin($userId);

// Query for channels that are pinned.
$response = $client->queryChannels([
    "pinned" => true,
], null, [
    "user_id" => $userId
]);

// Query for channels for specific members and show pinned first.
$response = $client->queryChannels([
        "members" => [ "$in" => [ "amy", "ben" ] ],
    ],
    [ "pinned_at" => -1 ],
    [ "user_id" => $userId ]
);

$response = $channel->unpin($userId);

# Get a channel
channel = client.channel("messaging", "general")

# Pin the channel for user amy
user_id = "amy"
response = channel.pin(user_id)

# Query for channels that are pinned
response = client.query_channels({"pinned": True}, user_id=user_id)

# Query for channels for specific members and show pinned first
response = client.query_channels(
    {"members": {"$in": ["amy", "ben"]}},
    {"pinned_at": -1},
    user_id=user_id
)

# Unpin the channel
response = channel.unpin(user_id)

# Get a channel
channel = client.channel("messaging", "general")

# Pin the channel for user amy
user_id = "amy"
response = channel.pin(user_id)

# Query for channels that are pinned
response = client.query_channels({ 'pinned': true }, sort: nil, user_id: user_id)

# Query for channels for specific members and show pinned first
response = client.query_channels(
  { 'members' => { '$in' => [ 'amy', 'ben' ] } },
  sort: { 'pinned_at': -1 },
  user_id: user_id
)

# Unpin the channel
response = channel.unpin(user_id)

// Pin the channel for user amy.
Channel.pin(channel.getType(), channel.getId(), "amy").request()

// Query for amy's channels that are pinned.
Channel.list()
    .userId("amy")
    .filterCondition(FilterCondition.in("members", "amy"))
    .filterCondition("pinned", true)
    .request();

// Query for channels for specific members and show pinned first.
Channel.list()
    .userId("amy")
    .filterConditions(FilterCondition.in("members", "amy", "ali"))
    .sort(Sort.builder().field("pinned_at").direction(Direction.DESC).build())
    .request();

// Unpin
Channel.unpin(channel.getType(), channel.getId(), "amy").request()

// Controllers

// Pin the channel for the current user.
channelController.pin { error in
    if let error {
        // handle error
    }
}

// Query all the pinned channels.
let channelListController = chatClient.channelListController(
    query: ChannelListQuery(
        filter: .and([
            .containMembers(userIds: [currentUserId]),
            .equal(.pinned, to: true)
        ])
    )
)
channelListController.synchronize { error in
    if let error {
        // handle error
    } else {
        let pinnedChannels = channelListController.channels
    }
}

// Unpin the channel for the current user.
channelController.unpin { error in
    if let error {
        // handle error
    }
}

// State layer (async-await)

// Pin the channel for the current user
try await chat.pin()

// Query all the pinned channels.
let channelList = chatClient.makeChannelList(
    with: ChannelListQuery(
        filter: .and([
            .containMembers(userIds: [currentUserId]),
            .equal(.pinned, to: true)
        ])
    )
)
try await channelList.get()
let pinnedChannels = channelList.state.channels

// Unpin the channel for the current user.
try await chat.unpin()

// Pin
var pinResponse = await _channelClient.PinAsync("messaging", "channel-id", "user-id");

// Get the date when the channel got pinned by the user
var pinnedAt = pinResponse.ChannelMember.PinnedAt;

// Get channels pinned for the user
var pinnedChannels = await _channelClient.QueryChannelsAsync(new QueryChannelsOptions
{
    Filter = new Dictionary<string, object>()
    {
        { "pinned", true },
    },
    UserId = "user-id",
});

// Unpin
var unpinResponse = await _channelClient.UnpinAsync("messaging", "channel-id", "user-id");

Global Pinning

To pin a channel for all users, use filter_tags to tag the channel as pinned. This allows you to query for globally pinned channels across your application.

// Pin globally by adding a "pinned" tag
val channelClient = client.channel("messaging", "general")
channelClient.update(message = null, extraData = mapOf("filter_tags" to listOf("pinned"))).enqueue { /* ... */ }

// Query globally pinned channels
val filter = Filters.`in`("filter_tags", listOf("pinned"))
val request = QueryChannelsRequest(filter = filter, limit = 30)
client.queryChannels(request).enqueue { /* ... */ }

// Pin globally by adding a "pinned" tag
await channel.update({ filter_tags: ["pinned"] });

// Query globally pinned channels
const pinned = await client.queryChannels({ filter_tags: { $in: ["pinned"] } });

// Pin globally by adding a "pinned" tag
Channel.update("messaging", "general")
    .filterTags(List.of("pinned"))
    .request();

// Query globally pinned channels
Channel.list()
    .filterCondition("filter_tags", FilterCondition.in("pinned"))
    .request();

// Pin globally by adding a "pinned" tag
try await channel.update(filterTags: ["pinned"])

// Query globally pinned channels
let channelListController = chatClient.channelListController(
    query: .init(filter: .in(.filterTags, values: ["pinned"]))
)
channelListController.synchronize { error in
    if let error {
        // handle error
    }
}

// Pin globally by adding a "pinned" tag
await channel.update({"filter_tags": ["pinned"]});

// Query globally pinned channels
final pinned = await client.queryChannels(
  filter: Filter.in_("filter_tags", ["pinned"]),
);

# Pin globally by adding a "pinned" tag
channel.update({"filter_tags": ["pinned"]})

# Query globally pinned channels
pinned = client.query_channels({"filter_tags": {"$in": ["pinned"]}})

// Pin globally by adding a "pinned" tag
channel.Update(ctx, map[string]interface{}{
    "filter_tags": []string{"pinned"},
}, nil)

// Query globally pinned channels
filter := map[string]interface{}{
    "filter_tags": map[string]interface{}{
        "$in": []string{"pinned"},
    },
}
resp, err := client.QueryChannels(ctx, &QueryOption{Filter: filter})

// Pin globally by adding a "pinned" tag
$channel->update(["filter_tags" => ["pinned"]]);

// Query globally pinned channels
$pinned = $client->queryChannels(["filter_tags" => ["$in" => ["pinned"]]]);

# Pin globally by adding a "pinned" tag
channel.update({"filter_tags" => ["pinned"]})

# Query globally pinned channels
pinned = client.query_channels({"filter_tags" => {"$in" => ["pinned"]}})

// Pin globally by adding a "pinned" tag
await channelClient.UpdateAsync("messaging", "general", new ChannelUpdateRequest
{
    FilterTags = new[] { "pinned" }
});

// Query globally pinned channels
var pinned = await channelClient.QueryChannelsAsync(new QueryChannelsOptions
{
    Filter = new Dictionary<string, object>
    {
        { "filter_tags", new Dictionary<string, object> { { "$in", new[] { "pinned" } } } }
    }
});

Archiving Channels

Muting Channels