Chat Gateways

Manage your agents from anywhere. Groove has native Telegram, Discord, and Slack gateways built into the daemon — push notifications for agent events and full command access from your phone.

Not MCP integrations

Gateways are first-class daemon components, not bolt-on MCP servers. They run inside the daemon process with direct access to the registry, process manager, and supervisor. Zero overhead, zero external processes.

Why Gateways?

The GUI is your command center for deep work. Gateways are your awareness layer — get notified when agents finish, crash, or need approval, and take quick actions without opening a browser.

• Agent completes at 2am? See it on your lock screen.
• Approval request while you're at lunch? Tap Approve right in the chat.
• Quick status check from your phone? /status in Telegram.

Setup

Telegram

1. Open Telegram and message @BotFather
2. Send /newbot and name it GroovePilot (or whatever you prefer)
3. Copy the bot token BotFather gives you
4. In Groove Settings > Gateways, click Add Gateway > Telegram
5. Paste your bot token and save
6. Open a chat with your new bot in Telegram and send /status — the chat ID is captured automatically
7. Click Test in Settings to verify notifications work

Zero dependencies

The Telegram gateway uses raw fetch() against the Bot API with long-polling. No npm packages needed — it works out of the box.

Discord

1. Go to the Discord Developer Portal
2. Create an application, add a Bot, and copy the bot token
3. Under OAuth2, generate an invite URL with bot scope and Send Messages + Read Message History permissions
4. Invite the bot to your server
5. In Groove Settings > Gateways, click Add Gateway > Discord
6. Paste your bot token and save

Optional dependency

Discord requires discord.js. Install it in the daemon package:

cd packages/daemon && npm i discord.js

Slack

1. Go to api.slack.com/apps and click Create New App > From scratch
2. Name it GroovePilot and select your workspace
3. Go to Settings > Socket Mode and toggle it on
4. It will prompt you to create an App-Level Token — name it "groove", add the connections:write scope, click Generate
5. Save the xapp-... token now — you can't view it again after closing the dialog
6. Go to Features > OAuth & Permissions and add all of these Bot Token Scopes:

Scope	Purpose
chat:write	Send messages and notifications
channels:read	List channels for the channel picker
channels:history	Receive messages in public channels
groups:read	List private channels
groups:history	Receive messages in private channels
im:history	Receive direct messages
app_mentions:read	Respond to @mentions

7. Click Install to Workspace and then Allow
8. Copy the Bot User OAuth Token (xoxb-...)
9. Go to Features > Event Subscriptions and toggle it on
10. Under Subscribe to bot events, add:
    • message.channels
    • message.im
    • app_mention
11. Click Save Changes
12. In Groove Settings > Gateways, click Add Gateway > Slack
13. Paste the Bot Token (xoxb-...) and App Token (xapp-...), then click Save
14. Select your channel from the dropdown and click Test

Commands in Slack

Slack reserves the / prefix for its own slash commands, so Groove commands use plain text in Slack. Just type status, agents, help etc. Or mention the bot: @GroovePilot status.

Important: Reinstall after adding scopes

If you add scopes after the initial install, Slack requires you to Reinstall to Workspace. The bot token changes each time you reinstall — update it in Groove Settings.

Commands

Commands work across all three platforms. Telegram and Discord use / prefix. Slack uses plain text (or @mention the bot).

Telegram / Discord	Slack	Description
/status	status	Daemon status + active agent summary
/agents	agents	List all agents with status and metrics
/spawn <role>	spawn <role>	Spawn a new agent
/kill <id>	kill <id>	Kill an agent
/approve <id>	approve <id>	Approve a pending request
/reject <id>	reject <id>	Reject a pending request
/rotate <id>	rotate <id>	Trigger context rotation
/teams	teams	List teams
/schedules	schedules	List schedules
/help	help	Show available commands

Notifications

Gateways push notifications when important things happen. Choose a preset to control what you receive:

Presets

Preset	Events
Critical (default)	Approval requests, scope conflicts, agent crashes
Lifecycle	Critical + all agent exits, rotations, scheduled spawns, QC activation
All	Everything except raw agent output and state sync

Raw agent output (agent:output) and state updates (state) are never forwarded — they're too high-frequency. Use the journalist:cycle notification for periodic activity summaries.

Event Coalescing

When multiple events fire within 3 seconds, they're batched into a single message:

• "3 agents completed: frontend-1, backend-1, tests-1"
• "2 scope conflicts detected"

Approval requests are never batched — each gets its own message with action buttons.

Approval Buttons

When an approval request arrives, all three platforms show interactive buttons:

• Telegram — inline keyboard with Approve/Reject buttons below the message
• Discord — ActionRow with green Approve and red Reject buttons
• Slack — Block Kit action buttons with primary/danger styling

After tapping a button, the message updates to show the resolution. No need to type /approve <id> — just tap.

Permissions

User Allowlist

Each gateway has an allowedUsers list. If empty, anyone who can message the bot can send commands (fine for personal bots). Add user IDs to restrict access:

• Telegram — numeric user ID (get it from @userinfobot)
• Discord — user snowflake ID (enable Developer Mode, right-click user > Copy ID)
• Slack — member ID (click profile > three dots > Copy member ID)

Command Permissions

Each gateway can be set to Full Access or Read Only:

• Full Access — all commands available (spawn, kill, approve, reject, rotate)
• Read Only — only status, agents, teams, schedules, and help

Set this in the Settings UI or via the API:

curl -X PATCH http://localhost:31415/api/gateways/tg-abc123 \
  -H "Content-Type: application/json" \
  -d '{"commandPermission": "read-only"}'

Security

• No inbound ports — Telegram uses long-polling, Discord and Slack use outbound WebSocket connections. Your firewall stays unchanged.
• Encrypted tokens — Bot tokens stored in the CredentialStore with AES-256-GCM encryption, same as provider API keys.
• Audit trail — All gateway operations logged to the audit log (gateway.create, gateway.connect, gateway.test, etc.).
• Local daemon — Gateways call daemon methods directly in-process. No HTTP round-trips, no CORS, no authentication tokens.

API

Gateways are fully manageable via the REST API. See the API Reference for all 10 endpoints.