@agentforge-io/connectors-slack

Slack connector for AgentForge. Wires Slack's user-OAuth grant into the host's ConnectorRegistryService so agents and automations can act on behalf of the authorized user — post messages, read channels, search history, send DMs, react, and upload files.

Install

npm install @agentforge-io/connectors-slack

Peer dep: @agentforge-io/core ^2.0.10.

Bootstrap

import { slackConnector } from '@agentforge-io/connectors-slack';

registry.register(
  slackConnector({
    clientId: process.env.SLACK_CLIENT_ID!,
    clientSecret: process.env.SLACK_CLIENT_SECRET!,
  }),
);

In the AgentForge platform host, these credentials live in the vault (SLACK_CLIENT_ID + SLACK_CLIENT_SECRET) and the wiring happens inside HostConnectorsModule.onApplicationBootstrap. End-users never see them.

OAuth scopes

The connector requests the following scopes at authorize time. Adding a tool that needs a new scope is a breaking change — every existing connection has to re-authorize.

| Scope | Used by | |---|---| | chat:write | slack_post_message, slack_send_dm | | channels:read | slack_post_message (channel-name resolution) | | channels:history | slack_read_channel (public channels) | | groups:history | slack_read_channel (private channels) | | im:history | slack_read_channel (DMs) | | im:write | slack_send_dm | | users:read | slack_send_dm (email lookup) | | reactions:write | slack_add_reaction | | files:write | slack_upload_file | | search:read | slack_search_messages |

Tools

slack_post_message

Post a message to a channel, group, or DM.

@slack_post_message  channel="#general"  text="ship is in 5 minutes"

slack_read_channel

Read recent messages. Cursor-paginated; the LLM decides whether to iterate.

@slack_read_channel  channel="C0123ABC"  limit=20

slack_search_messages

Full-text search across everything the user can see. Accepts the same DSL as Slack's in-app search.

@slack_search_messages  query='from:@alice in:#engineering after:2026-05-01'

slack_send_dm

DM another user. Resolves email → user id when needed.

@slack_send_dm  email="[email protected]"  text="check pinned messages in #q3-planning"

slack_add_reaction

React to a message.

@slack_add_reaction  channel="C0123ABC"  timestamp="1690000000.000100"  name="white_check_mark"

slack_upload_file

Upload + share a file. Accepts UTF-8 text or base64-encoded bytes.

@slack_upload_file  filename="report.csv"  content="..."  channels="C0123ABC"

Auth model

User token (xoxp-*) only. The connector acts as the user who authorized — posts are visible as them, reads are limited to channels they belong to, etc. Bot-token mode is not supported in v1; raise an issue if you need it.

Tokens are long-lived: Slack's classic user grant does not expire tokens automatically. They invalidate only when the user revokes access or a workspace admin rotates them. There is no refresh-token flow — ConnectorAuth.refreshTokenEncrypted stays null.

Multi-workspace

v1 limits each AgentForge user to ONE active Slack workspace connection. Reconnecting to a different workspace soft-revokes the previous one (isActive=false). v1.1 will open the unique key to allow concurrent workspaces; the team.id is already persisted in ConnectorAuth.metadata to make that migration straightforward.

Errors

| Slack error | When it happens | Suggested LLM behavior | |---|---|---| | invalid_auth / token_revoked | User revoked or admin rotated | UI prompts re-authorize | | missing_scope | Tool needs a scope the user didn't grant | Surface needed from SlackApiError; ask user to reconnect | | channel_not_found | Bad ID or user not a member of a private channel | LLM tells the user / picks another channel | | not_in_channel | User isn't a member of a public channel | LLM suggests joining first | | ratelimited | Slack rate cap hit | Wrapper retries once with Retry-After, then throws | | users_not_found | DM target email isn't in the workspace | LLM falls back to channel post or asks user |

Out of scope

• Events API (incoming webhooks) — separate SDD.
• Slash commands.
• Workflow Builder integration.
• Slack Canvas.
• Block Kit visual builder in the UI.
• Bot token (xoxb-*) mode.
• Enterprise Grid org-level install flow.

License

MIT.