Quick Start

Send Your First Omnichannel Message in 5 Minutes

This guide will walk you through setting up Omni, connecting to WhatsApp, and sending your first message through the unified API.

Step 1: Start Evolution API

Omni uses Evolution API for WhatsApp. Start it with Docker:

# Pull and run Evolution API
docker run -d \
  --name evolution-api \
  -p 8080:8080 \
  atendai/evolution-api

Wait a few seconds for it to start, then verify:

curl http://localhost:8080/health
# Should return: {"status":"ok"}

Step 2: Initialize Omni

# Initialize Omni workspace
omni init

# This creates:
# - .omni/ directory
# - config.json
# - .env

Step 3: Configure Omni

Edit config.json:

{
  "evolutionApi": {
    "baseUrl": "http://localhost:8080",
    "apiKey": "B6D711FCDE4D4FD5936544120E713976"
  },
  "mcp": {
    "enabled": true,
    "port": 3000
  }
}

The default Evolution API key is B6D711FCDE4D4FD5936544120E713976. Change this in production!

Step 4: Start Omni

# Start Omni server
omni serve

# You should see:
# 📱 Omni v1.0.0
# ✓ Evolution API connected
# ✓ MCP server started
# ✓ Ready to handle messages

Step 5: Create a WhatsApp Instance

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

# Get QR code to connect
omni instance qr --name my-whatsapp

A QR code will appear in your terminal. Scan it with WhatsApp on your phone:

Open WhatsApp
Go to Settings → Linked Devices
Tap “Link a Device”
Scan the QR code

Step 6: Send Your First Message

Once connected, send a message:

# Send text message
omni send \
  --instance my-whatsapp \
  --to "+1234567890" \
  --message "Hello from Omni! 👋"

# You should see:
# ✓ Message sent successfully
# Message ID: 3EB0ABC123...

Congratulations! You just sent your first omnichannel message! 🎉

Real-World Example: Multi-Channel Notification

Send the same message across multiple platforms:

Setup Instances

# WhatsApp
omni instance create --name whatsapp-prod --platform whatsapp

# Discord (if you have a bot)
omni instance create --name discord-bot --platform discord \
  --token "your-discord-token"

# Slack (if you have an app)
omni instance create --name slack-workspace --platform slack \
  --token "xoxb-your-slack-token"

Send Across All Channels

# Same API, different platforms!

# WhatsApp
omni send --instance whatsapp-prod \
  --to "+1234567890" \
  --message "System update completed ✅"

# Discord
omni send --instance discord-bot \
  --channel "general" \
  --message "System update completed ✅"

# Slack
omni send --instance slack-workspace \
  --channel "#engineering" \
  --message "System update completed ✅"

Message Types

Omni supports rich message types:

Text
Media (Image/Video)
Document
Reaction

omni send \
  --instance my-whatsapp \
  --to "+1234567890" \
  --message "Simple text message"

Using with AI Agents (MCP)

Connect Omni to Claude or any MCP-compatible agent: 1. Configure Claude Desktop Edit claude_desktop_config.json:

{
  "mcpServers": {
    "omni": {
      "command": "omni",
      "args": ["serve", "--mcp"]
    }
  }
}

2. Now Claude can send messages!

You: "Send a WhatsApp message to +1234567890 saying the report is ready"

Claude: I'll send that message via Omni.
[Uses omni_send_message tool]

✓ Message sent successfully via WhatsApp!

Multi-Tenant Setup

Manage multiple clients or teams:

# Create instances for different clients
omni instance create --name client-a-whatsapp --platform whatsapp
omni instance create --name client-b-whatsapp --platform whatsapp

# Set default instance for easier commands
omni config set default-instance client-a-whatsapp

# Now omni send uses client-a by default
omni send --to "+1234567890" --message "Hello!"

# Or specify instance explicitly
omni send --instance client-b-whatsapp --to "+0987654321" --message "Hi!"

Message Tracing

Track and debug all messages:

# View recent messages
omni traces list --limit 10

# Filter by instance
omni traces list --instance my-whatsapp

# Filter by phone number
omni traces by-phone "+1234567890"

# Get detailed trace
omni traces get <trace-id>

Common Use Cases

Customer Support Bot

