Connect an AI Teammate to Slack

This reference explains how to connect one Alloy AI Teammate to Slack through a dedicated Slack App. Use it when a customer wants to message an AI Teammate from Slack DMs, channels, or private channels.

• An Alloy AI Teammate already exists.
• A Slack workspace administrator can create or configure a Slack App and install it into the workspace.
• Alloy automatically creates and maintains a default workflow for each AI Teammate. A missing default workflow is

a rare exception, usually caused by a failed setup, migration, or data issue. Slack messages can register a chat before the workflow replies, but the AI will not respond until the chat is enabled and the default workflow is present and runnable.

1. Open the AI Teammate detail page in Alloy.
2. Open the `Slack` tab.
3. Copy the `Events Request URL`. It has this shape:

```text https://{api-domain}/webhooks/slack/events/{organizationId}/{employeeId} ```

1. Copy the required OAuth scopes shown in the tab.

Alloy generates the Events Request URL from the organization and AI Teammate. The same tab is where the Slack bot token and signing secret are saved after the Slack App is configured.

1. Open Slack API `Your Apps`.
2. Create a new app, or open an existing app dedicated to this AI Teammate.
3. Choose the customer's Slack workspace.

Use one dedicated Slack App per AI Teammate. Alloy uses the Slack bot user ID to prevent the same bot identity from being connected to multiple AI Teammates.

In the Slack App settings, open `OAuth & Permissions` and add the bot token scopes shown in Alloy:

• `app_mentions:read`
• `channels:history`
• `channels:read`
• `chat:write`
• `groups:history`
• `groups:read`
• `im:history`
• `im:read`
• `users:read`

Do not install the app yet. Finish the event and App Home settings first so Slack issues the Bot User OAuth Token with the final permissions and settings.

1. In the Slack App settings, open `Event Subscriptions`.
2. Turn `Enable Events` on.
3. Paste the Alloy `Events Request URL` into `Request URL`.
4. Wait for Slack to verify the URL.
5. Under `Subscribe to bot events`, add message events for the surfaces where the bot should listen, typically:
6. `message.im` for direct messages
7. `message.channels` for public channels
8. `message.groups` for private channels
9. Save changes.

The Slack app must deliver message events to Alloy. In channels and private channels, Alloy only runs the AI when the bot is addressed by mention, or when a later reply is inside a thread whose root message already addressed the bot.

If users should be able to open the app in Slack and message it directly:

1. In the Slack App settings, open `App Home`.
2. Enable the setting that allows users to send messages to the app from the messages tab.
3. Save changes.

After the bot scopes, event subscriptions, and direct message settings are configured:

1. In the Slack App settings, open `OAuth & Permissions`.
2. Click `Install to Workspace`, or `Reinstall to Workspace` if the app was installed earlier.
3. Review the requested permissions and approve the installation.

Slack issues or refreshes the Bot User OAuth Token during this step. If any scopes or app messaging settings change later, reinstall the app again before copying the token into Alloy.

In Slack:

1. Open `OAuth & Permissions`.
2. Copy the `Bot User OAuth Token`. It usually starts with `xoxb-`.
3. Open `Basic Information`.
4. Copy the `Signing Secret`.

Back in Alloy:

1. Open the same AI Teammate `Slack` tab.
2. Click `Connect`.
3. Paste:
4. the Bot User OAuth Token into the bot token field;
5. the Signing Secret into the signing secret field.
6. Save the connection.

Alloy validates the installed bot token with Slack `auth.test`, stores the Slack bot user ID and app name for display, and does not return the bot token or signing secret through the read API.

After the Slack App is connected:

1. Add or invite the bot to the Slack channel, private channel, or DM where it should operate.
2. Send a first message in that Slack conversation.
3. Return to the AI Teammate `Slack` tab in Alloy.
4. Find the newly discovered Slack chat.
5. Enable it.

Newly discovered Slack chats are disabled by default. This gives an Alloy user a chance to review each DM, channel, or private channel before the AI Teammate can respond there.

For direct messages, send a message to the bot after the DM chat is enabled.

For channels and private channels:

1. Mention the bot in a channel message.
2. Confirm the AI replies in a thread.
3. Continue in that thread. Later replies in a thread whose root message triggered the bot can continue without

repeating the mention.

If the bot sees a message before the chat is enabled, the chat appears in Alloy but the AI reply is skipped. Enable the chat and send another message to test the full flow.

• Slack Events webhook:

`POST /webhooks/slack/events/{organizationId}/{employeeId}`

• AI Teammate Slack settings:
• `GET /api/organizations/{orgId}/employees/{employeeId}/slack`
• `POST /api/organizations/{orgId}/employees/{employeeId}/slack`
• `DELETE /api/organizations/{orgId}/employees/{employeeId}/slack`
• Known Slack chats:
• `GET /api/organizations/{orgId}/employees/{employeeId}/slack/chats`
• `PUT /api/organizations/{orgId}/employees/{employeeId}/slack/chats/{chatId}/status`

The Slack webhook accepts Slack URL verification challenges before signature checks, so Slack can verify the request URL during app setup. Normal event callbacks are verified with the app signing secret using Slack's `X-Slack-Signature` and `X-Slack-Request-Timestamp` headers.

Inbound Slack events are accepted only when the AI Teammate has Slack credentials configured. Alloy ignores non-message events, Slack message subtypes, bot/self messages, duplicate Slack timestamps, and empty messages without downloadable attachments.

For accepted messages, Alloy starts the AI Teammate workflow only when:

• the Slack DM, channel, or private channel is enabled for that AI Teammate;
• direct messages are used, or a channel/private-channel message addresses the bot;
• automation is enabled for the conversation;
• the organization has available tokens;
• the AI Teammate default workflow is present and has a starting step.

Image attachments can be forwarded into the workflow input. Non-image attachments can be saved with the message but are not passed into the AI input payload.

• If Slack cannot verify the Request URL, confirm the URL exactly matches the Alloy `Events Request URL`.
• If Alloy rejects the connection, confirm the value is the Bot User OAuth Token, not the Slack app client secret.
• If messages reach Alloy but the AI does not reply, enable the discovered Slack chat in the AI Teammate `Slack`

tab and confirm the teammate default workflow is present and runnable. A missing default workflow is a rare exception and should be treated as a setup or data issue.

• If channel messages are saved but do not trigger the AI, mention the bot or continue in a thread whose root

message already mentioned the bot.

• If Slack file messages do not affect the workflow, confirm the file is an image and under the attachment size

limit.