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

# Composio Notifier

> Unified notifications across Slack, Discord, and Gmail via Composio SDK

The Composio notifier plugin provides unified notifications across multiple platforms (Slack, Discord, Gmail) using the Composio SDK. It automatically handles authentication and platform-specific formatting.

## Overview

The Composio notifier provides:

* Multi-platform support (Slack, Discord, Gmail)
* Single configuration for all channels
* Automatic authentication via Composio
* Priority-based emoji indicators
* Action button support
* Automatic timeout handling (30s)
* Optional peer dependency (graceful degradation)

<Info>
  The Composio SDK is an **optional** peer dependency. If not installed, the plugin will log a warning and perform no-ops without crashing.
</Info>

## Prerequisites

1. **Composio Account**: Sign up at [https://composio.dev](https://composio.dev)
2. **Composio SDK**: Install the optional dependency
   ```bash theme={null}
   npm install composio-core
   # or
   pnpm add composio-core
   ```
3. **Connected Apps**: Connect your Slack/Discord/Gmail accounts through Composio dashboard

## Configuration

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

```yaml theme={null}
plugins:
  notifier:
    name: composio
    config:
      composioApiKey: ${COMPOSIO_API_KEY}
      defaultApp: slack              # slack | discord | gmail
      channelName: "#notifications"  # Optional: Slack channel or Discord channel
      channelId: "C1234567890"       # Optional: Slack/Discord channel ID
      emailTo: "team@example.com"    # Required if defaultApp is gmail
```

### Configuration Options

<ParamField path="composioApiKey" type="string" required>
  Your Composio API key. Get it from the [Composio Dashboard](https://app.composio.dev).

  Falls back to `COMPOSIO_API_KEY` environment variable if not specified in config.

  <Warning>
    Keep your API key secure! Never commit it to version control. Use environment variables.
  </Warning>
</ParamField>

<ParamField path="defaultApp" type="string" default="slack">
  Default notification platform. Must be one of:

  * `slack` - Send to Slack via Composio
  * `discord` - Send to Discord via Composio
  * `gmail` - Send email via Gmail

  <Info>
    You must have the corresponding app connected in your Composio account.
  </Info>
</ParamField>

<ParamField path="channelName" type="string" optional>
  Channel name for Slack (e.g., `#agent-notifications`) or Discord.

  **Slack**: Accepts channel names (`#channel`) or user IDs (`@user`)

  **Discord**: Channel names are converted to channel IDs by Composio
</ParamField>

<ParamField path="channelId" type="string" optional>
  Explicit channel ID for Slack or Discord.

  **Slack**: Channel ID like `C1234567890`

  **Discord**: Numeric channel ID like `123456789012345678`

  <Note>
    If both `channelName` and `channelId` are provided, `channelId` takes precedence.
  </Note>
</ParamField>

<ParamField path="emailTo" type="string" required-if-gmail>
  Email recipient address. **Required** when `defaultApp` is `gmail`.

  <Warning>
    The plugin will throw an error at initialization if `defaultApp` is `gmail` and `emailTo` is not provided.
  </Warning>
</ParamField>

## Platform-Specific Behavior

### Slack

**Tool Used**: `SLACK_SEND_MESSAGE`

**Payload**:

```json theme={null}
{
  "text": "🚨 pr.created — session-abc-123\nPull request created\nPR: https://...",
  "channel": "#notifications"  // Optional
}
```

**Features**:

* Supports both channel names and IDs
* Emoji-based priority indicators
* Markdown formatting
* Action URLs in message body

### Discord

**Tool Used**: `DISCORD_SEND_MESSAGE`

**Payload**:

```json theme={null}
{
  "content": "🚨 pr.created — session-abc-123\nPull request created\nPR: https://...",
  "channel_id": "123456789012345678"  // Optional, numeric only
}
```

**Features**:

* Requires numeric channel IDs (not names)
* Emoji-based priority indicators
* Markdown formatting
* Action URLs in message body

<Note>
  Discord requires numeric channel IDs. Channel names are passed to Composio, which attempts to resolve them to IDs.
</Note>

### Gmail

**Tool Used**: `GMAIL_SEND_EMAIL`

**Payload**:

```json theme={null}
{
  "to": "team@example.com",
  "subject": "Agent Orchestrator Notification",
  "body": "🚨 pr.created — session-abc-123\nPull request created\nPR: https://..."
}
```

**Features**:

* Fixed subject line: "Agent Orchestrator Notification"
* Plain text body with emoji indicators
* Action URLs listed in email body

## Priority Emoji

Each notification includes a priority indicator:

<AccordionGroup>
  <Accordion title="🚨 urgent">
    Critical issues requiring immediate attention (Unicode: U+1F6A8)
  </Accordion>

  <Accordion title="👉 action">
    Actions waiting for human decision (Unicode: U+1F449)
  </Accordion>

  <Accordion title="⚠️ warning">
    Warning conditions to be aware of (Unicode: U+26A0)
  </Accordion>

  <Accordion title="ℹ️ info">
    Informational updates (Unicode: U+2139)
  </Accordion>
</AccordionGroup>

## Message Format

### Standard Notification

```
🚨 pr.created — session-abc-123
Pull request created successfully
PR: https://github.com/owner/repo/pull/123
```

### With Actions

```
🚨 pr.created — session-abc-123
Pull request created successfully
PR: https://github.com/owner/repo/pull/123

Actions:
- Approve: https://github.com/owner/repo/pull/123
- Request Changes
```

<Info>
  Actions without URLs are listed without links. This is common for callback-based actions that require custom handling.
</Info>

## Usage Examples

### Slack Notifications

```yaml theme={null}
plugins:
  notifier:
    name: composio
    config:
      composioApiKey: ${COMPOSIO_API_KEY}
      defaultApp: slack
      channelName: "#agent-notifications"
```

### Discord Notifications

```yaml theme={null}
plugins:
  notifier:
    name: composio
    config:
      composioApiKey: ${COMPOSIO_API_KEY}
      defaultApp: discord
      channelId: "123456789012345678"
```

### Email Notifications

```yaml theme={null}
plugins:
  notifier:
    name: composio
    config:
      composioApiKey: ${COMPOSIO_API_KEY}
      defaultApp: gmail
      emailTo: "team@example.com"
```

### Multi-Environment Setup

```yaml theme={null}
projects:
  - name: production
    plugins:
      notifier:
        name: composio
        config:
          composioApiKey: ${COMPOSIO_API_KEY}
          defaultApp: slack
          channelName: "#prod-alerts"
  
  - name: staging
    plugins:
      notifier:
        name: composio
        config:
          composioApiKey: ${COMPOSIO_API_KEY}
          defaultApp: discord
          channelId: "${DISCORD_STAGING_CHANNEL}"
```

## Advanced Features

### Custom Message Posting

The `post()` method allows sending custom messages with optional channel override:

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

### Entity ID Support

The plugin passes `entityId` to Composio's `executeAction()` if needed for multi-tenant scenarios:

```typescript theme={null}
// Internal implementation
await composio.executeAction({
  action: "SLACK_SEND_MESSAGE",
  params: { text, channel },
  entityId: config.entityId  // Optional
});
```

### Timeout Handling

All Composio API calls have a 30-second timeout to prevent hanging:

```typescript theme={null}
// Automatic timeout after 30 seconds
try {
  await notifier.notify(event);
} catch (err) {
  // Error: Composio API call timed out after 30s
}
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="SDK not installed warning">
    ```
    [notifier-composio] composio-core package is not installed — notifications will be no-ops
    ```

    **Solution**: Install the SDK

    ```bash theme={null}
    npm install composio-core
    # or
    pnpm add composio-core
    ```
  </Accordion>

  <Accordion title="No API key configured">
    ```
    [notifier-composio] No composioApiKey or COMPOSIO_API_KEY configured
    ```

    **Solution**: Set the API key

    ```yaml theme={null}
    config:
      composioApiKey: ${COMPOSIO_API_KEY}
    ```

    Or export environment variable:

    ```bash theme={null}
    export COMPOSIO_API_KEY=your_key_here
    ```
  </Accordion>

  <Accordion title="Invalid defaultApp error">
    ```
    Invalid defaultApp: "teams". Must be one of: slack, discord, gmail
    ```

    **Solution**: Use a valid app name

    ```yaml theme={null}
    config:
      defaultApp: slack  # Must be: slack, discord, or gmail
    ```
  </Accordion>

  <Accordion title="Gmail requires emailTo">
    ```
    emailTo is required when defaultApp is "gmail"
    ```

    **Solution**: Add email recipient

    ```yaml theme={null}
    config:
      defaultApp: gmail
      emailTo: "team@example.com"
    ```
  </Accordion>

  <Accordion title="App not connected in Composio">
    Composio API returns error: "App not connected"

    **Solution**:

    1. Go to [Composio Dashboard](https://app.composio.dev)
    2. Navigate to "Connected Accounts"
    3. Click "Connect" for Slack/Discord/Gmail
    4. Complete OAuth flow
    5. Retry notification
  </Accordion>

  <Accordion title="Discord channel not found">
    Discord requires numeric channel IDs. Channel names may not resolve.

    **Solution**: Use explicit channel ID

    ```yaml theme={null}
    config:
      channelId: "123456789012345678"  # Numeric ID
    ```

    Find channel ID:

    1. Enable Developer Mode in Discord settings
    2. Right-click channel → Copy ID
  </Accordion>

  <Accordion title="Timeout errors">
    ```
    Composio API call timed out after 30s
    ```

    **Possible causes**:

    * Network connectivity issues
    * Composio API slowness
    * Large message payload

    **Solution**:

    * Check network connection
    * Retry the operation
    * Contact Composio support if persistent
  </Accordion>
</AccordionGroup>

## Comparison with Other Notifiers

| Feature | Composio | Slack | Webhook |
| - | - | - | - |
| Multi-platform | ✅ 3 platforms | ❌ Slack only | ✅ Any HTTP |
| Setup complexity | Medium | Low | Low |
| Authentication | Composio OAuth | Webhook URL | Custom headers |
| Message formatting | Platform-aware | Block Kit | Custom JSON |
| Action buttons | Text only | Interactive | Custom |
| Email support | ✅ Gmail | ❌ | ✅ (custom) |
| Retries | SDK handles | Manual | Built-in |
| Cost | Composio pricing | Free (webhook) | Free (DIY) |

## Source Code

View the plugin source:

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

## Related

* [Composio Documentation](https://docs.composio.dev) - Official Composio docs
* [Slack Notifier](/plugins/notifier/slack) - Direct Slack webhook integration
* [Webhook Notifier](/plugins/notifier/webhook) - Generic HTTP webhooks
* [Desktop Notifier](/plugins/notifier/desktop) - OS-native notifications
* [Notifier Plugin Interface](/api/notifier) - Technical interface


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