Slack

Your agent answers as a Slack app. People send it direct messages, or mention it in a channel it has joined.

Before you start

• A workspace role that can edit Agents
• Permission to create and install apps in your Slack workspace

1. Create the Slack app

1. Go to api.slack.com/apps and create a new app from scratch in your Slack workspace.

2. In OAuth & Permissions, add these bot token scopes:

   Scope	Why the agent needs it
   chat:write	Post, update and remove its messages
   app_mentions:read	Receive messages that mention it
   im:history	Receive direct messages
   users:read and users:read.email	Match the sender to a VirtuAI user by email
   files:write	Share files the agent creates

3. Install the app to your Slack workspace, and copy the Bot User OAuth Token. It starts with xoxb-.

4. In Basic Information, copy the Signing Secret.

5. In App Home, allow people to send messages to the app from the Messages tab.

2. Connect the app to the agent

1. Open Agents and edit the agent.

2. In Channels, turn on Slack. A Slack Configuration card appears.

3. Paste the Bot Token and the Signing Secret. Both are required. Optionally, change the Waiting Message. The default is ⏳ Working on your request...

   Both values are encrypted when you save them and are never shown again. The fields then show Configured; leave them blank to keep the stored values.

4. Save the agent, then edit it again. The card now shows its Integration URLs.

3. Point Slack at the agent

The card lists two URLs, one for events and one for commands:

https://<your-virtuai-host>/slack/events/<agent-id>
https://<your-virtuai-host>/slack/commands/<agent-id>

1. In your Slack app, open Event Subscriptions and turn events on. Paste the events URL as the Request URL. Slack checks it right away and should show it as verified. The check only passes once the agent is saved with its Bot Token and Signing Secret, so do step 2 first.

2. Under Subscribe to bot events, add app_mention and message.im, then save.

3. Open Slash Commands and create the commands you want from the table below. Use the commands URL as the Request URL for each one.

4. Reinstall the app if Slack asks you to.

Caution

Subscribe only to app_mention and message.im. If you also subscribe to channel message events, the agent answers every message in every channel it’s in.

Every request from Slack, including the Request URL check, is verified against the Signing Secret. Requests that fail the check, and requests for an agent that has no Slack configuration saved, are rejected with 403.

Commands

VirtuAI reads the command’s name, so create each one with exactly this name:

Command	What it does
/new [title]	Starts a new conversation, with an optional title
/resume	Lists your recent conversations. /resume 2 switches to the second one.
/status	Tells you whether the agent is working, and for how long
/cancel	Asks the agent to stop the current task
/help	Lists the commands

How messages behave

• Progress. The app posts the waiting message and updates it while the agent works. The answer replaces it.
• One conversation per person. Each Slack user has one ongoing conversation with the agent, wherever they write to it. Use /new to start fresh.
• Where answers go. The answer is posted in the channel or direct message where you wrote.
• Threads. Replies in a thread are handled, but the agent doesn’t see the rest of the thread.
• Busy agent. If you write while the agent is working, your message is queued and handled next.
• Retries. If Slack resends an event because VirtuAI took a moment to acknowledge it, the agent still answers only once.
• Text only. Files and images you send aren’t read.
• Your accounts. If your Slack email matches a member of the VirtuAI workspace, the agent uses that member’s connected accounts, for example their Gmail or Drive.
• Budgets. If the workspace has run out of budget, the app replies with the budget message instead of an answer.

Troubleshooting

Slack won’t verify the Request URL : Check that the agent is saved with its Bot Token and Signing Secret: until it is, VirtuAI rejects Slack’s check with 403. Then check that you copied the events URL, not the commands one, that the signing secret is the one from this Slack app, and that your VirtuAI address is reachable from the internet.

Events arrive but the app never answers : Check the Bot Token and Signing Secret on the agent. A wrong signing secret makes VirtuAI reject every request.

The app doesn’t answer direct messages : Check that message.im is subscribed, im:history is granted, and messages are allowed in App Home.

A command says “Unknown command” : The command name in Slack doesn’t match one in the table.