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)

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

Prerequisites

1. Composio Account: Sign up at https://composio.dev
2. Composio SDK: Install the optional dependency
   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:

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: "[e-mail]"    # Required if defaultApp is gmail

Configuration Options

composioApiKey · string · required

Your Composio API key. Get it from the Composio Dashboard.

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

Keep your API key secure! Never commit it to version control. Use environment variables.

defaultApp · 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

You must have the corresponding app connected in your Composio account.

channelName · string

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

channelId · string

Explicit channel ID for Slack or Discord.

Slack: Channel ID like C1234567890

Discord: Numeric channel ID like 123456789012345678

If both channelName and channelId are provided, channelId takes precedence.

emailTo · string

Email recipient address. Required when defaultApp is gmail.

The plugin will throw an error at initialization if defaultApp is gmail and emailTo is not provided.

Platform-Specific Behavior

Slack

Tool Used: SLACK_SEND_MESSAGE

Payload:

{
  "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:

{
  "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

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

Gmail

Tool Used: GMAIL_SEND_EMAIL

Payload:

{
  "to": "[e-mail]",
  "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:

🚨 urgent

Critical issues requiring immediate attention (Unicode: U+1F6A8)

👉 action

Actions waiting for human decision (Unicode: U+1F449)

⚠️ warning

Warning conditions to be aware of (Unicode: U+26A0)

ℹ️ info

Informational updates (Unicode: U+2139)

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

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

Usage Examples

Slack Notifications

plugins:
  notifier:
    name: composio
    config:
      composioApiKey: ${COMPOSIO_API_KEY}
      defaultApp: slack
      channelName: "#agent-notifications"

Discord Notifications

plugins:
  notifier:
    name: composio
    config:
      composioApiKey: ${COMPOSIO_API_KEY}
      defaultApp: discord
      channelId: "123456789012345678"

Email Notifications

plugins:
  notifier:
    name: composio
    config:
      composioApiKey: ${COMPOSIO_API_KEY}
      defaultApp: gmail
      emailTo: "[e-mail]"

Multi-Environment Setup

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:

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:

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

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

Troubleshooting

SDK not installed warning

[notifier-composio] composio-core package is not installed — notifications will be no-ops

Solution: Install the SDK

npm install composio-core
# or
pnpm add composio-core

No API key configured

[notifier-composio] No composioApiKey or COMPOSIO_API_KEY configured

Solution: Set the API key

config:
  composioApiKey: ${COMPOSIO_API_KEY}

Or export environment variable:

export COMPOSIO_API_KEY=your_key_here

Invalid defaultApp error

Invalid defaultApp: "teams". Must be one of: slack, discord, gmail

Solution: Use a valid app name

config:
  defaultApp: slack  # Must be: slack, discord, or gmail

Gmail requires emailTo

emailTo is required when defaultApp is "gmail"

Solution: Add email recipient

config:
  defaultApp: gmail
  emailTo: "[e-mail]"

App not connected in Composio

Composio API returns error: “App not connected”

Solution:

1. Go to Composio Dashboard
2. Navigate to “Connected Accounts”
3. Click “Connect” for Slack/Discord/Gmail
4. Complete OAuth flow
5. Retry notification

Discord channel not found

Discord requires numeric channel IDs. Channel names may not resolve.

Solution: Use explicit channel ID

config:
  channelId: "123456789012345678"  # Numeric ID

Find channel ID:

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

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

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 - Official Composio docs
• Slack Notifier - Direct Slack webhook integration
• Webhook Notifier - Generic HTTP webhooks
• Desktop Notifier - OS-native notifications
• Notifier Plugin Interface - Technical interface