channel/setPurpose

Sets or updates the purpose (description) of a Slack channel. The purpose is a longer-form description visible in the channel details panel and the channel directory. It helps members understand why the channel exists. Requires channels:manage scope.

When to Use

Channel provisioning: Automatically set the purpose when creating a new project or team channel as part of a channel provisioning workflow, ensuring every channel is documented from day one.
Scope change documentation: When a project's scope changes, update the purpose to reflect the new objectives and key contacts so members have current context.
Organization-wide standardization: Run a bulk workflow to set standardized purpose text across all channels that are currently missing one, as part of a channel hygiene initiative.
New channel onboarding: Set the purpose during channel provisioning to include key contacts, linked resources, and description so new members can quickly understand the channel's role.

Configuration

Connection

Field	Type	Required	Description
`botToken`	string	Required	Bot Token starting with `xoxb-`. Requires `channels:manage` scope.

Operation Fields

Field	Type	Required	Description
`channelId`	string	Required	The channel to update. Starts with `C` (public) or `G` (private).
`purpose`	string	Required	The new purpose text. Can be up to 250 characters. Plain text only — no markdown or special formatting.

Purpose vs. Topic: The purpose is a stable description of what the channel is for (rarely changes). The topic is a dynamic status line (updated frequently). Use channel/setPurpose for "what this channel is" and channel/setTopic for "what's happening right now."

Sample Configuration

{
  "operation": "channel/setPurpose",
  "connection": {
    "botToken": "{{credentials.slackBotToken}}"
  },
  "fields": {
    "channelId": "{{$json.channelId}}",
    "purpose": "{{$json.purpose}}"
  }
}

Validation Errors

Error Code	Cause	Resolution
`channel_not_found`	Invalid channel ID or bot is not a member of the private channel.	Verify the channel ID. For private channels, join the channel first.
`missing_scope`	Bot token lacks `channels:manage` scope.	Re-authorize the Slack app with the required scope.
`is_archived`	The channel is archived and its purpose cannot be updated.	Unarchive the channel first with `channel/unarchive`, then update the purpose.

Output

Success Port

Field	Type	Description
`channelId`	string	The channel that was updated.
`purpose`	string	The new purpose text as confirmed by Slack.
`status`	string	`success` or `error`.
`errorCode`	string	Slack error code when `status` is `error`.
`payload`	object	Full raw Slack API response.

Error Port

On failure with Continue on Error enabled, routes to the error port with status: "error" and populated errorCode.

Sample Output

{
  "channelId": "C08AB3XYZ12",
  "purpose": "Project Alpha launch coordination. Owner: Jane Smith. Linked to: https://jira.example.com/projects/ALPHA",
  "status": "success",
  "errorCode": "",
  "payload": {
    "ok": true,
    "purpose": "Project Alpha launch coordination. Owner: Jane Smith. Linked to: https://jira.example.com/projects/ALPHA"
  }
}

Expression Reference

Expression	Result
`{{$node["channel-setpurpose"].json.purpose}}`	The confirmed new purpose — use in audit logs or confirmation messages.
`{{$node["channel-setpurpose"].json.channelId}}`	Channel ID — continue chaining to `channel/setTopic` if needed.
`{{'Project ' + $json.projectName + '. Owner: ' + $json.ownerName + '. Jira: ' + $json.jiraUrl}}`	Template for a standardized project channel purpose string.
`{{$node["channel-setpurpose"].json.status === "success"}}`	Boolean gate — confirm update before proceeding.

Node Policies & GuardRails

Policy Area	Recommendation
Scope requirements	Requires `channels:manage` scope for public channels. Private channels may need `groups:write`.
Rate limiting	Tier 2 (20+ req/min). For bulk purpose-setting across many channels, add delays between calls.
No hard-coded IDs	Always source `channelId` dynamically from upstream node output. Never hard-code channel IDs.
Purpose vs. topic	Keep purpose text stable (months/years lifespan). Use `channel/setTopic` for dynamic status information that changes weekly or daily.
Standardized templates	Define a purpose template per channel type (project, team, incident, client) and enforce it in provisioning workflows. Include owner name, linked resources, and creation date.
Character limit	Purpose text is limited to 250 characters. Truncate long descriptions and link to a full brief in a document or wiki instead.

Examples

Example 1 — Channel Provisioning with Standard Purpose

After creating a project channel, sets a standardized purpose from the project metadata.

// Node 1: channel/create
{ "name": "project-{{$json.projectName | slugify}}" }

// Node 2: channel/setPurpose
{
  "channelId": "{{$node['channel-create'].json.channelId}}",
  "purpose": "{{'Project: ' + $json.projectName + ' | Owner: ' + $json.ownerName + ' | Jira: ' + $json.jiraUrl}}"
}

Example 2 — Bulk Missing Purpose Remediation

Compliance workflow that finds all channels with empty purposes and sets a placeholder requiring manual update.

// channel/getMany → loop through channels
// For each channel: channel/get to read purpose
// IF: purpose === ""
//   channel/setPurpose:
{
  "channelId": "{{$json.channelId}}",
  "purpose": "PENDING DOCUMENTATION — Channel owner please update this purpose. Created: {{$json.createdDate}}"
}

Example 3 — Client Channel with Contacts

When a client account is provisioned, creates a channel and sets its purpose with account details and contact information.

{
  "operation": "channel/setPurpose",
  "fields": {
    "channelId": "{{$json.channelId}}",
    "purpose": "{{
      'Client: ' + $json.clientName +
      ' | AM: ' + $json.accountManagerName +
      ' | Contract: ' + $json.contractEndDate +
      ' | CRM: ' + $json.crmUrl
    }}"
  }
}