Updating a Channel

There are two ways to update a channel using the Stream API - a partial or full update. A partial update will retain any custom key-value data, whereas a complete update is going to remove any that are unspecified in the API request.

Partial Update

A partial update can be used to set and unset specific fields when it is necessary to retain additional custom data fields on the object. AKA a patch style update.

// Create a channel with some custom data
var req = new ChannelGetRequest
{
  Data = new ChannelRequest
  {
    CreatedBy = new UserRequest { Id = createdByUserId },
  },
};

req.Data.SetData("source", "user");
req.Data.SetData("source_detail", new Dictionary<string, object> { { "user_id", 123} });
req.Data.SetData("channel_detail", new Dictionary<string, object>
{
  { "topic", "Plants and Animals"},
  { "rating", "pg" }
});
var channelResp = await channelClient.GetOrCreateAsync("messaging", "general", req);

// Remove channel detail rating, and set a new source
var req = new PartialUpdateChannelRequest
{

  Unset = new List<string> { "channel_detail.rating" },
  Set = new Dictionary<string, object> { { "source", "system" } }
};
await channelClient.PartialUpdateAsync(channelResp.Channel.Type, channelResp.Channel.Id, req);

Full Update (overwrite)

The update function updates all of the channel data. Any data that is present on the channel and not included in a full update will be deleted.

var updatedChannel = new ChannelUpdateRequest { Data = new ChannelRequest() };
updatedChannel.Data.SetData("name", "myspecialchannel");
updatedChannel.Data.SetData("color", "green");
updatedChannel.Message = new MessageRequest { Text = "Thierry changed the channel color to green", UserId = "thierry" }

await channelClient.UpdateAsync(channel.Type, channel.Id, updatedChannel);

Request Params

NameTypeDescriptionOptional
channel dataobjectObject with the new channel information. One special field is “frozen”. Setting this field to true will freeze the channel. Read more about freezing channels in “Freezing Channels”
textobjectMessage object allowing you to show a system message in the Channel that something changed.Yes

Updating a channel using these methods cannot be used to add or remove members. For this, you must use specific methods for adding/removing members, more information can be found here.

Archiving a channel

A member in a channel can mark the channel as archived. The archival state is stored for this member, so it doesn’t affect anybody else. From an API point of view, an archived channel is the same as another channel, but the user interface may render an archived channel in a different way. When a channel is archived, the current date is recorded and this is returned as archived_at in the response.

When querying channels, the query can specify specify that archived channels should be excluded. The query can also specify only archived channels.

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

// Archive the channel.
await channel.archive();

// Query for channels that are not archived.
const resp = await client.queryChannels({ archived: false });

Pinning a channel

Pinning works very similar to archiving. A client can mark a channel as pinned, which can be used to render it differently in the UI. When a channel is pinned, the response contains a pinned_at timestamp.

Like archiving, it’s possible to query channels with a specific pinned state. It is also possible to sort channels by pin, such as returning pinned channels first.

// 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 resp = await client.queryChannels(
  { members: { $in: ["amy", "ben"] } },
  { pinned_at: -1 },
);

Global archiving or pinning

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

© Getstream.io, Inc. All Rights Reserved.