Skip to main content

Slack

Start and continue Factory sessions through a Slack direct message or app mention. A linked Slack account routes new sessions to its Default factory. Use Slack to create Work cards or reply in existing threads to continue sessions.

Before you connect​

You need a running Factory with working model access, a target repository, and a verified sandbox configuration. A workspace administrator may need to install the Slack app.

If your server operator has already configured Slack, continue with Link your account. The generated server includes the integration, but the operator must supply its app credentials and reachable endpoints before users can connect.

Configure the Slack app​

Set the public endpoints​

Slack needs a public HTTPS endpoint for requests. For local testing, forward a public HTTPS tunnel to the Factory Server. Keep browser authentication on its working local origin and set the separate channels origin:

.env
MASTRACODE_PUBLIC_URL=http://localhost:4111
MASTRACODE_CHANNELS_PUBLIC_URL=https://your-factory-tunnel.example.com

Replace the example channels URL with your actual public origin. For a deployed server, use its public HTTPS origin.

Use the channels origin with these paths in the Slack app settings:

Slack settingPath to append to the public channels origin
OAuth redirect URL for account linking/connect/slack/oidc/callback
Event Subscriptions request URL/api/agent-controllers/mastra-code/channels/slack/webhook
Interactivity request URL/api/agent-controllers/mastra-code/channels/slack/webhook

These webhook paths use the generated Factory controller's ID. A customized controller must use its own registered path. Keep the tunnel running while testing. Changing its hostname requires updating both the server configuration and Slack settings.

Install and configure the app​

Create an app in Slack's app settings. The Factory app manifest provides the app features, scopes, and subscriptions used by the server. Replace its example origin before applying it.

  1. Enable a bot user and the App Home messages tab so users can send direct messages.
  2. Configure the bot permissions and subscribe to app_mention, message.channels, message.groups, message.im, and message.mpim events.
  3. Install the app into the intended workspace and copy its bot token to the server's protected environment.
  4. Copy the app's signing secret, client ID, and client secret to the server.

The manifest's bot scopes cover messages, history, user lookup, reactions, files, and assistant features. Review them with your workspace administrator. Reinstall the app after changing its installation permissions.

Sign in with Slack links a user's identity through OpenID Connect. Its openid and profile permissions use a different authorization flow from bot installation. Each teammate connects their Slack account in Settings → Connections → Slack. Slack's Events API delivers the messages after setup.

Set the server credentials​

Store the app's values in the server environment, preserving other generated settings:

.env
SLACK_APP_SIGNING_SECRET=your-slack-signing-secret
SLACK_APP_BOT_TOKEN=your-slack-bot-token
SLACK_APP_CLIENT_ID=your-slack-client-id
SLACK_APP_CLIENT_SECRET=your-slack-client-secret

The signing secret enables the integration and verifies inbound requests. The bot token allows replies. Account linking also needs the client credentials and an HTTPS redirect origin. Configure credential encryption before users connect, and preserve the signing secret across restarts.

  1. Restart Factory, then verify the request URLs in Slack's Event Subscriptions and Interactivity & Shortcuts settings.
  2. Invite the app to a test channel, or open its direct messages.
  1. In Factory, open Settings → Connections → Slack.
  2. Select Connect Slack and complete the Slack sign-in flow.
  3. Return to Factory and confirm the displayed workspace and Slack identity.
  4. Under Session behavior, choose a Default factory.

This account link and default Factory are personal. Each teammate links their own identity. The default controls where new Slack sessions are routed. Existing sessions stay with their original Factory.

Work items​

Under Work items, configure Create work items for new Slack threads. This is a Factory-level setting.

When enabled, a new routed thread creates a Work card in Building and uses the thread's session. Subsequent replies continue that session without creating another card.

For discussion without the normal agent reply, start a message with aside. In a thread linked to a Work item, that discussion can be recorded in its comment feed. See Sessions.

To test your connection or diagnose errors, see Slack troubleshooting.