Skip to main content

​
Prerequisites

Before installing Omni, make sure you have: 
# Check your Python version
python --version

# Should output Python 3.10.0 or higher
If you need to install or upgrade Python:
  • macOS: brew install python@3.11
  • Ubuntu/Debian: sudo apt install python3.11 python3-pip
  • Windows: Download from python.org
Omni uses Evolution API for WhatsApp integration:
# Pull Evolution API Docker image
docker pull atendai/evolution-api

# Run Evolution API
docker run -p 8080:8080 atendai/evolution-api
Or use Docker Compose (recommended).
Depending on which platforms you want to integrate:
  • Discord: Bot token from Discord Developer Portal
  • Slack: App token from Slack API
  • WhatsApp: Evolution API instance

​
Installation Methods

​
Configuration

After installation, initialize Omni: 
# Initialize Omni workspace
omni init

# This creates:
# - .omni/ directory
# - config.json (Omni configuration)
# - .env (API keys and secrets)
Configure Omni in config.json: 
{
  "evolutionApi": {
    "baseUrl": "http://localhost:8080",
    "apiKey": "your-evolution-api-key"
  },
  "mcp": {
    "enabled": true,
    "port": 3000
  },
  "database": {
    "type": "sqlite",
    "path": ".omni/omni.db"
  },
  "tracing": {
    "enabled": true,
    "retentionDays": 30
  }
}
Set up platform credentials in .env: 
# Evolution API
EVOLUTION_API_KEY=your-evolution-api-key
EVOLUTION_API_URL=http://localhost:8080

# Discord (if using)
DISCORD_BOT_TOKEN=your-discord-bot-token

# Slack (if using)
SLACK_BOT_TOKEN=xoxb-your-slack-token
Security: Never commit .env to version control! Add it to .gitignore.

​
Start Omni

Start the Omni server: 
# Start Omni server
omni serve

# Or with custom port
omni serve --port 3001

# With MCP server enabled
omni serve --mcp
You should see output like: 
📱 Omni v1.0.0
✓ Database initialized
✓ Evolution API connected
✓ MCP server started on port 3000
✓ Omni server listening on http://localhost:8000

Ready to handle omnichannel messages!

​
Create Your First Instance

# Create a WhatsApp instance
omni instance create --name my-whatsapp --platform whatsapp

# Get QR code for connection
omni instance qr --name my-whatsapp

# Check instance status
omni instance status --name my-whatsapp

​
Verify Installation

Test that everything is working: 
# Check version
omni --version

# List instances
omni instance list

# Check MCP server
omni mcp status

# Test message sending (after instance connected)
omni send --instance my-whatsapp --to +1234567890 --message "Hello from Omni!"

​
Troubleshooting

Make sure Evolution API is running:
# Check if Evolution API is up
curl http://localhost:8080/health

# Restart Evolution API
docker restart evolution-api

# Check Evolution API logs
docker logs evolution-api
Make sure you’re using a terminal that supports images, or use web interface:
# Get QR code as URL
omni instance qr --name my-whatsapp --web

# This opens in your browser
Check database permissions and storage:
# Check database file
ls -la .omni/omni.db

# Reset database (WARNING: deletes all traces)
omni db reset

# Check trace settings
omni config get tracing
Change the MCP server port:
# Edit config.json or use command line
omni serve --mcp-port 3001

​
Next Steps

Quick Start

Send your first omnichannel message

Introduction

Learn more about Omni