Skip to main content
The Slack notifier plugin sends formatted notifications to Slack channels using incoming webhooks. It supports rich Block Kit formatting, interactive action buttons, and contextual metadata.

​
Overview

The Slack notifier provides:
  • Rich Block Kit formatted messages
  • Priority-based emoji indicators
  • Pull request and CI status integration
  • Interactive action buttons (URL and callback)
  • Automatic timestamp formatting
  • Per-project channel routing
This plugin uses Slack’s incoming webhook API, which is simpler but less powerful than the full Slack API. For advanced features like updating messages or threading, consider building a custom notifier.

​
Configuration

Add the Slack notifier to your agent-orchestrator.yaml: 
plugins:
  notifier:
    name: slack
    config:
      webhookUrl: https://hooks.slack.com/services/YOUR/WEBHOOK/URL
      channel: "#agent-notifications"  # Optional
      username: "Agent Orchestrator"    # Optional

​
Configuration Options

​
webhookUrl
string
required
Slack incoming webhook URL. Get this from your Slack workspace:
  1. Go to https://api.slack.com/apps
  2. Create a new app or select existing
  3. Enable “Incoming Webhooks”
  4. Add webhook to your workspace
  5. Copy the webhook URL
Keep your webhook URL secret! Anyone with this URL can post to your Slack. Store it in environment variables or secure config.
​
channel
string
Default channel to post to (e.g., #agent-notifications or @username). If not specified, uses the webhook’s default channel.
You can override the channel per-notification using the context.channel parameter in the post() method.
​
username
string
default:"Agent Orchestrator"
Display name shown in Slack for the bot. Customize this to distinguish between multiple orchestrators or environments.

​
Notification Format

​
Message Structure

Slack notifications use Block Kit for rich formatting: 
🚨 pr.created — session-abc-123

Pull request created successfully for fix-login-bug

Project: my-app | Priority: urgent | Time: Jan 15, 2026 10:30 AM

🔗 View Pull Request

✅ CI: passing

[Approve] [Request Changes] [Close PR]

―――――――――――――――――――

​
Priority Emoji

Each notification includes a priority indicator:
Critical issues requiring immediate attention
Actions waiting for human decision
Warning conditions to be aware of
Informational updates

​
Action Buttons

The plugin supports two types of action buttons:
  1. URL Buttons - Direct links that open in browser
  2. Callback Buttons - Trigger callback endpoints when clicked
Callback buttons require setting up a Slack interaction endpoint to handle button clicks. The button action_id is prefixed with ao_ and includes a sanitized version of the action label.

​
Usage Examples

​
Basic Setup

plugins:
  notifier:
    name: slack
    config:
      webhookUrl: ${SLACK_WEBHOOK_URL}
      channel: "#agent-notifications"

​
Multiple Environments

projects:
  - name: production-app
    plugins:
      notifier:
        name: slack
        config:
          webhookUrl: ${SLACK_WEBHOOK_PROD}
          channel: "#prod-alerts"
          username: "Production Orchestrator"
  
  - name: staging-app
    plugins:
      notifier:
        name: slack
        config:
          webhookUrl: ${SLACK_WEBHOOK_STAGING}
          channel: "#staging-alerts"
          username: "Staging Orchestrator"

​
Team-Based Routing

projects:
  - name: frontend
    plugins:
      notifier:
        name: slack
        config:
          webhookUrl: ${SLACK_WEBHOOK_URL}
          channel: "#frontend-team"
  
  - name: backend
    plugins:
      notifier:
        name: slack
        config:
          webhookUrl: ${SLACK_WEBHOOK_URL}
          channel: "#backend-team"

​
Event Data Integration

The Slack notifier automatically includes rich metadata when available: When event data includes prUrl, a clickable link is added: 
🔗 View Pull Request

​
CI Status

When event data includes ciStatus, a status indicator is added: 
✅ CI: passing
or 
❌ CI: failing

​
Timestamp Formatting

Timestamps use Slack’s dynamic formatting for user timezone localization: 
Time: <!date^1736945400^{date_short_pretty} {time}|Jan 15, 2026 10:30 AM>

​
Advanced Features

​
Post Raw Messages

The post() method allows sending custom messages: 
const notifier = slack.create(config);
await notifier.post("Custom notification message", {
  channel: "#custom-channel"
});
The post() method uses simple text formatting instead of Block Kit. For rich formatting, use the standard notify() and notifyWithActions() methods.

​
Action Button Sanitization

Action labels are automatically sanitized for use as Slack action IDs:
  • Converted to lowercase
  • Non-alphanumeric characters replaced with _
  • Leading/trailing underscores removed
  • Index appended for uniqueness
Example: "Request Changes" → "ao_request_changes_0"

​
Troubleshooting

Check your webhook URL:
  1. Verify the URL is complete and correct
  2. Ensure the webhook hasn’t been deleted in Slack settings
  3. Test the webhook with curl:
curl -X POST -H 'Content-Type: application/json' \
  -d '{"text":"Test"}' \
  YOUR_WEBHOOK_URL
The channel parameter in config only works if your webhook’s “Post to Channel” setting in Slack allows override. Check:
  1. Slack App Settings → Incoming Webhooks
  2. Verify webhook permissions
  3. Try without channel parameter to use default
URL buttons should work automatically. For callback buttons:
  1. Set up Slack Interactivity in your app settings
  2. Configure Request URL for interactions
  3. Handle button clicks in your endpoint
  4. Match the action_id pattern: ao_<sanitized_label>_<index>
Check the logs for warnings:
[notifier-slack] No webhookUrl configured — notifications will be no-ops
Ensure webhookUrl is set in your config and properly loaded from environment variables.
Slack has message limits:
  • Text blocks: 3000 characters
  • Total message: 40,000 characters
Keep event messages concise or implement message truncation in your event handlers.

​
Security Considerations

Webhook URL Security:
  • Never commit webhook URLs to version control
  • Use environment variables: ${SLACK_WEBHOOK_URL}
  • Rotate webhooks if exposed
  • Different webhooks per environment
  • Restrict webhook permissions to specific channels

​
Source Code

View the plugin source:
  • Package: @composio/ao-plugin-notifier-slack
  • Location: packages/plugins/notifier-slack/src/index.ts

Build docs developers (and LLMs) love

Get started for freeTalk to us