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.

Batch updates run asynchronously by default: the request returns a task ID, and the updates are processed in the background. For bounded channel data updates, you can instead request synchronous execution.

When an asynchronous 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.

Synchronous channel data updates

Set synchronous: true on a server-side PUT /channels/batch request to wait for a bounded updateData database write before continuing. This mode supports channel data updates only; member operations remain asynchronous.

Provide a root filter.cids using $eq or $in with 1 to 100 CIDs. A types filter can further restrict that selection. Types-only filters, root $or or $and, and more than 100 CIDs return HTTP 400. Split larger selections into separate requests. Requests with no fields to update or no matching channels also return HTTP 400.

For example, this request freezes two channels:

{
  "operation": "updateData",
  "synchronous": true,
  "filter": {
    "cids": { "$in": ["messaging:channel-a", "messaging:channel-b"] }
  },
  "data": { "frozen": true }
}

A synchronous success includes a positive success_channels_count and no task_id:

{
  "success_channels_count": 2
}

The count is the number of matching channels loaded for the completed update, excluding missing and duplicate CIDs. It is not an affected-row count: a concurrent hard deletion can reduce the number of rows written.

Always inspect the response shape. If task_id is present, the operation was queued and you must wait for the asynchronous task before continuing, even if you sent synchronous: true. An older API node can ignore the new field during a rollout or rollback. Use an SDK release that exposes both synchronous and success_channels_count.

Database writes for one synchronous request commit together. Event delivery remains best effort and is not guaranteed by a successful response. Synchronous updates emit per-channel update events but do not emit channel_batch_update.started or channel_batch_update.completed task events. Disabling a channel can still schedule background thread read-state work.

A timeout does not prove the write failed: the database may already have committed. Read the channel state before deciding to retry. Repeating the same idempotent update may emit duplicate events. Concurrent channel updates are not serialized with this 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, using the standard query operator syntax, 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",
    ],
  },
};

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);

Webhooks

When an asynchronous batch update is started, 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 asynchronous 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 partial failure). If some channels failed to update, they are listed in failed_channels, grouped by reason - see the partial failure example.

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 });

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.