Connect a Slack bot and one of your agents will reply in DMs, channels it's invited to, and threads. Frona uses Slack's Socket Mode, so the engine does not need a public URL. It opens an outbound WebSocket to Slack instead.

What you need

• A Slack workspace where you can install apps
• A Slack App created at api.slack.com/apps
• Two tokens from that app:
  • A Bot User OAuth Token (starts with xoxb-)
  • An App-Level Token with the connections:write scope (starts with xapp-)

No public URL is required. The engine connects out to Slack over WebSocket.

Creating the Slack app

The fastest path is to create the app from a manifest. The manifest below sets up Socket Mode, the right scopes, and the right event subscriptions in one step. Manual setup is documented further down if you'd rather click through.

From a manifest (recommended)

1. Go to api.slack.com/apps and click Create New App → From a manifest.
2. Pick the workspace and click Next.
3. Switch the editor to JSON, replace the contents with the snippet below, and click Next → Create.

{
  "display_information": {
    "name": "Frona",
    "description": "Slack connector for a Frona agent"
  },
  "features": {
    "bot_user": {
      "display_name": "Frona",
      "always_online": true
    }
  },
  "oauth_config": {
    "scopes": {
      "bot": [
        "channels:history",
        "chat:write",
        "groups:history",
        "im:history",
        "im:read",
        "users:read"
      ]
    }
  },
  "settings": {
    "socket_mode_enabled": true,
    "event_subscriptions": {
      "bot_events": [
        "message.channels",
        "message.groups",
        "message.im"
      ]
    }
  }
}

After the app is created:

4. Open Basic Information → App-Level Tokens and click Generate Token and Scopes. Add the connections:write scope, name the token (any value), and create it. Copy the xapp-… token; you'll paste it into Frona.
5. Open Install App and click Install to Workspace, then approve. Copy the Bot User OAuth Token (xoxb-…).

You now have both tokens. Skip the manual section and continue to Connecting the channel.

Manual setup (alternative)

1. Go to api.slack.com/apps and click Create New App → From scratch. Name it and pick the workspace.
2. Open Socket Mode in the left sidebar and toggle Enable Socket Mode on. When prompted, create an App-Level Token with the connections:write scope. Copy the xapp-… token; you'll paste it into Frona.
3. Open OAuth & Permissions. Under Bot Token Scopes, add at minimum:
   • chat:write. Send messages.
   • im:history, im:read. Receive DMs.
   • channels:history, groups:history. Receive messages in channels and private channels the bot is in.
   • users:read. Resolve sender display names.
4. Open Event Subscriptions and enable events. Under Subscribe to bot events, add:
   • message.im (DMs)
   • message.channels and/or message.groups (channels)
5. Open Install App and click Install to Workspace. Copy the Bot User OAuth Token (xoxb-…).

Connecting the channel

Connection happens in two stages. A short dialog creates the channel, then the channel's detail page is where you paste the tokens (via Frona's vault).

Step 1: Create the channel

1. In Frona, open Settings → Channels and click Add channel.
2. Pick Slack from the provider list. The create dialog opens.
3. Fill in the dialog:
   • Space. Defaults to Slack. This is the space the conversation will live in. Keep the default to create a new space with that name, type any other name to create a different one, or pick an existing space from the dropdown. A space can host only one channel, so spaces already bound to another channel are hidden.
   • Agent. The agent that reads every incoming message and sends the reply.
   • When a message arrives. How inbound messages are handled:
     • Treat as a message from you (default). The agent runs full inference and replies. The first inbound message you send pairs your Slack user to the channel.
     • Hand off to a waiting agent. The message goes to whichever task is currently waiting on a signal (e.g., a 2FA code). The agent does not reply on this channel. See Signals.
4. Click Create.

You land on the channel detail page. The status is Setup until both tokens are configured.

Step 2: Configure the tokens

Open the Config tab on the channel detail page. The Provider Config panel lists bot_token and app_token. Both are secrets, so they're set via Frona's credential picker rather than a raw text field.

For each field:

1. Click Configure.
2. Pick a vault connection. You can use a configured password manager (1Password, Bitwarden, HashiCorp Vault, KeePass) or Local to keep the secret in Frona's encrypted store.
3. Either pick an existing vault item, or click New credential to create one. For Local, choose API key, name it (e.g., slack-bot-token), and paste the xoxb-… or xapp-… value.
4. Pick the field on the item that holds the token.
5. Click Save in the dialog.

After both tokens are configured, click Save at the top of the channel page. The adapter opens a Socket Mode connection and the channel transitions to Connected.

Step 3: Pair your Slack user

By default the channel doesn't trust any sender, so even your own messages are ignored. Pair the channel to your Slack user so the agent treats you as a self-source:

1. On the channel detail page, click Pair. A short code appears (e.g. XYZ-123).
2. DM the bot the code from your own Slack user, or post it in a channel the bot can see.
3. The channel records your Slack user ID as a paired address and the conversation goes live.

From then on, messages from that user pass the default receive_message policy and the agent replies. Invite the bot to a channel (/invite @your-bot) or DM it to test. To pair another user, click Re-pair and repeat. To let unpaired teammates through, add a policy.

Configuration fields

Field	Required	Description
bot_token	Yes	Bot User OAuth Token from OAuth & Permissions. Starts with xoxb-. Stored encrypted.
app_token	Yes	App-Level Token with connections:write. Starts with xapp-. Stored encrypted.

How messages flow

• DMs to the bot run full inference and the agent replies in the same DM.
• Channel messages are delivered to the bot only if it's a member of the channel and the relevant *.history scope is granted.
• Mentions (@your-bot) and thread replies the bot is part of are always delivered.
• Replies are sent back to the same Slack channel (and into the thread if the original message was threaded). Markdown is rendered into Slack's mrkdwn format.

Allowlisting senders

By default only your own Slack user passes receive_message (the bot's auth.test identity is treated as self). To open the bot up to other users in the workspace, add a policy:

permit(
  principal == Policy::Agent::"assistant",
  action == Policy::Action::"receive_message",
  resource in Policy::Channel::"slack"
) when { resource.sender.address == "U0123ABC" };

The address is the Slack user ID (the U… value, not the display name). See Policies for channel-wide allows and blocks.

Tips

• Socket Mode means no public URL. This is the easiest way to run Slack against a self-hosted or development engine.
• Invite the bot to channels you want it to read. Slack will not deliver message.channels events for channels the bot isn't in.
• Use one Slack app per agent. Tokens cannot be shared and giving each agent its own app keeps the bot identity (name, avatar) clean.
• Keep the App-Level Token secret. It can open a Socket Mode connection from anywhere and impersonate your app.

Troubleshooting

Symptom	Likely cause
Channel marked Failed right after creation	bot_token rejected by Slack auth.test. Make sure you copied the Bot User OAuth Token (xoxb-…), not the App-Level Token.
Channel Failed with "Socket Mode registration failed"	app_token is missing the connections:write scope, or Socket Mode is disabled on the app.
Bot is in a channel but never sees messages	The relevant scope (channels:history / groups:history) or event subscription (message.channels / message.groups) is missing.
Bot doesn't reply in threads	Make sure the bot was added to the thread, or that someone @mentioned it there.

Next steps

• Channels. How channels work in general.
• Policies. Allow specific users or channels.