Automagik Omni
π The omnipresent messaging hub for AI agents. Connect to WhatsApp, Discord, Slack, and more through one unified API. Multi-tenant, production-ready, MCP-native.
Ask AI about Automagik Omni
Powered by Claude Β· Grounded in docs
I know everything about Automagik Omni. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
[!IMPORTANT] This repository has been superseded. Omni v2 β a complete TypeScript/Bun rewrite with event-driven architecture (NATS JetStream), a CLI-first design, and expanded channel support β is now the active project.
New home: automagik-dev/omni
This repo is archived and no longer maintained. Please star and use the new one!
The Omnipresent Messaging Hub for AI Agents
π One Integration, All Channels, Zero Headaches
Connect your AI agents to WhatsApp, Discord, Slack, and moreβall through one unified API
Multi-tenant, production-ready, and built for scale
What is Omni? β’ Features β’ Quick Start β’ Architecture β’ πΊοΈ Roadmap β’ Contributing
π What is Automagik Omni?
Automagik Omni is your AI agent's universal translator for the messaging world. Think of it as an intelligent postman who:
- πΊοΈ Knows every address (WhatsApp, Discord, Slack, Instagram...)
- π Speaks every language (different protocols and APIs)
- π¬ Delivers messages reliably, every time
- π₯ Remembers every conversation for analytics and debugging
π The Problem: Integration Hell
"Building messaging integrations is a developer's nightmare"
Every time you want your AI agent to work on a new platform, you face:
- π Learn a new API: Each platform has different docs, authentication, webhooks
- β»οΈ Duplicate code: The same logic written 5 different ways for 5 platforms
- π Maintenance nightmare: Updates break across different integrations
- β° Procrastination paralysis: "I'll add Slack support... later"
- π₯ Production fires: When WhatsApp breaks, everything breaks
The result? Months of development, fragile code, and agents that only work on 1-2 platforms.
β¨ The Omni Solution: Write Once, Connect Everywhere
graph LR
A[Your AI Agent] -->|One API| B[OMNI HUB]
B -->|Automatic| C[WhatsApp]
B -->|Automatic| D[Discord]
B -->|Automatic| E[Slack]
B -->|Automatic| F[Instagram]
B -->|Automatic| G[Teams]
B -->|Automatic| H[...and more]
style B fill:#00D9FF,stroke:#0099CC,stroke-width:3px,color:#000
What you get:
- βοΈ Write integration code once β works everywhere
- π Plug & Play: Connect new channels in minutes, not weeks
- ποΈ Production-grade: Multi-tenant, secure, scalable from day one
- π Full visibility: Every message traced from input to output
- π€ MCP-native: Control via Claude, Cursor, or any MCP tool
π The Vision: True Omnipresence
Imagine talking to the same AI agent across all your apps, with perfect context:
"Hey assistant, I saw a cool product on Instagramβcan you help me order it here on WhatsApp?"
The agent remembers who you are, what you were talking about, and responds naturallyβregardless of platform.
Today: Omni makes your agents present on multiple channels Tomorrow: True omnipresence with shared context across all platforms
π Key Features
β Production-Ready Today
- π Plug & Play Setup: From zero to sending messages in under 5 minutes
- π’ Multi-Tenant Architecture: Complete isolation between instances, teams, and clients
- π Comprehensive Tracing: Every message logged with performance metrics and payloads
- π Enterprise Security: API key authentication, request validation, CORS controls
- π€ MCP Server Built-in: Control from Claude Code, Cursor, or any MCP-compatible tool
- π Battle-Tested Scale: Handle 100+ instances and hundreds of concurrent conversations
- π Real-Time Streaming: SSE support for Automagik Hive agents
- π³ Deployment Flexible: Docker, PM2, systemdβdeploy however you prefer
π± Supported Channels
| Channel | Status | Features |
|---|---|---|
| β Production | Text, media, audio, stickers, reactions, presence, QR login via Evolution API | |
| Discord | β Production | Multi-server, text, attachments, voice infrastructure, bot + IPC architecture |
| Slack | π Q4 2025 | Full workspace integration with threads and reactions |
| WhatsApp Business | π Q4 2025 | Business API with Flows for structured interactions |
| Instagram Direct | π Q1 2026 | DMs, stories, and engagement |
| Telegram | π Q1 2026 | Bots, channels, and groups |
| Microsoft Teams | π Q1 2026 | Enterprise collaboration |
| LinkedIn Messages | π 2026-2027 | Professional networking |
| π 2026-2027 | China market access | |
| TikTok DMs | π 2026-2027 | Short-form social engagement |
| SMS Gateway | π 2026-2027 | Universal text messaging |
π§© Integrations
Works seamlessly with the Automagik ecosystem:
- Automagik Hive: Multi-agent orchestration with streaming SSE
- Automagik Spark: Scheduled messaging and workflows
- Automagik Tools: MCP tools for enhanced agent capabilities
- Any OpenAPI-Compatible Agent: Bring your own agent with standard HTTP APIs
π¦ Quick Start
Prerequisites
- Python 3.12+ (3.11+ supported)
- PostgreSQL (recommended) or SQLite (for development)
- Node.js 20+ (for Evolution API - WhatsApp integration)
- Discord Bot Token (optional, for Discord) - Create here
Note: Evolution API (WhatsApp) is included as a git submodule with SQLite support - no Docker required!
Installation
# 1. Clone with submodules (includes Evolution API for WhatsApp)
git clone --recurse-submodules https://github.com/namastexlabs/automagik-omni.git
cd automagik-omni
# 2. Run the setup script (installs everything)
./update-automagik-omni.sh
# This installs Python deps, Evolution API deps, and runs migrations
# 3. Configure your API keys
cp .env.example .env
nano .env # Set EVOLUTION_API_KEY and AUTOMAGIK_OMNI_API_KEY
# 4. Start all services with PM2
pm2 start ecosystem.config.js
# β
Done! Services running:
# - Omni API: http://localhost:8882
# - Evolution API (WhatsApp): http://localhost:18082
What gets installed:
- β Omni Backend - Multi-tenant messaging hub (Python/FastAPI)
- β Evolution API - WhatsApp integration with SQLite (no Docker!)
- β Health Checks - Ensures services start in correct order
- β Discord Manager - Multi-bot Discord integration (optional)
Your First Message in 60 Seconds
Quick Start with Defaults
Use this curl command to create your first instance with local Evolution API:
# Create instance with local Evolution API (started via PM2)
curl -X POST http://localhost:8882/api/v1/instances \
-H "x-api-key: YOUR_OMNI_API_KEY_HERE" \
-H "Content-Type: application/json" \
-d '{
"name": "my-first-bot",
"channel_type": "whatsapp",
"evolution_url": "http://localhost:18082",
"evolution_key": "YOUR_EVOLUTION_API_KEY_HERE",
"agent_api_url": "http://localhost:8886",
"agent_api_key": "YOUR_AGENT_API_KEY_HERE",
"default_agent": "template-agent"
}'
Replace the placeholders:
YOUR_OMNI_API_KEY_HEREβ Value fromAUTOMAGIK_OMNI_API_KEYin your.envYOUR_EVOLUTION_API_KEY_HEREβ Value fromEVOLUTION_API_KEYin your.envYOUR_AGENT_API_KEY_HEREβ Your AI agent's API key (e.g., Automagik Hive)
Default ports:
- Evolution API (WhatsApp):
localhost:18082 - Omni API:
localhost:8882 - Automagik Hive (optional):
localhost:8886
Complete Example
# Check health
curl http://localhost:8882/health
# {"status": "healthy"}
# Get QR code to connect WhatsApp
curl http://localhost:8882/api/v1/instances/my-first-bot/qr \
-H "x-api-key: YOUR_OMNI_API_KEY_HERE"
# Scan with WhatsApp β Connected!
# Send a test message
curl -X POST http://localhost:8882/api/v1/instances/my-first-bot/send-text \
-H "x-api-key: YOUR_OMNI_API_KEY_HERE" \
-H "Content-Type: application/json" \
-d '{
"phone": "+1234567890",
"message": "π Hello from Automagik Omni!"
}'
That's it! Your agent is now live and responding on WhatsApp.
Security Note: Always use strong, unique API keys in production. Never commit real keys to git.
ποΈ Architecture
How Omni Works
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β OMNI HUB β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β β
β ββββββββββββββββ βββββββββββββββββ ββββββββββββ β
β β WhatsApp βββββββΆβ Instance βββββββΆβ AI β β
β β Webhook β β Manager β β Agent β β
β ββββββββββββββββ βββββββββββββββββ ββββββββββββ β
β β β
β ββββββββββββββββ β β
β β Discord βββββββββββββββ€ β
β β Bot + IPC β β β
β ββββββββββββββββ β β
β βββββββΌβββββββ β
β ββββββββββββββββ β Message β ββββββββββββ β
β β Slack βββββββΆβ Router βββββββΆβ Trace β β
β β (Soon) β β & Handler β β Store β β
β ββββββββββββββββ βββββββββββββββ ββββββββββββ β
β β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Core Components
- Instance Manager: Multi-tenant instance management with complete isolation
- Channel Handler Factory: Pluggable architecture for platform-specific logic
- Message Router: Validates, enriches, and routes messages to appropriate agents
- Trace System: Complete message lifecycle tracking with performance metrics
- MCP Server: Remote control interface for AI coding agents
Message Flow
User sends message β Platform webhook β Omni validates
β
Access control check
β
Route to AI agent
β
Agent processes (with streaming support)
β
Format for platform
β
Send via channel
β
Store trace for analytics
π€ MCP: Control from Anywhere
Automagik Omni includes a Model Context Protocol (MCP) server, enabling AI agents to programmatically manage messaging instances and send messages.
Available MCP Tools
| Tool | Description | Operations |
|---|---|---|
manage_instances | Instance CRUD operations | list, get, create, update, delete, status, qr, restart, logout |
send_message | Send messages to any channel | text, media, audio, sticker, contact, reaction |
manage_traces | Message history and analytics | list, get, analytics, cleanup |
manage_profiles | User profile management | fetch, update_picture |
Quick MCP Setup
π€ Claude Code Configuration
Add to your Claude Code MCP servers configuration:
{
"mcpServers": {
"omni": {
"command": "uvx",
"args": ["--from", "automagik-omni", "mcp-server-omni"],
"env": {
"OMNI_URL": "http://localhost:8000",
"OMNI_API_KEY": "your-api-key-here"
}
}
}
}
Usage:
"List all my messaging instances"
"Send a WhatsApp message to +1234567890: Hello!"
"Show me message analytics for the last 24 hours"
π― Cursor Configuration
Add to Cursor's MCP settings:
{
"mcp.servers": {
"omni": {
"command": "uvx",
"args": ["--from", "automagik-omni", "mcp-server-omni"],
"env": {
"OMNI_URL": "http://localhost:8000",
"OMNI_API_KEY": "your-api-key-here"
}
}
}
}
π VSCode + Cline Configuration
For the Cline extension:
{
"cline.mcpServers": [
{
"name": "omni",
"command": "uvx",
"args": ["--from", "automagik-omni", "mcp-server-omni"],
"env": {
"OMNI_URL": "http://localhost:8000",
"OMNI_API_KEY": "your-api-key-here"
}
}
]
}
π§ Generic MCP Configuration
For any MCP-compatible tool:
{
"command": "uvx",
"args": ["--from", "automagik-omni", "mcp-server-omni"],
"env": {
"OMNI_URL": "http://localhost:8000",
"OMNI_API_KEY": "your-api-key-here"
}
}
MCP Usage Examples
# From Claude Code or any MCP client
"Create a new WhatsApp instance named 'support-bot'"
β Uses manage_instances to create and configure
"Send a message to customer +5511999999999: Your order has shipped!"
β Uses send_message with proper formatting
"Show me all failed messages from yesterday"
β Uses manage_traces with filters
"Get QR code for my WhatsApp instance 'sales-team'"
β Uses manage_instances(operation="qr")
π οΈ API Reference
Core Endpoints
Instance Management
# List all instances
GET /api/v1/instances
Headers: x-api-key: your-key
# Create new instance
POST /api/v1/instances
{
"name": "my-bot",
"channel_type": "whatsapp|discord",
"evolution_url": "https://...", # WhatsApp only
"evolution_api_key": "...", # WhatsApp only
"discord_token": "...", # Discord only
"agent_url": "https://your-agent.com/chat",
"agent_api_key": "optional"
}
# Get instance details
GET /api/v1/instances/{name}
# Update instance
PATCH /api/v1/instances/{name}
{
"agent_url": "https://new-endpoint.com"
}
# Delete instance
DELETE /api/v1/instances/{name}
Channel Operations
# Get WhatsApp QR Code
GET /api/v1/instances/{name}/qr
# Check connection status
GET /api/v1/instances/{name}/status
# Restart connection
POST /api/v1/instances/{name}/restart
# Logout/disconnect
POST /api/v1/instances/{name}/logout
Messaging
# Send text message
POST /api/v1/instances/{name}/send-text
{
"phone": "+1234567890",
"message": "Hello!",
"quoted_message_id": "optional"
}
# Send media (image, video, document)
POST /api/v1/instances/{name}/send-media
{
"phone": "+1234567890",
"media_url": "https://example.com/image.jpg",
"media_type": "image|video|document",
"caption": "Optional caption"
}
# Send audio/voice note
POST /api/v1/instances/{name}/send-audio
{
"phone": "+1234567890",
"audio_url": "https://example.com/audio.mp3"
}
# Send reaction
POST /api/v1/instances/{name}/send-reaction
{
"phone": "+1234567890",
"message_id": "message-to-react-to",
"emoji": "π"
}
Traces & Analytics
# List message traces
GET /api/v1/traces?instance_name=my-bot&limit=50
# Get specific trace
GET /api/v1/traces/{trace_id}
# Analytics summary
GET /api/v1/traces/analytics/summary?start_date=2025-01-01
# Cleanup old traces
POST /api/v1/traces/cleanup
{
"days_old": 30,
"dry_run": false
}
Authentication
All API requests require the x-api-key header:
curl -H "x-api-key: your-secret-key" \
http://localhost:8000/api/v1/instances
Set your API key in .env:
OMNI_API_KEY=your-super-secret-key-here
π― Agent Integration
Automagik Hive (Recommended)
Omni has first-class support for Automagik Hive with streaming Server-Sent Events:
# Hive agent responds with SSE streaming
# Omni automatically:
# 1. Buffers the stream
# 2. Formats for the target channel
# 3. Sends when complete
# 4. Handles errors gracefully
# Just point agent_url to your Hive endpoint!
Custom HTTP Agent
Any agent that accepts HTTP POST with JSON:
POST https://your-agent.com/chat
Content-Type: application/json
{
"message": "User's message",
"user_id": "platform:user_id",
"platform": "whatsapp|discord",
"context": {
"phone": "+1234567890",
"instance_name": "my-bot"
}
}
Response:
{
"response": "Agent's reply message"
}
OpenAPI-Compatible Agent
If your agent has an OpenAPI spec, it just works:
# Create instance pointing to any OpenAPI endpoint
curl -X POST http://localhost:8000/api/v1/instances \
-H "x-api-key: your-key" \
-d '{
"agent_url": "https://api.yourservice.com/v1/chat",
"agent_api_key": "service-api-key"
}'
πΊοΈ Roadmap
Q4 2025 - Foundation Strengthening
- π― Robustness & Scale: Performance beyond Evolution API limitations
- π Access Control: Whitelist/blacklist for user management
- πΌ WhatsApp Business API: Flows for structured interactions
- π¬ Slack Integration: Full workspace support with threads
- π Fallback System: Multiple WhatsApp engines for redundancy
Q1-Q2 2026 - Channel Expansion
- π± Instagram Direct: DMs, stories, engagement
- βοΈ Telegram: Bots, channels, groups
- π Microsoft Teams: Enterprise collaboration
- π Meta Messenger: Facebook messaging
- π Unified User Management: Link users across platforms
- π§ True Omnipresence: Shared context across all channels
2026-2027 - Global Scale
- πΌ LinkedIn Messages: Professional networking
- π¨π³ WeChat: China market access
- π΅ TikTok DMs: Short-form social engagement
- π± SMS Gateway: Universal text messaging
- π Open Architecture: Plugin system for any messaging platform
- π Enterprise Features: SSO, audit logs, compliance tools
π Development
Local Development
# Start with hot reload
make dev
# Run tests
make test
# View logs
make logs
# Check code quality
make lint
make format
# Database operations
make migrate # Run migrations
make db-reset # Reset database (caution!)
make db-shell # Open database shell
Docker Deployment
# Build and run
docker-compose up -d
# View logs
docker-compose logs -f omni-api
# Restart services
docker-compose restart
# Stop everything
docker-compose down
Production Deployment with PM2
# Install PM2
npm install -g pm2
# Start all services
pm2 start ecosystem.config.js
# Monitor
pm2 monit
# View logs
pm2 logs omni-api
# Restart
pm2 restart all
# Stop
pm2 stop all
Environment Variables
Key configuration options (see .env.example for complete list):
# Omni API Configuration
AUTOMAGIK_OMNI_API_HOST=0.0.0.0
AUTOMAGIK_OMNI_API_PORT=8882
AUTOMAGIK_OMNI_API_KEY=CHANGE-THIS-TO-SECURE-KEY
# Database (SQLite for development)
AUTOMAGIK_OMNI_SQLITE_DATABASE_PATH=./data/automagik-omni.db
# Or PostgreSQL for production:
# AUTOMAGIK_OMNI_DATABASE_URL=postgresql://user:pass@localhost:5432/automagik_omni
# Evolution API (WhatsApp - runs locally via PM2)
EVOLUTION_API_PATH=resources/evolution-api
EVOLUTION_API_URL=http://localhost:18082
EVOLUTION_API_PORT=18082
EVOLUTION_API_KEY=CHANGE-THIS-TO-SECURE-KEY
EVOLUTION_LOG_LEVEL=ERROR,WARN
# Discord (optional)
DISCORD_TOKEN=YOUR-DISCORD-BOT-TOKEN-HERE
# Logging
LOG_LEVEL=INFO # DEBUG, INFO, WARNING, ERROR, CRITICAL
Important: Generate strong, unique API keys for production. Never use default values!
π€ Contributing
We love contributions! Here's how to get started:
Quick Contribution Guide
- Fork the repository
- Clone your fork locally
- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes
- Test thoroughly:
make test - Commit with conventional commits:
feat: add slack integration - Push to your fork:
git push origin feature/amazing-feature - Open a Pull Request with clear description
Development Setup
# Clone your fork
git clone https://github.com/YOUR_USERNAME/automagik-omni.git
cd automagik-omni
# Install dependencies with UV (recommended)
make install
# Create .env file
cp .env.example .env
# Run migrations
make migrate
# Start development server
make dev
# Run tests before committing
make test
make lint
Contribution Guidelines
- Follow existing code style (use
make format) - Write tests for new features
- Update documentation
- Use conventional commits (
feat:,fix:,docs:,refactor:) - Keep PRs focused on a single feature/fix
See CONTRIBUTING.md for detailed guidelines.
π Acknowledgments
Special thanks to:
- Evolution API Team: For excellent WhatsApp infrastructure
- Discord.py Community: For the powerful bot framework
- Automagik Community: Early adopters and contributors
- FastAPI Team: For the amazing Python web framework
π License
MIT License - see LICENSE file for details.
π Links
- GitHub: github.com/namastexlabs/automagik-omni
- Discord: discord.gg/xcW8c7fF3R
- Twitter: @namastexlabs
- DeepWiki Docs: deepwiki.com/namastexlabs/automagik-omni
π Connect your AI to every messaging platform with one integration
The omnipresent hub that just worksβ’
Star us on GitHub β’
Join our Discord
Made with β€οΈ by Namastex Labs
AI that elevates human potential, not replaces it
