Add Slack ingress to a Brand

Slack ingress is per-Brand BYO: the Brand creates their own Slack App, hosts it in their workspace, and pastes the credentials into Aroovo. Aroovo never owns the bot identity for a Brand's tenants.

Who runs this. The Brand-Owner. Requires the Brand to already be created and authenticated (see Set up BYO Entra) and at least one Tenant under the Brand.

1. Create the Slack App

Open api.slack.com/apps and click Create New App → From scratch. Pick a name (e.g. Acme Agents) and the Brand's primary workspace.

2. Add bot scopes

Open OAuth & Permissions → Scopes → Bot Token Scopes and add:

  • app_mentions:read — receive @mentions in channels.
  • chat:write — post replies.
  • im:history, im:read, im:write — DM support.
  • users:read, users:read.email — resolve Slack user id → email for identity mapping.

Click Install to Workspace. Note the resulting bot token (xoxb-...).

3. Configure event subscriptions

Open Event Subscriptions, toggle Enable Events, and set the request URL to:

https://agents.aroovo.tech/api/slack/events

Subscribe to the bot events app_mention and message.im. Save changes.

Slack will challenge the URL. Aroovo's endpoint responds to the challenge automatically; the URL will go green within a few seconds.

4. Paste credentials into Aroovo

From the Brand's admin console (/admin/brands/<slug>), open the Slack tab. Paste:

  • Bot token (xoxb-...).
  • Signing secret — from Basic Information → App Credentials.

API equivalent:

POST /api/admin/brands/<brandId>/slack-config
{
  "botToken": "xoxb-...",
  "signingSecret": "..."
}

The bot token + signing secret are encrypted under the Brand-scoped Secret vault. Plaintext is never returned over the API or logged.

5. Map Slack channels to Tenants

One Slack workspace can host bots for multiple Brand customers if the Brand is reselling agents into different end-customer workspaces from a single Slack workspace. Each channel routes to one Tenant; conversations are isolated per channel.

PUT /api/admin/brands/<brandId>/slack-config/channel-map
{
  "channelId": "C0123456789",
  "tenantSlug": "acme-customer-1"
}

To remove a mapping:

DELETE /api/admin/brands/<brandId>/slack-config/channel-map/<channelId>

6. Smoke-test

In the mapped Slack channel, @-mention the bot: “@Acme Agents, what can you do?” The agent loop dispatches, the reply posts back as a Slack message in the same thread, and the conversation appears in Aroovo's per-Tenant audit chain.

See ADR-005 for the full Slack ingress design and Concepts — Multi-channel ingress for the shared abstraction.