> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ComposioHQ/agent-orchestrator/llms.txt
> Use this file to discover all available pages before exploring further.

# Slack Notifier

> Send rich notifications to Slack via incoming webhooks

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

<Note>
  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.
</Note>

## Configuration

Add the Slack notifier to your `agent-orchestrator.yaml`:

```yaml theme={null}
plugins:
  notifier:
    name: slack
    config:
      webhookUrl: https://hooks.slack.com/services/YOUR/WEBHOOK/URL
      channel: "#agent-notifications"  # Optional
      username: "Agent Orchestrator"    # Optional
```

### Configuration Options

<ParamField path="webhookUrl" type="string" required>
  Slack incoming webhook URL. Get this from your Slack workspace:

  1. Go to [https://api.slack.com/apps](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

  <Warning>
    Keep your webhook URL secret! Anyone with this URL can post to your Slack. Store it in environment variables or secure config.
  </Warning>
</ParamField>

<ParamField path="channel" type="string" optional>
  Default channel to post to (e.g., `#agent-notifications` or `@username`). If not specified, uses the webhook's default channel.

  <Info>
    You can override the channel per-notification using the `context.channel` parameter in the `post()` method.
  </Info>
</ParamField>

<ParamField path="username" type="string" default="Agent Orchestrator">
  Display name shown in Slack for the bot. Customize this to distinguish between multiple orchestrators or environments.
</ParamField>

## 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:

<AccordionGroup>
  <Accordion title="🚨 urgent">
    Critical issues requiring immediate attention
  </Accordion>

  <Accordion title="👉 action">
    Actions waiting for human decision
  </Accordion>

  <Accordion title="⚠️ warning">
    Warning conditions to be aware of
  </Accordion>

  <Accordion title="ℹ️ info">
    Informational updates
  </Accordion>
</AccordionGroup>

### 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

<Info>
  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.
</Info>

## Usage Examples

### Basic Setup

```yaml theme={null}
plugins:
  notifier:
    name: slack
    config:
      webhookUrl: ${SLACK_WEBHOOK_URL}
      channel: "#agent-notifications"
```

### Multiple Environments

```yaml theme={null}
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

```yaml theme={null}
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:

### Pull Request Links

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:

```typescript theme={null}
const notifier = slack.create(config);
await notifier.post("Custom notification message", {
  channel: "#custom-channel"
});
```

<Note>
  The `post()` method uses simple text formatting instead of Block Kit. For rich formatting, use the standard `notify()` and `notifyWithActions()` methods.
</Note>

### 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

<AccordionGroup>
  <Accordion title="Webhook returns 404 or invalid_token">
    **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:

    ```bash theme={null}
    curl -X POST -H 'Content-Type: application/json' \
      -d '{"text":"Test"}' \
      YOUR_WEBHOOK_URL
    ```
  </Accordion>

  <Accordion title="Messages not appearing in expected channel">
    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
  </Accordion>

  <Accordion title="Action buttons not working">
    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>`
  </Accordion>

  <Accordion title="No notifications being sent">
    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.
  </Accordion>

  <Accordion title="Messages are too long or cut off">
    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.
  </Accordion>
</AccordionGroup>

## Security Considerations

<Warning>
  **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
</Warning>

## Source Code

View the plugin source:

* Package: `@composio/ao-plugin-notifier-slack`
* Location: `packages/plugins/notifier-slack/src/index.ts`

## Related

* [Desktop Notifier](/plugins/notifier/desktop) - OS-native notifications
* [Webhook Notifier](/plugins/notifier/webhook) - Generic HTTP webhooks
* [Composio Notifier](/plugins/notifier/composio) - Unified notifications including Slack via Composio
* [Slack Block Kit](https://api.slack.com/block-kit) - Official Slack documentation


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.