---
title: "Create or update a Slack channel binding"
method: POST
path: "/api/v1/slack_channel_bindings"
---

# Create or update a Slack channel binding

`POST /api/v1/slack_channel_bindings`

Creates a new binding between a Slack channel and a team, or updates the
existing binding if one already exists for the given channel. The caller also
supplies a list of agents to attach to the binding and enroll as members of the
destination team.

The caller must have team-manage rights on the destination team (and on the
currently bound team if the channel is being re-pointed). Returns 403 if
permission is insufficient. All write steps are idempotent, so retrying after
a partial failure is safe.

On success the REST endpoint returns 201 Created. The script binding
(`slack.channel_bindings.upsert`) returns the full binding object including the
attached agents.

## Request body

- object
  - `agent_user_ids` string[], required — List of agent user IDs to attach to the binding and enroll as members of the destination team. Pass an empty array to bind the channel without attaching any agents.
  - `channel_id` string, required — Slack channel ID to bind (e.g. `C01234ABCDE`). Acts as the natural key of the binding within the workspace.
  - `customer_label` string — Human-readable label for the customer associated with this channel. Stored in the binding's config. `null` if omitted.
  - `is_ext_shared_cached` boolean — Cached value of Slack's `is_ext_shared` flag for the channel. When provided, this value is persisted on the binding to avoid repeated Slack API lookups. `null` if omitted.
  - `slack_team_id` string, required — Slack workspace team ID that the channel belongs to (e.g. `T01234ABCDE`). Identifies which Slack integration to use.
  - `team_id` string, required — ID of the team to bind the Slack channel to. The caller must have team-manage rights on this team.

## Response `200`

Successful response

- SlackChannelBinding — A binding that connects a Slack channel to an ArchAstro team and one or more agents, enabling those agents to receive and respond to messages in that channel.
  - `agents` string[] — IDs of the agents attached to this binding. Empty array when no agents are assigned.
  - `channel` string — Slack channel ID (e.g. `C01234ABCDE`) that this binding targets.
  - `customer_label` string — Human-readable label identifying the customer, derived from the binding's embedded config. `null` when not set.
  - `id` string, required — Unique identifier for this Slack channel binding.
  - `integration` string — ID of the Slack integration that owns this binding.
  - `is_ext_shared_cached` boolean — Cached value of Slack's `is_ext_shared` flag for this channel. May be stale relative to Slack's current state.
  - `team` string — ID of the ArchAstro team this channel is bound to.

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `403` — Forbidden; The Slack integration referenced by this binding is not visible to the caller
- `404` — Agent not found; Team not found
- `422` — Invalid parameters; Binding org_id does not match the integration's org_id

---

[API](https://skmtc.net/archastro/apis/archastro-platform-api.md) · [All operations](https://skmtc.net/archastro/apis/archastro-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/archastro/archastro-platform-api/revisions/a8772b442f86/schema)