Batch Updates

You can perform batch updates on multiple channels at once. This is useful for making changes to a large number of channels without having to update each one individually, which could result in potentially thousands of API calls.

This functionality, unlike the single version of update channel, works asynchronously. This means that the request will return immediately, and the updates will be processed in the background.

When the update is requested, a task will be created and the task ID will be returned in the response. You can use this task ID to check the status of the update operation.

How to target channels

In order to perform batch updates, you need to target which channels you want to update.

You can do this by providing a filter that matches the channels you want to update.

The filters that are supported for batch updates are:

Filter examples

// 1) Filter by type
const filters = {
  types: { $in: ["messaging"] },
};

// 2) Filter by specific CIDs
const filtersByCIDS = {
  channel_cids: {
    $in: [
      "messaging:3b11838a-7734-4ece-8547-4b8524257671",
      "messaging:a266bee6-dc3c-4188-a37d-e554d4bfac34",
      "messaging:40fef12a-0b7c-4bcf-bd97-3ddf604efed5",
      "messaging:2a58963e-d769-4ce3-9309-bff93c14db57",
    ],
  },
};

// 1) Filter by type
filters := map[string]any{
	"types": map[string]any{
		"$in": []string{"messaging"},
	},
}

// 2) Filter by specific CIDs
filtersByCIDS := map[string]any{
	"cids": map[string]any{
		"$in": []string{
			"messaging:3b11838a-7734-4ece-8547-4b8524257671",
			"messaging:a266bee6-dc3c-4188-a37d-e554d4bfac34",
			"messaging:40fef12a-0b7c-4bcf-bd97-3ddf604efed5",
			"messaging:2a58963e-d769-4ce3-9309-bff93c14db57",
		},
	},
}

use GetStream\ChatClient;
use GetStream\GeneratedModels as Models;

$client = new ChatClient("{{ api_key }}", "{{ api_secret }}");

// 1) Filter by type
$filters = (object)[
    "types" => (object)['$in' => ["messaging"]],
];

// 2) Filter by specific CIDs
$filtersByCIDS = (object)[
    "cids" => (object)['$in' => [
        "messaging:3b11838a-7734-4ece-8547-4b8524257671",
        "messaging:a266bee6-dc3c-4188-a37d-e554d4bfac34",
        "messaging:40fef12a-0b7c-4bcf-bd97-3ddf604efed5",
        "messaging:2a58963e-d769-4ce3-9309-bff93c14db57",
    ]],
];

# 1) Filter by type
filters = {
    "types": {"$in": ["messaging"]},
}

# 2) Filter by specific CIDs
filters_by_cids = {
    "channel_cids": {
        "$in": [
            "messaging:3b11838a-7734-4ece-8547-4b8524257671",
            "messaging:a266bee6-dc3c-4188-a37d-e554d4bfac34",
            "messaging:40fef12a-0b7c-4bcf-bd97-3ddf604efed5",
            "messaging:2a58963e-d769-4ce3-9309-bff93c14db57",
        ],
    },
}

// 1) Filter by type
var filters = Map.<String, Object>of(
    "types", Map.of("$in", List.of("messaging")));

// 2) Filter by specific CIDs
var filtersByCIDS = Map.<String, Object>of(
    "channel_cids", Map.of("$in", List.of(
        "messaging:3b11838a-7734-4ece-8547-4b8524257671",
        "messaging:a266bee6-dc3c-4188-a37d-e554d4bfac34",
        "messaging:40fef12a-0b7c-4bcf-bd97-3ddf604efed5",
        "messaging:2a58963e-d769-4ce3-9309-bff93c14db57")));

using GetStream;
using GetStream.Models;

var client = new StreamClient("{{ api_key }}", "{{ api_secret }}");
var chat = new ChatClient(client);

// 1) Filter by type
var filters = new Dictionary<string, object>
{
    ["types"] = new Dictionary<string, object>
    {
        ["$in"] = new List<string> { "messaging" }
    }
};

// 2) Filter by specific CIDs
var filtersByCIDS = new Dictionary<string, object>
{
    ["cids"] = new Dictionary<string, object>
    {
        ["$in"] = new List<string>
        {
            "messaging:3b11838a-7734-4ece-8547-4b8524257671",
            "messaging:a266bee6-dc3c-4188-a37d-e554d4bfac34",
            "messaging:40fef12a-0b7c-4bcf-bd97-3ddf604efed5",
            "messaging:2a58963e-d769-4ce3-9309-bff93c14db57"
        }
    }
};

require 'getstream_ruby'

Models = GetStream::Generated::Models

# 1) Filter by type
filters = {
  'types' => { '$in' => ['messaging'] }
}

# 2) Filter by specific CIDs
filters_by_cids = {
  'cids' => {
    '$in' => [
      'messaging:3b11838a-7734-4ece-8547-4b8524257671',
      'messaging:a266bee6-dc3c-4188-a37d-e554d4bfac34',
      'messaging:40fef12a-0b7c-4bcf-bd97-3ddf604efed5',
      'messaging:2a58963e-d769-4ce3-9309-bff93c14db57'
    ]
  }
}

Supported operations

You can perform different operations on the channels but only once at a time. The supported operations are:

Channel data update properties

When using the updateData operation, you can update the following channel properties. All properties are optional - only the provided values will be updated.

Config overrides

The config_overrides object allows you to override the default channel type configuration for specific channels:

Most of the operations require additional parameters to be specified, such as the members to add or remove, or the channelData to update.

We've prepared convenience methods for all operations, some examples are shown below:

// Add members
const updater = client.channelBatchUpdater();
const filter = {
  types: {
    $in: ["messaging"],
  },
};

const members = ["user-123"];

const resp = await updater.addMembers(filter, members);

