Slack

Authentication

Slack supports two token types. For Conductor, bot tokens are almost always the right choice. User tokens act on behalf of a specific person and are better suited to personal automation.

Creating a Slack App

1. 01Go to api.slack.com/apps and click Create New App.
2. 02Choose From scratch. Give it a name and pick your workspace.
3. 03Under OAuth & Permissions, scroll to Bot Token Scopes and add the scopes you need (see table below).
4. 04Click Install to Workspace. Authorize on the OAuth screen.
5. 05Copy the Bot User OAuth Token (starts with xoxb-). This goes in your Conductor config.
6. 06Under Basic Information → App Credentials, copy your Signing Secret.

You can customize the bot's display name and icon under App Home → Your App's Presence in Slack. The display name is what appears in channels when the bot posts messages.

OAuth Scopes

Add these under OAuth & Permissions → Bot Token Scopes. Start with the minimum you need — Slack lets you add scopes later (but requires reinstalling the app after changes).

After adding scopes, always click Reinstall to Workspace. Scopes only take effect after reinstall.

Socket Mode (local dev)

Socket Mode lets your app receive events over a persistent WebSocket connection instead of requiring a public HTTPS URL. This is ideal for local development or environments behind a firewall. To enable it, go to Socket Mode in your app settings, toggle it on, and generate an App-Level Token with the connections:write scope. App-level tokens start with xapp-.

{
  "plugins": {
    "slack": {
      "token": "xoxb-your-bot-token-here",
      "app_token": "xapp-1-your-app-level-token",
      "socket_mode": true
    }
  }
}

Event subscriptions still need to be configured in your app settings under Event Subscriptions, even when using Socket Mode. Subscribe to events like message.channels, message.im, and app_mention.

Conductor config

{
  "plugins": {
    "slack": {
      "token": "xoxb-your-bot-token-here",
      "signing_secret": "your-signing-secret"
    }
  }
}

Store your bot token in an environment variable and reference it via ${SLACK_BOT_TOKEN} rather than hardcoding it. Never commit tokens to source control.

Available tools

Usage examples

// Send a message to a channel
slack.message.send({
  channel: "C0123456789",   // channel ID, not name
  text: "Hello from Conductor!"
})

// Send with blocks (Block Kit)
slack.message.send({
  channel: "C0123456789",
  text: "Fallback text",
  blocks: [
    {
      type: "section",
      text: { type: "mrkdwn", text: "*Hello!* This is a block message." }
    }
  ]
})

// Reply in a thread
slack.thread.reply({
  channel: "C0123456789",
  thread_ts: "1683000000.123456",  // timestamp of the parent message
  text: "This is a thread reply"
})

// Upload a file to a channel
slack.file.upload({
  channels: ["C0123456789"],
  content: "File contents here as a string",
  filename: "report.txt",
  title: "My Report"
})

// Add a reaction to a message
slack.reaction.add({
  channel: "C0123456789",
  timestamp: "1683000000.123456",
  name: "thumbsup"   // emoji name without colons
})

Finding channel and workspace IDs

Slack's API always uses IDs, never names. Channel names can change; IDs cannot.

// Channel IDs look like: C0123456789
// To find a channel ID in Slack:
// 1. Right-click the channel name → "Copy link"
//    The link ends in /C0123456789 — that's the ID
// 2. Or: channel details → scroll to bottom → "Channel ID"
//
// Workspace ID (team ID) looks like: T0123456789
// Settings & administration → Workspace settings
// The URL contains /T0123456789

Rate limits

Slack uses a tiered rate limit system. Each API method belongs to a tier. When you exceed a tier's limit, the API returns HTTP 429 with a Retry-After header specifying seconds to wait.

Common errors

Security best practices

• —Store tokens in environment variables or a secrets manager. Never hardcode them in config files committed to source control.
• —Request only the scopes your integration actually needs. Slack's principle of least privilege reduces blast radius if a token is leaked.
• —Rotate tokens periodically and immediately if you suspect compromise. Revoke old tokens under OAuth & Permissions → Revoke tokens.
• —For production, use a dedicated bot account rather than a personal user token. This way the integration doesn't break if someone leaves the team.
• —Verify the X-Slack-Signature header on incoming webhooks using your signing secret to prevent spoofed requests.