Skip to main content
The Waterline Slack bot brings ticket progress scores into your team’s workflow. Mention @Waterline in any channel with a ticket key and the bot replies with a breakdown of which acceptance criteria are implemented, partial, or missing — without leaving Slack.
The Slack integration is in early access. Some features described here may still be rolling out to all workspaces.

​
Connect Slack

1

Open Slack settings

In Waterline, go to Settings → Integrations → Slack and click Add to Slack.
2

Authorize the app

You’ll be redirected to Slack’s OAuth page. Select your workspace and authorize the Waterline app.
3

Invite the bot to a channel

In Slack, invite @Waterline to any channel where you want to use it:
/invite @Waterline
OAuth scopes the Waterline Slack app requests:
ScopeWhy Waterline needs it
app_mentions:readReceive @Waterline mentions in channels
chat:writePost progress score replies
channels:historyRead messages to parse commands in channels
im:historyHandle direct messages to the bot

​
Usage

​
Query a ticket

Mention @Waterline followed by a ticket key in any channel the bot has been invited to: 
@Waterline PROJ-123
The bot replies with a progress breakdown: 
PROJ-123 — Add user authentication
Progress: 68%

✅ Login form submits credentials to /api/auth/login
✅ JWT token stored in httpOnly cookie
⚠️  Password reset flow — partial (email sending found, token validation missing)
❌ OAuth (Google) login — no evidence found

Analyzed against: my-org/my-repo

​
Specify a repository

If your Waterline workspace has multiple repositories connected, you can tell the bot which one to analyze against: 
@Waterline PROJ-123 repo:my-org/my-repo
The bot also works in direct messages. Open a DM with @Waterline and send a ticket key directly — no channel invite needed.

​
Self-hosted Slack app setup

If you’re running Waterline yourself, create a Slack app at api.slack.com/apps:
1

Create the app

Click Create New App → From scratch and give it a name and workspace.
2

Add a redirect URL

Under OAuth & Permissions, add a redirect URL:
https://your-api.com/api/connect/slack/callback
3

Add bot token scopes

Under OAuth & Permissions → Bot Token Scopes, add the four scopes listed above: app_mentions:read, chat:write, channels:history, and im:history.
4

Enable Event Subscriptions

Under Event Subscriptions, turn on Enable Events and set the Request URL to:
https://your-api.com/api/slack/events
Then subscribe to the app_mention and message.im bot events.
5

Install and copy credentials

Install the app to your workspace, then copy the credentials to your .env:
SLACK_CLIENT_ID=your_client_id
SLACK_CLIENT_SECRET=your_client_secret
SLACK_REDIRECT_URI=https://your-api.com/api/connect/slack/callback
SLACK_SIGNING_SECRET=your_signing_secret