Skip to main content
After this guide, people in a Slack workspace can message your agent directly or mention it in a channel, and it answers in a thread. A private connection uses one Slack app’s bot token and serves one workspace; a public connection registers an app other workspaces can install. Both paths exist in the admin dashboard and in lua channels, and both hand you an app manifest that configures Slack for you. Verified against lua-cli 3.33.0. Before you begin
  • A Slack app created at api.slack.com/apps (Create New App → From scratch) in a workspace you can install apps to.
  • Private: the app’s Bot User OAuth Token, which starts with xoxb-, from OAuth & Permissions after a first install with at least the users:read scope.
  • Public: the App ID, Client ID, and Client Secret from Basic Information → App Credentials.
  • An agent with a promoted production version; see Release an agent.
1

Link the app

In the admin dashboard open Agents, select the agent, select + in the Channels section of its Overview tab, and choose Slack in Connect a channel. Choose Private — just my workspace or Public — a distributable app, say whether you already have a Slack app (the wizard walks you through creating one otherwise), enter the Bot token or the App ID, Client ID, and Client Secret, and select Connect. The next dialog shows the app Manifest to copy into Slack’s App Manifest page and, for a public app, an Add to Slack button.
2

Provider console: apply the manifest

In your Slack app open App Manifest, switch to JSON, paste the manifest, and save. It sets the fourteen bot scopes listed under Limits, subscribes the bot to app_mention, message.channels, message.groups, message.im, and message.mpim, points Event Subscriptions and Interactivity at https://wa.heylua.ai/slack/webhook, and adds the OAuth redirect URL https://auth.heylua.ai/slack/oauth_redirect/<appId>. Edit display_information to name the app. For a private app, reinstall it to the workspace so the token picks up the new scopes.
3

Public only: install through Lua

Open the install URL the admin dashboard or CLI gave you and approve the installation. It completes OAuth with Lua and moves the channel from pending_setup to active.
Slack’s own Install to Workspace button creates a token inside Slack but never reaches Lua, so the channel stays pending. Use the install URL.
4

Verify

Send the app a direct message with hello; it answers in a thread under your message. Invite it to a channel and mention it; it answers in a thread there too. lua channels list shows a SLACK entry.

​
Response settings

Once connected, select the Slack channel in the admin dashboard to open Slack settings; Response behavior offers Mentions only, DMs and mentions (the default), and Auto-respond in channels, which adds a list of channels to pick. Mentions are always answered. Direct messages are answered unless the mode is mentions_only. Messages in channels the app belongs to are answered only in auto_respond mode and only in the listed channels. Reactions need the reactions:write scope; an app installed before that scope was in the manifest keeps its old token until the workspace reauthorises it, and the agent silently skips the reaction until then.

​
Channel behavior

To put something in front of a Slack workspace unprompted, either let people ask the agent in-channel, or connect Slack as an integration and have a job post through it; as a channel, Slack is where people talk to the agent.

​
Limits

  • Bot scopes: chat:write, channels:history, groups:history, im:history, mpim:history, channels:read, groups:read, im:read, mpim:read, users:read, app_mentions:read, users:read.email, files:read, reactions:write.
  • One private connection per workspace and app; one public connection per App ID per agent.
  • images renders only the first image.

​
Troubleshooting

The bot token was issued before the manifest was applied. Apply the manifest, reinstall the app to the workspace, and link again with the new xoxb- token.
The app was installed with Slack’s button instead of the install URL, so OAuth never returned to Lua. Open https://auth.heylua.ai/slack/install/<appId> and approve it there.
That is the default dms_and_mentions mode. Mention the app, or set responseMode to auto_respond and add the channel’s ID to autoRespondChannels.

​
Next steps

Connect Microsoft Teams

The other team-chat channel, admin dashboard only.

Response formatting

What each component becomes in Slack.

lua channels

Every menu item and what it prints.

About channels

Channels and integrations, and why Slack is on both lists.