Slack Integration
The Slack integration brings Q directly into your team's conversations. You can @mention Q to ask questions with full tool access, use /heyq slash commands for quick interactions, and receive project event notifications — all without leaving Slack.
Slack integration is available on the Builder and Team plans.
What You Can Do
@Q Mentions (Full AI)
Mention @Q in any mapped channel to interact with the full sidebar AI. Q can:
- Read any file in your project
- Search across all pages and missions
- Create new pages
- Create missions on any board
- Update mission statuses
- Answer questions using the full project context
Q responds in a thread and follows up on replies, maintaining conversation history.
/heyq Slash Commands (Lightweight AI)
Slash commands give you quick access without the overhead of the full AI:
| Command | What it does |
|---|---|
/heyq help | Show available commands |
/heyq status | Project status overview with mission board summaries |
/heyq create | Open a form to create a mission or page |
/heyq create --type mission --board Dev --title "Fix login bug" | Quick-create a mission without a form |
/heyq create --type page --title "Competitor Analysis" | Quick-create a page without a form |
/heyq <any question> | Ask Q a context-aware question |
Slash commands use a lightweight AI that has a snapshot of your project context but no tools. For deeper interactions (reading files, creating content), use @Q instead.
Setup
Connect Slack
Go to Project Settings → Integrations → Chat Integration and click Connect Slack. This opens the Slack OAuth flow and installs the Q bot in your workspace.
Map a channel to your project
After connecting, add a channel mapping. Enter the Slack channel ID (right-click the channel name → View channel details → the ID is at the bottom of the panel). Optionally enter a display name.
Choose event subscriptions
Select which project events should trigger notifications in the channel — for example, mission created, status changed, page updated, or AI proposals.
Enable Q for the channel
Toggle Q enabled to allow @Q mentions and /heyq commands in the
mapped channel.
Invite Q to the channel
In Slack, type /invite @Q in the mapped channel so the bot can read
messages and post responses.
@Q vs /heyq — When to Use Which
| @Q Mention | /heyq Slash Command | |
|---|---|---|
| AI | Full sidebar AI with tools | Lightweight AI, no tools |
| Can read files | Yes | No (uses a context snapshot) |
| Can create/update | Yes (pages, missions) | Only via /heyq create |
| Thread follow-ups | Yes | No (one-shot) |
| Speed | Slower (multi-step tool use) | Fast |
| Best for | Deep questions, actions | Quick status checks, simple questions |
Use /heyq for quick questions like "what's the project status?" and @Q for
anything that requires reading or changing project content.
User Linking
Q automatically links your Slack account to your HeyQ account by matching email addresses. Once linked:
- Actions you trigger from Slack (creating missions, pages) are attributed to you in the activity log.
- Activity entries show a Slack icon next to your name to indicate the action came from chat.
Channel Mapping
Each channel mapping connects a Slack channel to one Q project. You can:
- Map multiple channels to the same project (e.g.,
#productand#devboth linked to the same Q project) - Map channels from different projects to keep conversations scoped
Channel mappings are managed in Project Settings → Integrations → Chat Integration.
Disconnecting
To disconnect Slack:
- Go to Project Settings → Integrations → Chat Integration
- Click the trash icon next to the connected Slack workspace
- Confirm the disconnection
This removes the workspace link and all channel mappings. The Slack app itself remains installed in your Slack workspace — you can uninstall it from Slack's app settings if needed.
Troubleshooting
"I'm not connected to a HeyQ project in this channel yet" — The channel isn't mapped to a project. Go to Project Settings → Integrations and add a channel mapping with the correct channel ID.
@Q doesn't respond at all — Make sure the bot is invited to the channel
(/invite @Q) and that the channel mapping has Q enabled toggled on.
Activity shows "API" instead of my name — Your Slack account isn't linked to your HeyQ account yet. This happens automatically on your next interaction if your Slack and HeyQ emails match.
"not_in_channel" error — The bot isn't a member of the channel. Type
/invite @Q in Slack to add it.