Skip to main content
POST
/
api
/
v1
/
messages

​
Send a Message

Send text messages, media, reactions, and more across any connected platform.
​
instance
string
required
The name of the instance to send from
​
to
string
required
Recipient phone number (with country code) or channel/user ID
​
message
string
Text message content (required for text messages)
​
mediaUrl
string
URL of media file for image/video/document messages
​
mediaType
string
Type of media: image, video, audio, document
​
caption
string
Caption for media messages
​
replyTo
string
Message ID to reply to (creates a quoted reply)

​
Examples

curl -X POST http://localhost:8000/api/v1/messages \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "instance": "my-whatsapp",
    "to": "+1234567890",
    "message": "Hello from Omni! 👋"
  }'

​
Response

200 Success
{
  "success": true,
  "messageId": "3EB0ABC123...",
  "instance": "my-whatsapp",
  "to": "+1234567890",
  "timestamp": "2025-10-31T12:00:00Z",
  "status": "sent"
}
400 Bad Request
{
  "error": {
    "code": "INVALID_PHONE_NUMBER",
    "message": "Phone number must include country code",
    "details": {
      "provided": "1234567890",
      "expected": "+1234567890"
    }
  }
}
404 Not Found
{
  "error": {
    "code": "INSTANCE_NOT_FOUND",
    "message": "Instance 'my-whatsapp' does not exist"
  }
}
503 Service Unavailable
{
  "error": {
    "code": "INSTANCE_NOT_CONNECTED",
    "message": "Instance 'my-whatsapp' is not connected"
  }
}

​
Message Types

  • Text Message
  • Image
  • Video
  • Document
  • Reply to Message
  • Reaction
curl -X POST http://localhost:8000/api/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "instance": "my-whatsapp",
    "to": "+1234567890",
    "message": "Simple text message"
  }'

​
Platform-Specific Examples

# WhatsApp uses phone numbers
curl -X POST http://localhost:8000/api/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "instance": "my-whatsapp",
    "to": "+1234567890",
    "message": "Hello on WhatsApp!"
  }'
Phone number format:
  • ✅ +1234567890 (with country code)
  • ✅ +55 11 98765-4321 (formatted)
  • ❌ 1234567890 (missing +)
  • ❌ (123) 456-7890 (invalid format)
# Discord uses channel IDs
curl -X POST http://localhost:8000/api/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "instance": "my-discord",
    "to": "1234567890123456789",
    "message": "Hello on Discord!"
  }'
Channel ID format:
  • ✅ 1234567890123456789 (numeric ID)
  • ✅ #general (channel name, if configured)
# Slack uses channel IDs or names
curl -X POST http://localhost:8000/api/v1/messages \
  -H "Content-Type: application/json" \
  -d '{
    "instance": "my-slack",
    "to": "#engineering",
    "message": "Hello on Slack!"
  }'
Channel format:
  • ✅ #general (channel name)
  • ✅ C1234567890 (channel ID)
  • ✅ @username (direct message)
  • ✅ U1234567890 (user ID)

​
Testing

​
Interactive Playground

Try the API live using the built-in Swagger docs: 
# Start Omni
omni serve

# Open Swagger UI
open http://localhost:8000/docs
Navigate to POST /api/v1/messages and click “Try it out”!

​
Test with Postman

1

Import Collection

Download our Postman collection:
curl -O https://raw.githubusercontent.com/namastexlabs/automagik-omni/main/docs/postman-collection.json
2

Configure Environment

Set these variables:
  • BASE_URL: http://localhost:8000
  • API_KEY: Your API key
  • INSTANCE: Your instance name
3

Send Test Message

Select “Send Text Message” and hit Send!

​
Rate Limits

Message sending is rate-limited to prevent spam and ensure fair usage.
Instance TypeLimitWindow
WhatsApp60 messages1 minute
Discord120 messages1 minute
Slack100 messages1 minute
Rate limit headers in response: 
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1635724800

​
Best Practices

# ✅ Good
"to": "+1234567890"

# ❌ Bad
"to": "1234567890"

# Check if instance is connected
curl http://localhost:8000/api/v1/instances/my-whatsapp/status

# Then send message
curl -X POST http://localhost:8000/api/v1/messages ...

try:
    response = send_message(...)
    if response.status_code == 503:
        # Instance disconnected, reconnect
        reconnect_instance()
    elif response.status_code == 429:
        # Rate limited, wait and retry
        time.sleep(60)
except Exception as e:
    log_error(e)
Every message gets a unique ID for tracking:
# Get message details
curl http://localhost:8000/api/v1/traces/{messageId}

​
Next Steps

Manage Instances

Create and configure messaging instances

Message Traces

Track and debug your messages

Quick Start

Complete Omni tutorial

API Overview

Back to API overview