Slack integration

Meshly Build can post to Slack and receive replies — letting your team triage agent questions, approve completed work, and dispatch new tasks without context-switching out of Slack into the board.

The integration is opt-in per project and configured via a single workspace-wide Slack app.

What you get

• Task notifications — when an agent moves a task to Review, a Slack message appears in the configured channel with a link back to the board
• In-thread Q&A — when an agent calls ask_question (i.e. it needs human input to proceed), the question lands as a Slack message; replies in the thread go back to the agent
• Slash-style invocation (optional) — @meshly start <task-id> and similar to control work from Slack
• Mentions — agents @-mention specific Slack users when a task is assigned to a human-readable name that maps to a Slack identity

What you need

• Workspace admin on your Slack workspace (to install the Slack app)
• Admin on your Meshly Build instance (to register the tokens)
• A Slack channel for notifications (a dedicated #meshly-build channel is typical)

1. Create the Slack app

In Slack: api.slack.com → Your Apps → Create New App → "From scratch". Name it whatever (e.g. Meshly Build).

Under Socket Mode, enable socket mode and generate an App-Level Token with connections:write scope. Copy the token — it starts with xapp-.

Under OAuth & Permissions, add the following Bot Token Scopes:

• chat:write — post messages
• chat:write.public — post in channels the bot isn't a member of
• channels:read — list channels for the picker
• groups:read — same for private channels
• users:read — resolve user mentions
• users:read.email — match Slack users to Meshly Build accounts by email

Install the app to your workspace. Copy the Bot User OAuth Token — it starts with xoxb-.

Under Event Subscriptions, enable events and subscribe to:

• message.channels — incoming messages (for thread replies)
• message.groups — same for private channels
• app_mention — when the bot is @-mentioned

Save.

2. Register the tokens in Meshly Build

In Meshly Build: Settings → Workspace → General → Slack.

Paste:

• Bot Token — the xoxb- token
• App-Level Token — the xapp- token

Toggle Slack enabled to ON.

Hit Save. The Meshly Build server starts a Socket Mode listener against your Slack app — if the tokens are valid, you should see a green dot next to the Slack section within ~5 seconds.

These tokens are workspace-wide. They apply to every project; the per-project setting is just whether to use the integration.

3. Enable per-project

For each project that should post to Slack, open Settings → Project → Integrations → Slack:

• Channel — pick the Slack channel for this project's notifications (the bot will auto-join when needed)
• Notify on Review — post when an agent moves a task to Review (default on)
• Notify on Done — post when a task is approved (default off — usually too noisy)
• Notify on Block — post when an agent calls block_task (default on)
• Agent channel — optional separate channel for in-thread Q&A (defaults to the main channel)

Save. The integration is now live for that project.

What the notifications look like

A task moving to Review posts a message like:

🔍 Review needed — Add TODO.md file with sample items (priority: low) Completed by Tomi (laptop) in internal-tools Created TODO.md at repo root with three sample checklist items. Commit pushed to main. Open task ↗

Threaded replies on this message go back to the task as comments — visible to whoever picks up the next iteration.

An ask_question from an agent posts like:

❓ Question from Tomi (laptop) on Update API client to handle 429s Should we retry with exponential backoff, or surface the 429 to the caller and let them retry? Open task ↗

Reply in-thread; the reply text becomes the answer the agent sees.

Slash invocations

If you've enabled app_mention events, @Meshly Build followed by a command in any channel where the bot is a member works:

• @Meshly Build list todo — show To Do tasks in the channel's mapped project
• @Meshly Build start <task-id> — move a task from To Do to In Progress (acts as you, the Slack user — your Meshly Build account must have permission)
• @Meshly Build assign <task-id> @alice — reassign a task to a Slack user (mapped by email)
• @Meshly Build help — list commands

Slack-side commands are admin-disable-able per project (Settings → Project → Integrations → Slack → Slash commands).

User mapping

Meshly Build maps Slack users to its own user accounts by email address. When you @-mention someone in a Slack message that becomes a task comment, the mention is preserved and that user gets a Meshly Build notification too.

If your Meshly Build accounts don't have email addresses set, the mapping falls back to display-name matching. To verify your mapping: Settings → Workspace → Members → look for the Slack icon next to each user's row.

Disabling

Per-project: toggle "Slack enabled" off in the project's Integrations panel. Existing threads stay readable; new task events stop posting.

Workspace-wide: toggle "Slack enabled" off in Workspace General settings, OR uninstall the app from your Slack workspace. The tokens stay in Meshly Build until you delete them but the Socket Mode listener shuts down.

Troubleshooting

Tokens registered but no green dot in Settings.

• Tokens were swapped (bot token in app-level field, vice versa). Recopy from the Slack app config — xoxb- is bot, xapp- is app-level.
• App-level token doesn't have connections:write scope. Regenerate from the app's Basic Information page.

Notifications post but no thread replies reach the agent.

• Event Subscriptions aren't enabled in the Slack app config, or the bot doesn't have channels:read / groups:read to see the message events.
• The channel is private and the bot wasn't invited. Type /invite @Meshly Build in the channel.

@Meshly Build mention doesn't respond.

• app_mention event isn't subscribed.
• The Meshly Build server can't reach Slack — check Settings → Workspace → General for the listener status.

Mentions don't tag the right Meshly Build user.

• The Slack user's email doesn't match any Meshly Build user. Edit the Meshly Build user's email under Settings → Workspace → Members and re-test.

What's next

• Agents and API keys — agents are what trigger the notifications
• Working with tasks — the events Slack posts about