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
val channelClient = client.channel(channelType = "messaging", channelId = "general")

channelClient.create(
  memberIds = listOf("thierry", "tomasso"),
  extraData = mapOf(
    "source" to "user",
    "source_detail" to mapOf("user_id" to 123),
    "channel_detail" to mapOf(
      "topic" to "Plants and Animals",
      "rating" to "pg"
    )
  )
).execute()

// let's change the source of this channel
channelClient.updatePartial(set = mapOf("source" to "system")).execute()

// since it's system generated we no longer need source_detail
channelClient.updatePartial(unset = listOf("source_detail")).execute()

// and finally update one of the nested fields in the channel_detail
channelClient.updatePartial(set = mapOf("channel_detail.topic" to "Nature")).execute()

// and maybe we decide we no longer need a rating
channelClient.updatePartial(unset = listOf("channel_detail.rating")).execute()

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.

val channelClient = client.channel("messaging", "general")

channelClient.update(
  message = Message(
    text = "Thierry changed the channel color to green"
  ),
  extraData = mapOf(
    "name" to "myspecialchannel",
    "color" to "green",
  ),
).enqueue { result ->
  if (result is Result.Success) {
    val channel = result.value
  } else {
    // Handle Result.Failure
  }
}

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 that archived channels should be excluded. The query can also specify only archived channels.

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

// Archive the channel
channelClient.archive().enqueue { /* ... */ }

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

// Unarchive the channel
channelClient.unarchive().enqueue { /* ... */ }

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.

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

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.