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. In `Quick setup with a Slack app manifest`, click `Copy manifest`.

The copied manifest is JSON. It includes the AI Teammate app name, bot token scopes, App Home direct-message settings, Slack event subscriptions, and the Alloy Events Request URL for this AI Teammate.

The Slack tab also displays the `Events Request URL` inside the collapsed `Troubleshooting` accordion. It has this shape:

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

1. Open Slack API `Your Apps`.
2. Click `Create New App`.
3. Choose `From an app manifest (JSON)`.
4. Pick the customer's Slack workspace.
5. Paste the manifest copied from Alloy.
6. Review Slack's summary and create the app.

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.

Slack verifies the Events Request URL while creating the app from the manifest. The manifest configures the bot token scopes, `app_mention`, direct-message, public-channel, and private-channel events, and enables direct messages in App Home.

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 a reply explicitly @-mentions a different AI bot, the sticky bot does not re-engage; the mentioned bot answers instead.

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`
• `GET /api/organizations/{orgId}/employees/{employeeId}/slack/manifest`
• 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.

Attachments are capped at `10` files, `10 MB` per file, and `30 MB` total per inbound message. 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.

During AI reply generation, Alloy sets a best-effort Slack assistant thread typing status when a thread timestamp is available.

• 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 the message @-mentions a different AI bot, the sticky bot yields to the mentioned bot.

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

limit.