Developer Hub
Slack Skill Setup
Connect Slack workspaces to raia agents, control direct-message and channel access, enable files, and test conversations.
Let users chat with your raia agents inside Slack. This guide walks an organization administrator through connecting a Slack workspace, adding the Slack skill to an agent, and controlling who can reach the agent from direct messages and channels.
How it works
The Slack skill connects a raia agent to one or more Slack workspaces. A Slack workspace is connected once at the organization level. Each agent then decides, per workspace, which Slack users can send it direct messages and which channels it answers in.
Once configured, Slack users can:
- Send direct messages to the raia app and get a reply from the agent.
- @mention the raia app in a channel to bring the agent into a thread. The agent replies in the thread and only responds when mentioned.
- @mention the raia app in a group DM to chat with the agent alongside teammates.
- Attach files (when file upload is enabled) for the agent to read.
- Use slash commands to get help, check which agent is active, or start a fresh conversation.
Every Slack exchange is stored as a raia conversation with the source Slack, so it shows up in your conversation views, reports, and logs like any other channel.
Before you start
| Requirement | Details |
|---|---|
| raia role | You must be able to manage the organization (to connect or disconnect a workspace) and edit the agent's skills (to configure the skill). |
| Slack permission | You must be allowed to install apps in the Slack workspace. Some workspaces require a Slack admin to approve the app the first time it is installed. |
| An agent | The agent should exist and be in Active or Draft status. Archived agents never respond in Slack. |
| Matching emails (recommended) | raia identifies Slack users by the email on their Slack profile. For the Require known raia user option to work, that email must match the user's raia account email. |
Step 1: Connect a Slack workspace
You can start from either the agent or the organization settings. Both paths run the same Slack authorization flow.
Option A: Start from the agent (fastest)
- Open Agents and select the agent.
- Open the Skills tab and choose Add skill, then pick Slack.
- On the new Slack skill card, click SET UP. This opens the agent's Slack skill page.
- If no workspace is connected yet, click Connect.
- Slack opens its authorization screen. Choose the workspace in the top-right corner, review the requested permissions, and click Allow.
- You are returned to the agent's Slack skill page with a confirmation that the workspace is connected.
When you connect from an agent, raia also enables that workspace for the agent right away with safe defaults: all channels, anyone can DM, and Require known raia user turned on for both channels and direct messages. You can change these in Step 2.
Option B: Start from organization settings
- Open Organization settings, then Integrations, then Slack.
- Click Connect Slack.
- Complete the Slack authorization screen as described above.
- You are returned to the Slack integrations page. The workspace appears with a Connected badge, the granted permissions, and the list of agents that use it.
Connecting from organization settings does not enable the workspace for any agent. Continue with Step 2 for each agent that should respond in Slack.
Connecting more than one workspace
Repeat either option to connect additional workspaces. An organization can connect several workspaces, and the same workspace can be connected to more than one raia organization. Each agent chooses which connected workspaces it participates in.
Step 2: Configure the agent's Slack skill
Open the agent, go to Skills, and open the Slack skill. The page shows global settings for the skill followed by one section per connected workspace.
Global settings
| Setting | Default | What it does |
|---|---|---|
| File Upload Enabled | On | Lets Slack users attach files to their messages. Limits: up to 5 files per message, 20 MB per file, no empty files. Unsupported file types are skipped and the user is told. When off, the agent replies that uploads are disabled. |
| Auto Complete Ended Chat | On | Marks the raia conversation as complete when the agent detects the conversation has ended. |
| Auto Archive Chat | Off | Archives the raia conversation after a period of inactivity. Turning it on reveals Auto Archive Chat Timeout (Minutes), which must be a whole number of at least 1. |
At least one of Auto Complete Ended Chat or Auto Archive Chat must stay on. The form prevents you from turning off the last one. When a conversation is completed or archived, the Slack user is told and their next message starts a new conversation.
Per-workspace settings
Each connected workspace has its own collapsible section.
- Enable the workspace for this agent. Use the toggle in the section header. Active means the agent responds in that workspace. Disabled pauses this agent only; other agents using the same workspace are unaffected.
- Users: who can send direct messages.
| Option | Behavior |
|---|---|
| Anyone | Any member of the workspace can DM the agent, including in group DMs. |
| Only selected people | Pick specific Slack users from a searchable list. Only those users can DM the agent. |
| Require known raia user | In addition to the option above, the sender's Slack email must match a raia user account. Users without a match get a message asking them to contact their admin. |
- Channels: where the agent answers @mentions.
| Option | Behavior |
|---|---|
| All channels | The agent responds in every public or private channel the raia app has been invited to. |
| Only selected channels | Pick specific channels from a searchable list. Private channels show a lock icon. Channels the app has not joined are greyed out with the hint Invite the bot to this channel first. |
| Require known raia user | Only Slack users whose email matches a raia account can @mention the agent in channels. |
- Click Save.
The page header shows Pending until at least one enabled workspace grants user or channel access, and Active once it does. The skill card on the agent's Skills tab reflects the same state.
Step 3: Invite the raia app to channels
The raia app only sees channels it has been added to. In each channel where the agent should respond:
- Type
/invite @raiain the channel (or add the app from the channel details panel). - The app posts a short welcome message explaining that it replies only when mentioned.
- If you use Only selected channels, return to the agent's Slack skill page. The channel is now selectable in the list.
Private channels work the same way; a member must invite the app.
Step 4: Test it in Slack
Direct message. Open the raia app from the Apps section in Slack's sidebar and send a message. The app shows a typing status while the agent is working and replies in the DM.
Channel. In an invited channel, post @raia <your question>. The agent replies in a thread under your message. Mention the app again for each follow-up in that thread.
Group DM. Add the raia app to a group DM and @mention it the same way as in a channel.
Files. Attach a file to a DM or a channel mention. The app confirms it is processing the attachment and replies once it is ready.
If several agents are allowed to respond in the same place, the app asks the user to pick one. The choice is remembered per DM and per channel thread until the user changes it or starts a new conversation.
Slash commands
| Command | Where it works | What it does |
|---|---|---|
/raia_help | Anywhere | Shows how to use raia in Slack and lists the available commands. |
/raia_status | 1:1 DM only | Shows which agent is active in this DM and the current conversation ID. |
/raia_new | 1:1 DM only | Ends the current DM conversation and starts a new one with the agent. |
Slash commands cannot be run from inside a message thread. Run them from the channel or the DM itself.
Managing connections
Open Organization settings, then Integrations, then Slack to see every connected workspace, its status, the permissions it granted, and which agents use it.
Reauthorizing a workspace
A workspace shows Needs re-authorization when:
- raia has added a new Slack permission since the workspace was connected (the missing permissions are listed), or
- Slack revoked the app's access, for example because the installing user was deactivated or an admin removed the app.
Click Reauthorize on the integrations page, or Reconnect workspace on the agent's Slack skill page, and approve the Slack screen again. Agent configurations are preserved. Until you reauthorize, the agent cannot read channel lists or process files in that workspace, and may not respond at all.
Disconnecting a workspace
Click Disconnect workspace on the integrations page. The confirmation dialog lists the agents that will stop responding. Disconnecting:
- removes the workspace from every agent's Slack configuration in this organization, and
- stops the agents in this organization from responding in that workspace.
Other raia organizations connected to the same workspace are not affected. To remove the raia app from Slack entirely, a Slack admin must also remove it from the workspace's app management page.
Automatic clean-up
- When a channel is archived or deleted in Slack, raia removes it from every agent's selected-channel list and archives any active Slack conversations in that channel.
- When an agent is archived in raia, it stops responding in Slack. Users who had it selected are asked to choose another agent, if one is available.
Troubleshooting
| Symptom | Likely cause and fix |
|---|---|
| Slack does not appear in the agent's Add skill list. | The Slack skill is not enabled for your raia environment. Contact raia support. |
| The authorization screen returns an error toast in raia. | The Slack approval was cancelled, timed out, or the workspace requires admin approval for new apps. Ask a Slack admin to approve the raia app, then try Connect again. The connect link expires after 10 minutes, so start again from raia. |
| "This Slack workspace isn't connected to Raia yet." | The app is installed in Slack but no raia organization has a live connection to it. Connect the workspace from organization settings, or reauthorize it if it shows Needs re-authorization. |
| "I don't have an agent available for you yet." in a DM | No enabled agent allows this user. Check the workspace toggle, the Users setting, and whether Require known raia user is on while the Slack email does not match a raia account. |
| "I don't have an agent set up for this channel yet." after an @mention | No enabled agent includes this channel. Check the Channels setting for the workspace. If the agent uses Only selected channels, add the channel and save. |
| The agent does not react to messages posted in a channel. | Channels are mention-only by design. Users must @mention the raia app, including for follow-ups in a thread. |
| "Channel list unavailable" on the agent's Slack skill page | The workspace was connected before the channel-reading permissions were added. Click Reauthorize Slack workspace and approve the Slack screen. |
| A channel is greyed out with "Invite the bot to this channel first". | The raia app is not a member of that channel. Invite it in Slack, then refresh the page. |
| "File uploads are disabled for this agent in Slack." | Turn on File Upload Enabled in the agent's Slack skill settings. |
| "This workspace needs to be reconnected to Raia before file uploads can work." | The workspace is missing the file-reading permission. Reauthorize the workspace. |
| "You've reached the usage limit for now." | The organization or agent has hit a message quota. Review plan limits and the Message Quota skill in raia. |
| "I'm unable to identify your account." | Require known raia user is on and the user's Slack profile email does not match any raia user. Update the Slack email or invite the user to raia with that email. |
Frequently asked questions
What happens if multiple agents match the same scope? The app posts an agent picker and asks the user to choose. The choice is remembered for that DM or channel thread. In a 1:1 DM the user can switch by running /raia_new and picking a different agent.
What is the difference between disabling a workspace and disconnecting it? Disabling, on the agent's Slack skill page, stops only that agent from responding in that workspace. Disconnecting, on the organization integrations page, removes the workspace from every agent in the organization.
Can one agent serve several Slack workspaces? Yes. Connect each workspace to the organization, then enable and scope each one in the agent's Slack skill settings.
Can several agents share one workspace? Yes. Give each agent its own channel or user scope. Where scopes overlap, users pick which agent they want.
Does the agent respond in group DMs? Yes, when @mentioned. Group DMs follow the Users settings for the workspace.
Where do Slack conversations show up in raia? In the agent's conversations with the source Slack. Administrative actions such as connecting a workspace or changing the skill configuration are recorded in the organization's action logs under the Slack source.
Is the Slack token stored securely? Yes. Bot tokens are encrypted at rest and never shown in the raia interface beyond a masked preview on the integrations page.