v1

latestOpenAPI 3.0.02026-08-04891301.4 MB

Create or update a Slack channel binding

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.

post/api/v1/slack_channel_bindings

Request body

agent_user_idsstring[] 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_idstring required

Slack channel ID to bind (e.g. C01234ABCDE). Acts as the natural key of the binding within the workspace.

customer_labelstring

Human-readable label for the customer associated with this channel. Stored in the binding's config. null if omitted.

is_ext_shared_cachedboolean

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_idstring required

Slack workspace team ID that the channel belongs to (e.g. T01234ABCDE). Identifies which Slack integration to use.

team_idstring required

ID of the team to bind the Slack channel to. The caller must have team-manage rights on this team.

Example request

{
  "agent_user_ids": [
    "string"
  ],
  "channel_id": "string",
  "customer_label": "string",
  "is_ext_shared_cached": true,
  "slack_team_id": "string",
  "team_id": "string"
}

Response

Successful response

agentsstring[]

IDs of the agents attached to this binding. Empty array when no agents are assigned.

channelstring

Slack channel ID (e.g. C01234ABCDE) that this binding targets.

customer_labelstring

Human-readable label identifying the customer, derived from the binding's embedded config. null when not set.

idstring required

Unique identifier for this Slack channel binding.

integrationstring

ID of the Slack integration that owns this binding.

is_ext_shared_cachedboolean

Cached value of Slack's is_ext_shared flag for this channel. May be stale relative to Slack's current state.

teamstring

ID of the ArchAstro team this channel is bound to.

Example response

{
  "agents": [
    "string"
  ],
  "channel": "C01234ABCDE",
  "customer_label": "string",
  "id": "string",
  "integration": "string",
  "is_ext_shared_cached": true,
  "team": "string"
}