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.

// Here's a channel with some custom field data that might be useful
$channel = $client->Channel('messaging', 'thierry-jenny',
['source'=>'user','source_detail'=>['user_id'=>123],
'channel_detail'=>['topic'=>'Plants and Animals', 'rating'=> 'pg'] ]);

// let's change the source of this channel
$response = $channel->updatePartial(['source' => 'system']);

// since it's system generated we no longer need source_detail
$response = $channel->updatePartial(null,['source_detail']);

// and finally update one of the nested fields in the channel_detail
$response = $channel->updatePartial(['source_detail'=> ['topic' => 'Nature']]);

// and maybe we decide we no longer need a rating
$response = $channel->updatePartial(null,['source_detail'=>'topic']);

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.

$update = $channel->update(
	[
		'name'  => 'myspecialchannel',
		'color'	 => 'green'
	],
	[
		'text' => 'Thierry changed the channel color to green',
		'user_id' => 'thierry'
	]
);

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.