API Documentation

🔑 Your API Key & Config

Everything below is pre-filled with your real values. Copy and use directly.

👥 Your Groups

Use these Group IDs in API calls — they never change, even if you rename the group.

🔐 Authentication

Pass your API key as a header on every request.

Request Format

All POST endpoints accept either format — use whichever your tool supports:

📱 List Instances

Copycurl -X GET https://sevenoways.app/api/instances \
  -H "x-api-key: YOUR_API_KEY"

➕ Create Instance

Copycurl -X POST https://sevenoways.app/api/instances \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instanceId":"number2","label":"Second Line"}'

🗑️ Delete Instance

👥 List Groups

Copycurl https://sevenoways.app/api/instances/INSTANCE_ID/groups \
  -H "x-api-key: YOUR_API_KEY"

💬 Send Text to Groups

Copycurl -X POST https://sevenoways.app/api/send \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "INSTANCE_ID",
    "groupIds": ["GROUP_ID_HERE"],
    "message": "Hello everyone! 👋"
  }'

Copycurl -X POST https://sevenoways.app/api/send \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "INSTANCE_ID",
    "groups": ["Group Name Here"],
    "message": "Hello everyone! 👋"
  }'

Copy-d '{
  "instanceId": "INSTANCE_ID",
  "sendAll": true,
  "message": "Broadcast to everyone!"
}'

🖼️ Send Image to Groups

Copy-d '{
  "instanceId": "INSTANCE_ID",
  "groupIds": ["GROUP_ID_HERE"],
  "imageUrl": "https://example.com/banner.jpg",
  "caption": "Check this out!"
}'

📎 Send Document to Groups

Copy-d '{
  "instanceId": "INSTANCE_ID",
  "groupIds": ["GROUP_ID_HERE"],
  "fileUrl": "https://example.com/report.pdf",
  "filename": "Monthly Report.pdf",
  "mimetype": "application/pdf"
}'

📞 Send Text to Number

Copycurl -X POST https://sevenoways.app/api/send-number \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "INSTANCE_ID",
    "phone": "971501234567",
    "message": "Hello! Your order is ready 🎉"
  }'

🖼️ Send Image to Number

Copy-d '{
  "instanceId": "INSTANCE_ID",
  "phone": "971501234567",
  "imageUrl": "https://example.com/invoice.png",
  "caption": "Your invoice"
}'

📎 Send Document to Number

Copy-d '{
  "instanceId": "INSTANCE_ID",
  "phone": "971501234567",
  "fileUrl": "https://example.com/contract.pdf",
  "filename": "Contract.pdf"
}'

🌐 WhatsApp Communities

Send messages to WhatsApp Communities your number is connected to. Communities are automatically discovered from your connected instance — no setup required.

💬 Send Text to Community

Copycurl -X POST https://sevenoways.app/api/send-to-community \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "INSTANCE_ID",
    "communityId": "120363XXXXXXXX@newsletter",
    "message": "📣 Community update: New features released!"
  }'

Copy{
  "success": true,
  "queued": true,
  "queueId": 142
}

🖼️ Send Image to Community

Copycurl -X POST https://sevenoways.app/api/send-image-to-community \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "INSTANCE_ID",
    "communityId": "120363XXXXXXXX@newsletter",
    "imageUrl": "https://example.com/banner.jpg",
    "caption": "Check out our new product! 🚀"
  }'

📎 Send Document to Community

Copycurl -X POST https://sevenoways.app/api/send-document-to-community \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "INSTANCE_ID",
    "communityId": "120363XXXXXXXX@newsletter",
    "fileUrl": "https://example.com/newsletter.pdf",
    "filename": "Community-Update.pdf"
  }'

📢 WhatsApp Channels

Send broadcast messages to WhatsApp Channels (Newsletters). Unlike communities, channels are one-way broadcasts — only admins/owners can post, followers only receive.

🗂️ Manage Saved Channels

Copycurl -X GET https://sevenoways.app/api/channels \
  -H "x-api-key: YOUR_API_KEY"

Copy{
  "success": true,
  "channels": [
    {
      "id": "ch_abc123",
      "channelJid": "120363XXXXXXXX@newsletter",
      "name": "My Brand Updates",
      "description": "Latest news from our brand",
      "subscribers": 4820,
      "isAdmin": true,
      "inviteLink": "https://whatsapp.com/channel/XXXXXXX",
      "instanceId": "inst_abc123"
    }
  ]
}

Copycurl -X POST https://sevenoways.app/api/channels \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "INSTANCE_ID",
    "inviteLink": "https://whatsapp.com/channel/XXXXXXXXXXXXXXXX"
  }'

Copycurl -X DELETE https://sevenoways.app/api/channels/ch_abc123 \
  -H "x-api-key: YOUR_API_KEY"

💬 Send Text to Channel

Copycurl -X POST https://sevenoways.app/api/send-to-channel \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "INSTANCE_ID",
    "channelJid": "120363XXXXXXXX@newsletter",
    "message": "📢 Big announcement coming tomorrow — stay tuned!"
  }'

Copy{
  "success": true,
  "queued": true,
  "queueId": 158
}

🖼️ Send Image to Channel

