Composio Notifier

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

Composio Account: Sign up at https://composio.dev

Composio SDK: Install the optional dependency

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

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: "[email protected]"    # 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 C1234567890Discord: 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": "[email protected]",
  "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: "[email protected]"

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: "[email protected]"

App not connected in Composio

Composio API returns error: “App not connected”Solution:

Go to Composio Dashboard
Navigate to “Connected Accounts”
Click “Connect” for Slack/Discord/Gmail
Complete OAuth flow
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:

Enable Developer Mode in Discord settings
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

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

Overview

Runtime Plugins

Agent Plugins

Workspace Plugins

Tracker Plugins

SCM Plugins

Notifier Plugins

Terminal Plugins

Overview

Prerequisites

Configuration

Configuration Options

Platform-Specific Behavior

Slack

Discord

Gmail

Priority Emoji

Message Format

Standard Notification

With Actions

Usage Examples

Slack Notifications

Discord Notifications

Email Notifications

Multi-Environment Setup

Advanced Features

Custom Message Posting

Entity ID Support

Timeout Handling

Troubleshooting

Comparison with Other Notifiers

Source Code

Build docs developers (and LLMs) love

Overview

Runtime Plugins

Agent Plugins

Workspace Plugins

Tracker Plugins

SCM Plugins

Notifier Plugins

Terminal Plugins

​Overview

​Prerequisites

​Configuration

​Configuration Options

​Platform-Specific Behavior

​Slack

​Discord

​Gmail

​Priority Emoji

​Message Format

​Standard Notification

​With Actions

​Usage Examples

​Slack Notifications

​Discord Notifications

​Email Notifications

​Multi-Environment Setup

​Advanced Features

​Custom Message Posting

​Entity ID Support

​Timeout Handling

​Troubleshooting

​Comparison with Other Notifiers

​Source Code

​Related

Build docs developers (and LLMs) love

Overview

Prerequisites

Configuration

Configuration Options

Platform-Specific Behavior

Slack

Discord

Gmail

Priority Emoji

Message Format

Standard Notification

With Actions

Usage Examples

Slack Notifications

Discord Notifications

Email Notifications

Multi-Environment Setup

Advanced Features

Custom Message Posting

Entity ID Support

Timeout Handling

Troubleshooting

Comparison with Other Notifiers

Source Code

Related