Slack Bots

Connect your Gravity Rail agents to Slack. Respond to @mentions, interact via DMs, and stream real-time AI responses directly in Slack channels and threads.

Quick Start

1. Create a Slack App

1. Go to api.slack.com/apps
2. Click Create New App > From an app manifest
3. Select your workspace, paste the manifest below, and click Create

{
   "display_information": { "name": "Your Bot Name" },
   "features": {
      "bot_user": { "display_name": "Your Bot Name", "always_online": false },
      "assistant_view": { "assistant_description": "AI assistant", "suggested_prompts": [] }
   },
   "oauth_config": {
      "scopes": {
         "bot": ["app_mentions:read", "assistant:write", "channels:history", "channels:join", "channels:read", "chat:write", "groups:history", "groups:read", "im:history", "im:read", "im:write", "mpim:history", "mpim:read", "mpim:write", "users:read", "users:read.email"]
      }
   },
   "settings": {
      "event_subscriptions": {
         "bot_events": ["app_mention", "assistant_thread_context_changed", "assistant_thread_started", "message.channels", "message.groups", "message.im", "message.mpim"]
      },
      "org_deploy_enabled": true,
      "token_rotation_enabled": false
   }
}

4. Note your Signing Secret from Basic Information
5. Note your Client ID and Client Secret from OAuth & Permissions

2. Add Bot in Gravity Rail

1. Go to Settings > Slack
2. Click Add Slack App
3. Enter:
   • App Name
   • Agent (select the AI agent that will respond)
   • Signing Secret
   • Client ID
   • Client Secret
4. Save

3. Configure Slack App URLs

In your Slack app settings at api.slack.com:

1. Event Subscriptions > Enable Events > set Request URL to: https://api.gravityrail.com/api/v2/w/{workspaceUuid}/app-connections/slack/events

2. OAuth & Permissions > add both Redirect URLs:

   • https://api.gravityrail.com/api/v2/w/{workspaceUuid}/app-connections/slack/oauth/callback (bot)
   • https://api.gravityrail.com/api/v2/w/{workspaceUuid}/app-connections/slack/oauth/user/callback (user)

Replace {workspaceUuid} with your workspace UUID. These URLs are also shown when you run gr slack-apps get.

4. Install to Slack

1. Go to the Connect tab in your app configuration
2. Click Install to Slack
3. Authorize the requested permissions

Your bot is now live! Try @mentioning it in a channel.

Response Modes

Mode	When Bot Responds
Mentions (default)	Only when @mentioned
Auto	AI decides based on context
Off	DMs and slash commands only

Set in your app's Behavior tab.

Auto Mode

In Auto mode, the bot uses AI to decide when to respond. You can customize the decision criteria with the Respond When field.

Requirements for Auto mode:

• Subscribe to message.channels and message.groups events in Slack
• Invite the bot to channels with /invite @botname

Streaming Responses

Slack bots support real-time streaming with "Thinking..." indicators:

1. Enable Agents & Assistants in your Slack app settings
2. Add the assistant:write scope
3. Reinstall the app to apply new scopes

Streaming works in threads. The bot shows a "Thinking..." status while generating, then streams the response word-by-word.

Account Linking

Link Slack users to Gravity Rail members for personalized responses.

Auto-Link: Matches users by verified email automatically.

Manual: Users can link their accounts through Settings > Slack > Connect.

Linked accounts get responses personalized with member data.

Required OAuth Scopes

All 16 scopes are needed for full functionality:

Scope	Purpose
app_mentions:read	Read @mentions
assistant:write	Act as App Agent (streaming)
channels:history	Read public channel messages
channels:join	Join public channels
channels:read	View public channel info
chat:write	Send messages
groups:history	Read private channel messages
groups:read	View private channel info
im:history	Read DM messages
im:read	View DM info
im:write	Start DMs
mpim:history	Read group DM messages
mpim:read	View group DM info
mpim:write	Start group DMs
users:read	View workspace users
users:read.email	View user emails (for account linking)

Settings Reference

General

Setting	Description
App Name	Display name for this configuration
Agent	AI agent that handles interactions
Signing Secret	From Slack Basic Information
Client ID	For OAuth flows
Client Secret	For OAuth flows

Behavior

Setting	Description
Respond Mode	mentions, auto, or off
Respond When	Custom AI prompt for auto mode decisions
Reply in Threads	Whether responses go in threads
Allow DMs	Enable direct message interactions

Advanced

Setting	Description
Allowed Channels	Restrict bot to specific channel IDs
Socket Mode	Use WebSocket instead of HTTP (for firewalls)

Tips

• Test in a private channel first before deploying widely
• Use threads to keep conversations organized
• Enable streaming for a better user experience
• One app, many workspaces - install the same app to multiple Slack workspaces

Common Issues

Bot not responding to messages

Check event subscriptions, verify the signing secret matches, and ensure the bot is invited to the channel

Thread messages not received in Auto mode

Subscribe to message.channels and message.groups events, then reinstall the app

Streaming not working

Enable Agents & Assistants in Slack, add assistant:write scope, and reinstall

"Thinking..." indicator not showing

Requires assistant:write scope and messages must be in a thread

Outbound DMs (Agent-Initiated)

Agents can open a Slack DM with a member proactively — without waiting for the member to message first. This is useful for routines that need to reach out (appointment reminders, follow-ups, alerts).

Prerequisites

1. The Slack app must be installed and the agent member configured (see Quick Start above).
2. The target member must have their Slack account linked to their Gravity Rail account (see Account Linking above). The link stores the member's Slack user ID so the bot knows who to DM.
3. The im:write OAuth scope must be granted (included in the manifest above).

EventRule Configuration

Create an EventRule with action chat:create and set channel to slack:

{
  "action": "chat:create",
  "channel": "slack",
  "message": "Hi {{member.first_name}}, this is your reminder…"
}

• message: The opening message sent to the member. Supports template variables. If omitted, the workflow's initial task content is used.
• channel: slack routes the outbound chat through the Slack DM channel instead of SMS or email.

The EventRule can be triggered by any inbound event (form submission, routine schedule, workflow transition, etc.).

Thread-Reuse Behavior

If an active DM thread already exists for the same Slack app, member, and workflow, the new message is posted into that existing thread — no new Chat is created. This keeps related messages together and avoids spamming the member with separate conversations.

A new DM channel is opened (via conversations.open) only when no live thread exists. The opening message's Slack timestamp is captured and the Chat + SlackThread record are created with the same machinery used for inbound messages, so member replies flow through the existing inbound event handler seamlessly.

Error Handling

If the outbound DM cannot be delivered (member not linked, app not installed, missing scopes), the EventRule fails with a typed error rather than silently reporting success. Check the assignment activity log for details.

Related

• Channels — Overview of all communication channels
• Discord Bots — Deploy AI bots in Discord
• Workflows — Build the conversation flows that power your bot