Select your Platform:
Client SDKs
Backend SDKs
Updating a Channel
Confused about "Updating a Channel"?
Let us know how we can improve our documentation:
- On This Page:
- Partial Update
- Full Update (overwrite)
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
Copied!Confused about "Partial Update"?
Let us know how we can improve our documentation:
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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// Here's a channel with some custom field data that might be useful
const channel = client.channel(type, id , {
source: "user",
source_detail:{ user_id: 123 },
channel_detail:{ topic: "Plants and Animals", rating: "pg" }
})
// let's change the source of this channel
await channel.updatePartial({ set:{ source: "system" } });
// since it's system generated we no longer need source_detail
await channel.updatePartial({ unset: ["source_detail"] });
// and finally update one of the nested fields in the channel_detail
await channel.updatePartial({ set: { "channel_detail.topic": "Nature" } });
// and maybe we decide we no longer need a rating
await channel.updatePartial({ unset: ["channel_detail.rating"] });
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// Here's a channel with some custom field data that might be useful
var channel = client.channel(type, id: id, extraData: {
"source": "user",
"source_detail" :{ "user_id": 123 },
"channel_detail" :{ "topic": "Plants and Animals", "rating": "pg" }
});
// let's change the source of this channel
await channel.updatePartial({ "set" :{ "source": "system" } });
// since it's system generated we no longer need source_detail
await channel.updatePartial({ "unset": ["source_detail"] });
// and finally update one of the nested fields in the channel_detail
await channel.updatePartial({ "set": { "channel_detail.topic": "Nature" } });
// and maybe we decide we no longer need a rating
await channel.updatePartial({ "unset": ["channel_detail.rating"] });
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# Here's a channel with some custom field data that might be useful
channel = client.channel(type, id , {
"source": "user",
"source_detail":{ "user_id": 123 },
"channel_detail":{ "topic": "Plants and Animals", "rating": "pg" }
})
# let's change the source of this channel
channel.update_partial(to_set={ "source": "system" });
# since it's system generated we no longer need source_detail
channel.update_partial(to_unset=["source_detail"]);
# and finally update one of the nested fields in the channel_detail
channel.update_partial(to_set={ "channel_detail.topic": "Nature" });
# and maybe we decide we no longer need a rating
channel.update_partial(to_unset=["channel_detail.rating"]);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
// Here's a channel with some custom field data that might be useful
val channelClient = client.channel(channelType = "messaging", channelId = "general")
channelClient.create(
members = 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()
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
// Here's a channel with some custom field data that might be useful
ChannelClient channelClient = client.channel("messaging", "general");
List<String> members = Arrays.asList("thierry", "tommaso");
Map<String, String> channelDetail = new HashMap<>();
channelDetail.put("topic", "Plants and Animals");
channelDetail.put("rating", "pg");
Map<String, Integer> userId = new HashMap<>();
userId.put("user_id", 123);
Map<String, Object> extraData = new HashMap<>();
extraData.put("source", "user");
extraData.put("source_detail", userId);
extraData.put("channel_detail", channelDetail);
channelClient.create(members, extraData).execute();
// let's change the source of this channel
Map<String, Object> setField = Collections.singletonMap("source", "system");
channelClient.updatePartial(setField, emptyList()).execute();
// since it's system generated we no longer need source_detail
List<String> unsetField = Collections.singletonList("source_detail");
channelClient.updatePartial(emptyMap(), unsetField).execute();
// and finally update one of the nested fields in the channel_detail
Map<String, Object> setNestedField = Collections.singletonMap("channel_detail.topic", "Nature");
channelClient.updatePartial(setNestedField, emptyList()).execute();
// and maybe we decide we no longer need a rating
List<String> unsetNestedField = Collections.singletonList("channel_detail.rating");
channelClient.updatePartial(emptyMap(), unsetNestedField).execute();
Full Update (overwrite)
Copied!Confused about "Full Update (overwrite)"?
Let us know how we can improve our documentation:
The updateChannel
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.
1
2
3
4
5
6
7
const update = await channel.update(
{
name: 'myspecialchannel',
color: 'green',
},
{ text: 'Thierry changed the channel color to green', user_id: "Thierry" },
);
1
2
3
4
await channel.update({
"name": "myspecialchannel",
"color": "green",
}, Message(text: "Thierry changed the channel color to green"));
1
2
3
4
5
6
7
8
9
10
$update = $channel->update(
[
'name' => 'myspecialchannel',
'color' => 'green'
],
[
'text' => 'Thierry changed the channel color to green',
'user_id' => 'thierry'
]
);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
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.isSuccess) {
val channel = result.data()
} else {
// Handle result.error()
}
}
1
2
3
4
5
6
7
8
9
10
import Stream Chat
let controller = chatClient.channelController(for: .init(type: .messaging, id: "general"))
controller.updateChannel(name: "My special channel", imageURL: nil, team: nil, extraData: .defaultValue) { error in
if let error = error {
// handle errors
print(error)
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
ChannelClient channelClient = client.channel("messaging", "general");
Map<String, Object> channelData = new HashMap<>();
channelData.put("name", "myspecialchannel");
channelData.put("color", "green");
Message updateMessage = new Message();
updateMessage.setText("Thierry changed the channel color to green");
channelClient.update(updateMessage, channelData).enqueue(result -> {
if (result.isSuccess()) {
Channel channel = result.data();
} else {
// Handle result.error()
}
});
1
2
3
4
5
6
7
8
9
10
channel.update(
{
"name": "myspecialchannel",
"color": "green",
},
update_message={
"text": "Thierry changed the channel color to green",
"user_id": "Thierry",
},
)
Request Params
Copied!Name | Type | Description | Optional |
---|---|---|---|
channel data | object | Object 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" | |
text | object | Message object allowing you to show a system message in the Channel that something changed. | Yes |