# 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

<codetabs>

<codetabs-item value="kotlin" label="Kotlin">

```kotlin
// 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 { /* ... */ }
```

</codetabs-item>

<codetabs-item value="javascript" label="JavaScript">

```js
// 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();
```

</codetabs-item>

<codetabs-item value="dart" label="Dart">

```dart
// 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();
```

</codetabs-item>

<codetabs-item value="go" label="Go">

```go
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)
```

</codetabs-item>

<codetabs-item value="php" label="Php">

```php
// 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);
```

</codetabs-item>

<codetabs-item value="python" label="Python">

```python
# 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)
```

</codetabs-item>

<codetabs-item value="ruby" label="Ruby">

```ruby
# 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)
```

</codetabs-item>

<codetabs-item value="java" label="Java">

```java
// 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()
```

</codetabs-item>

<codetabs-item value="swift" label="Swift">

```swift
// 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()
```

</codetabs-item>

<codetabs-item value="csharp" label="C#">

```csharp
// 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");
```

</codetabs-item>

</codetabs>

## Global Pinning

Channels are pinned for a specific member. If the channel should instead be pinned for all users, this can be stored as custom data in the channel itself. The value cannot collide with existing fields, so use a value such as `globally_pinned: true`.


---

This page was last updated at 2026-03-05T19:05:23.679Z.

For the most recent version of this documentation, visit [https://getstream.io/chat/docs/go-golang/pinning_channels/](https://getstream.io/chat/docs/go-golang/pinning_channels/).