# Receive message → AI processes → Send reply
omni webhook setup --url https://yourapp.com/webhook
# Your app receives messages, processes with AI,
# sends responses via omni send

Notification System

# Send alerts across all platforms
omni send --instance whatsapp \
  --to "+list" --message "Alert: Server down"
omni send --instance discord \
  --channel "alerts" --message "Alert: Server down"

Marketing Campaigns

# Broadcast to subscriber list
omni broadcast \
  --instance my-whatsapp \
  --list "subscribers.csv" \
  --message "New product launch! 🚀"

Order Updates

# E-commerce order notifications
omni send \
  --instance shop-whatsapp \
  --to "$CUSTOMER_PHONE" \
  --message "Your order #$ORDER_ID has shipped!"

Pro Tips

Keep Instances Organized

Use clear naming conventions:

# Good
omni instance create --name prod-customer-support
omni instance create --name staging-notifications
omni instance create --name team-internal

# Not ideal
omni instance create --name instance1
omni instance create --name test123

Use Environment Variables

# .env
OMNI_DEFAULT_INSTANCE=prod-customer-support
OMNI_EVOLUTION_API_KEY=your-key

# Now commands use defaults
omni send --to "+123" --message "Hi!"

Monitor Instance Health

# Check connection status regularly
omni instance status --all

# Reconnect if needed
omni instance restart --name my-whatsapp

Next Steps

Webhook Integration

Learn to:

Receive incoming messages
Process with AI
Send automated replies

Advanced Messaging

Explore:

Group chats
Media handling
Message templates
Bulk operations

Analytics & Monitoring

Track:

Message delivery rates
Response times
Usage patterns
Error rates

Production Deployment

Deploy at scale:

Load balancing
High availability
Backup strategies

Troubleshooting

QR code won't scan

Try these solutions:

# Get web-based QR
omni instance qr --name my-whatsapp --web

# Or regenerate
omni instance disconnect --name my-whatsapp
omni instance qr --name my-whatsapp

Messages not sending

Check instance status:

omni instance status --name my-whatsapp
# Should show: connected

# If disconnected, reconnect:
omni instance restart --name my-whatsapp

Evolution API errors

Verify Evolution API is running:

curl http://localhost:8080/health
docker logs evolution-api

# Restart if needed
docker restart evolution-api

Congratulations! 🎉 You’ve sent your first omnichannel message with Omni. You can now reach users on any platform!

Join the Community

Share your integrations and get help from the community

Getting Started

API Reference

Send Your First Omnichannel Message in 5 Minutes

Step 1: Start Evolution API

Step 2: Initialize Omni

Step 3: Configure Omni

Step 4: Start Omni

Step 5: Create a WhatsApp Instance

Step 6: Send Your First Message

Real-World Example: Multi-Channel Notification

Message Types

Using with AI Agents (MCP)

Multi-Tenant Setup

Message Tracing

Common Use Cases

Customer Support Bot

Notification System

Marketing Campaigns

Order Updates

Pro Tips

Next Steps

Webhook Integration

Advanced Messaging

Analytics & Monitoring

Production Deployment

Troubleshooting

Join the Community

Getting Started

API Reference

​Send Your First Omnichannel Message in 5 Minutes

​Step 1: Start Evolution API

​Step 2: Initialize Omni

​Step 3: Configure Omni

​Step 4: Start Omni

​Step 5: Create a WhatsApp Instance

​Step 6: Send Your First Message

​Real-World Example: Multi-Channel Notification

​Message Types

​Using with AI Agents (MCP)

​Multi-Tenant Setup

​Message Tracing

​Common Use Cases

Customer Support Bot

Notification System

Marketing Campaigns

Order Updates

​Pro Tips

​Next Steps

Webhook Integration

Advanced Messaging

Analytics & Monitoring

Production Deployment

​Troubleshooting

Join the Community

Send Your First Omnichannel Message in 5 Minutes

Step 1: Start Evolution API

Step 2: Initialize Omni

Step 3: Configure Omni

Step 4: Start Omni

Step 5: Create a WhatsApp Instance

Step 6: Send Your First Message

Real-World Example: Multi-Channel Notification

Message Types

Using with AI Agents (MCP)

Multi-Tenant Setup

Message Tracing

Common Use Cases

Pro Tips

Next Steps

Troubleshooting