// Update channel data
const updater = client.channelBatchUpdater();
const filter = {
  types: {
    $in: ["messaging", "team"],
  },
};

const data = {
  frozen: true,
  custom: {
    color: "blue",
  },
};

const resp = await updater.updateData(filter, data);

// Note: Channel batch updates are not yet available in the Go SDK.
// This feature will be added in a future release.
// Please use individual channel update methods in the meantime.

// Add members
$response = $client->channelBatchUpdate(new Models\ChannelBatchUpdateRequest(
    operation: "addMembers",
    filter: (object)["types" => (object)['$in' => ["messaging"]]],
    members: [new Models\ChannelBatchMemberRequest(userID: "user-123")],
));

// Update channel data
$response = $client->channelBatchUpdate(new Models\ChannelBatchUpdateRequest(
    operation: "updateData",
    filter: (object)["types" => (object)['$in' => ["messaging", "team"]]],
    data: new Models\ChannelDataUpdate(
        frozen: true,
        custom: (object)["color" => "blue"],
    ),
));

# Note: Batch channel updates are not yet available in the getstream Python SDK.
# Use individual channel.update() calls or the REST API directly.

// Add members
var filter = Map.<String, Object>of(
    "types", Map.of("$in", List.of("messaging")));

var members = List.of(ChannelBatchMemberRequest.builder()
    .userID("user-123").build());

var resp = chat.channelBatchUpdate(ChannelBatchUpdateRequest.builder()
    .operation("addMembers")
    .filter(filter)
    .members(members)
    .build()).execute();

// Update channel data
var filter2 = Map.<String, Object>of(
    "types", Map.of("$in", List.of("messaging", "team")));

var data = ChannelDataUpdate.builder()
    .frozen(true)
    .custom(Map.of("color", "blue"))
    .build();

var resp2 = chat.channelBatchUpdate(ChannelBatchUpdateRequest.builder()
    .operation("updateData")
    .filter(filter2)
    .data(data)
    .build()).execute();

using GetStream;
using GetStream.Models;

var client = new StreamClient("{{ api_key }}", "{{ api_secret }}");
var chat = new ChatClient(client);

// Add members
var resp = await chat.ChannelBatchUpdateAsync(new ChannelBatchUpdateRequest
{
    Operation = "addMembers",
    Filter = new Dictionary<string, object>
    {
        ["types"] = new Dictionary<string, object>
        {
            ["$in"] = new List<string> { "messaging" }
        }
    },
    Members = new List<ChannelBatchMemberRequest>
    {
        new ChannelBatchMemberRequest { UserID = "user-123" }
    }
});

require 'getstream_ruby'

Models = GetStream::Generated::Models

# Add members
filter = {
  'types' => { '$in' => ['messaging'] }
}

resp = client.chat.channel_batch_update(Models::ChannelBatchUpdateRequest.new(
  operation: 'addMembers',
  filter: filter,
  members: [Models::ChannelBatchMemberRequest.new(user_id: 'user-123')]
))

# Update channel data
filter = {
  'types' => { '$in' => ['messaging', 'team'] }
}

resp = client.chat.channel_batch_update(Models::ChannelBatchUpdateRequest.new(
  operation: 'updateData',
  filter: filter,
  data: Models::ChannelDataUpdate.new(
    frozen: true,
    custom: { 'color' => 'blue' }
  )
))

Webhooks

When an update is started via batch updates, a webhook event channel_batch_update.started will be triggered.

Additionally, for each channel that is updated, the corresponding webhook events will be triggered as well. For example, if members are added to channels, the member.added event will be triggered for each channel that is updated.

When the batch update operation is completed, a webhook event channel_batch_update.completed will be triggered. This event will contain the task ID and the status of the operation (success or failure).

For the format of the status please see next section.

Status

You can check the status of a batch update operation by using the task ID returned when the operation was started.

To get the status of the task, you use the Get Task endpoint with the task ID.

const taskResponse = await client.getTask({ id: response.task_id });

taskResponse, err := client.GetTask(ctx, taskID, &getstream.GetTaskRequest{})

$taskResponse = $client->getTask($response->getData()->taskID);

# Note: Batch channel updates are not yet available in the getstream Python SDK.
# Use individual channel.update() calls or the REST API directly.

var taskResponse = client.getTask(response.getData().getTaskId()).execute();

using GetStream;
using GetStream.Models;

var client = new StreamClient("{{ api_key }}", "{{ api_secret }}");

var taskResponse = await client.GetTaskAsync(response.Data.TaskID);

require 'getstream_ruby'

task_response = client.common.get_task(response.task_id)

The response will contain information about the task, including its status, result, and any errors that occurred during the operation.

{
  "task_id": "23685bb3-d1c7-492b-a02a-3dbaa12855e1",
  "status": "completed",
  "created_at": "2025-12-13T10:25:15.856428Z",
  "updated_at": "2025-12-13T10:35:00.512601Z",
  "result": {
    "operation": "show",
    "status": "completed",
    "success_channels_count": 1080,
    "task_id": "23685bb3-d1c7-492b-a02a-3dbaa12855e1",
    "batch_created_at": "2025-12-13T10:25:16Z",
    "failed_channels": [
      {
        "reason": "cannot invite members to the distinct channel",
        "cids": ["messaging:550e8400-e29b-41d4-a716-446655440000"]
      },
      {
        "reason": "user not found: user_id 'user_12345' does not exist",
        "cids": ["team:7c9e6679-7425-40de-944b-e07fc1f90ae7"]
      }
    ],
    "finished_at": "2025-12-13T10:35:00.512579053Z"
  },
  "duration": "36.23ms"
}

You can try to re apply the operation on the failed channels again by creating a new task with the same operation and just the CIDs of the failed channels.