Copycurl -X POST https://sevenoways.app/api/send-image-to-channel \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "INSTANCE_ID",
    "channelJid": "120363XXXXXXXX@newsletter",
    "imageUrl": "https://example.com/promo.jpg",
    "caption": "Our summer sale starts today! 🌞"
  }'

📎 Send Document to Channel

Copycurl -X POST https://sevenoways.app/api/send-document-to-channel \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "INSTANCE_ID",
    "channelJid": "120363XXXXXXXX@newsletter",
    "fileUrl": "https://example.com/monthly-report.pdf",
    "filename": "August-Report.pdf"
  }'

⏰ Schedules

Copy-d '{
  "instanceId": "INSTANCE_ID",
  "label": "Daily Morning Update",
  "cronExpr": "0 9 * * *",
  "timezone": "Asia/Dubai",
  "groupIds": ["GROUP_ID_HERE"],
  "message": "Good morning team! ☀️"
}'

🔗 n8n Integration

Connect this API to n8n using the HTTP Request node. Set it up once as a credential and reuse it everywhere.

Copy{
  "instanceId": "INSTANCE_ID",
  "groupIds": ["GROUP_ID_HERE"],
  "message": "{{ $json.message }}"
}

📋 n8n Workflow Examples

New form submission → notify group

Copy{
  "instanceId": "INSTANCE_ID",
  "groupIds": ["GROUP_ID_HERE"],
  "message": "📋 New lead: {{ $json.name }} — {{ $json.email }}"
}

Send order confirmation to customer

Copy{
  "instanceId": "INSTANCE_ID",
  "phone": "{{ $json.phone.replace(/[^0-9]/g, '') }}",
  "message": "Hi {{ $json.name }}! Order #{{ $json.orderId }} confirmed ✅"
}

Daily report to all groups

Copy{
  "instanceId": "INSTANCE_ID",
  "sendAll": true,
  "message": "📊 Daily report:\nSales: {{ $json.sales }}\nLeads: {{ $json.leads }}"
}

Google Sheet row added → alert group

Copy{
  "instanceId": "INSTANCE_ID",
  "groupIds": ["GROUP_ID_HERE"],
  "message": "📋 New entry:\n{{ $json.Name }} — AED {{ $json.Amount }}"
}

Send invoice PDF to customer

Copy{
  "instanceId": "INSTANCE_ID",
  "phone": "{{ $json.phone }}",
  "fileUrl": "{{ $json.invoiceUrl }}",
  "filename": "Invoice-{{ $json.invoiceNo }}.pdf",
  "mimetype": "application/pdf"
}

🔄 Pabbly Connect Integration

Use the HTTP Request action in any Pabbly workflow to send WhatsApp messages.

Pabbly — Send to WhatsApp Group

To send to groups instead of a number, use https://sevenoways.app/api/send with:

⚡ Ottokit Integration

Use Ottokit's Webhook / HTTP Request module to connect any trigger to Sevenoways Relay.

🚦 Rate Limits

All send endpoints are rate-limited per API key. Exceeding limits returns HTTP 429.

When a limit is reached you'll receive: { "success": false, "error": "Send rate limit exceeded — max 60 requests/minute per API key." }

🔗 Webhooks

Webhooks deliver real-time event notifications to your endpoint via HTTP POST. Configure them in your dashboard.

Available events

Signature verification (HMAC-SHA256)

Each webhook request includes an X-Webhook-Signature header. Verify it to ensure requests come from Sevenoways.

Copy// Node.js
const crypto = require('crypto')
const sig = req.headers['x-webhook-signature']
const expected = 'sha256=' + crypto
  .createHmac('sha256', YOUR_WEBHOOK_SECRET)
  .update(JSON.stringify(req.body))
  .digest('hex')
if (sig !== expected) { res.status(401).send('Unauthorized'); return }

📦 SDK Examples

Send a WhatsApp message to a group using your preferred language.

cURL

Copycurl -X POST https://sevenoways.app/api/send \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "INSTANCE_ID",
    "groupIds": ["GROUP_ID@g.us"],
    "message": "Hello from cURL!"
  }'

JavaScript (fetch)

Copyconst response = await fetch('https://sevenoways.app/api/send', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    instanceId: 'INSTANCE_ID',
    groupIds: ['GROUP_ID@g.us'],
    message: 'Hello from JavaScript!'
  })
})
const data = await response.json()
console.log(data)

Python (requests)

Copyimport requests

response = requests.post(
    'https://sevenoways.app/api/send',
    headers={
        'x-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'instanceId': 'INSTANCE_ID',
        'groupIds': ['GROUP_ID@g.us'],
        'message': 'Hello from Python!'
    }
)
print(response.json())

PHP (cURL)

Copy$ch = curl_init('https://sevenoways.app/api/send');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'x-api-key: YOUR_API_KEY',
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'instanceId' => 'INSTANCE_ID',
        'groupIds'   => ['GROUP_ID@g.us'],
        'message'    => 'Hello from PHP!'
    ])
]);
$result = json_decode(curl_exec($ch), true);

⏰ Cron Reference

Common timezones: Asia/Dubai  ·  Europe/London  ·  America/New_York  ·  UTC