WhatsApp API
Documentation

Overview

The Onyx WhatsApp API lets you send and receive WhatsApp messages programmatically using a simple HTTP REST interface. You can send text, images, PDFs, documents and more — to individuals or groups — from any programming language or platform.

The API uses an unofficial WhatsApp connection tied to your own WhatsApp number via a QR scan. Your messages are delivered directly from your number.

2 Setup & Connection

Before making any API calls, you need to connect your WhatsApp number to our cloud service.

Authentication

Every API request requires your Client ID and API Key, passed as URL path segments. You can find these in the API tab of your dashboard after login.

https://onyxberry.com/services/wapi/Api2/{method}/{YOUR_CLIENT_ID}/{YOUR_API_KEY}

Replace {YOUR_CLIENT_ID} and {YOUR_API_KEY} with the values from your dashboard API tab. In the SDK examples below, these are shown as YOUR_USER_ID and YOUR_API_KEY — they are the same credentials.

Send Text Message

Send a plain text message to any WhatsApp number. The number must include the country code with + prefix.

require_once __DIR__ . '/OnyxWhatsAppClient.php';

$client = new OnyxWhatsAppClient('YOUR_USER_ID', 'YOUR_API_KEY');

$result = $client->sendText('+971566599829', 'Hello! This is sent via Onyx API 👋');
print_r($result);

curl -X POST \
  "https://onyxberry.com/services/wapi/Api2/sendText/YOUR_USER_ID/YOUR_API_KEY" \
  -d "number=+971566599829" \
  -d "message=Hello from Onyx API!"

const { OnyxWhatsAppClient } = require('./index');

const client = new OnyxWhatsAppClient('YOUR_USER_ID', 'YOUR_API_KEY');

client.sendText('+971566599829', 'Hello! 👋')
  .then(res => console.log(res));

from onyx_whatsapp_sdk import OnyxWhatsAppClient

client = OnyxWhatsAppClient("YOUR_USER_ID", "YOUR_API_KEY")
result = client.send_text('+971566599829', 'Hello! 👋')
print(result)

{ "status": 200, "message": "WhatsApp chat has been queued for sending!", "data": false, "saved_message_id": 8821, "message_status": "pending", "message_status_code": 0 }

{ "status": 400, "message": "Invalid phone number!" }
{ "status": "error", "response": "Invalid Credentials" }
{ "status": 500, "error": "WhatsApp account doesn't exist!" }

Send Bulk Messages

Queue up to 100 messages in a single API call. Each message is delivered asynchronously through the same queue as single messages — your configured random delay (set in Dashboard → Random Delay Settings) is applied between every send to keep your WhatsApp account safe.

require_once __DIR__ . '/OnyxWhatsAppClient.php';

$client = new OnyxWhatsAppClient('YOUR_USER_ID', 'YOUR_API_KEY');

$response = $client->sendBulk([
    ['number' => '+971566599829', 'message' => 'Hi Ahmed! Your invoice #1001 is ready.'],
    ['number' => '+971501234567', 'message' => 'Hi Sara! Your order has been shipped.'],
    ['number' => '+971509876543', 'message' => 'Hi Khalid! Your appointment is confirmed.'],
]);

echo "Queued: " . $response['queued'] . " messages\n";
echo "Batch ID: " . $response['batch_id'] . "\n";

curl -X POST \
  "https://onyxberry.com/services/wapi/Api2/sendBulk/YOUR_USER_ID/YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "number": "+971566599829", "message": "Hi Ahmed! Your invoice #1001 is ready." },
      { "number": "+971501234567", "message": "Hi Sara! Your order has been shipped." },
      { "number": "+971509876543", "message": "Hi Khalid! Your appointment is confirmed." }
    ]
  }'

from onyx_whatsapp_sdk import OnyxWhatsAppClient

client = OnyxWhatsAppClient("YOUR_USER_ID", "YOUR_API_KEY")

messages = [
    {"number": "+971566599829", "message": "Hi Ahmed! Your invoice #1001 is ready."},
    {"number": "+971501234567", "message": "Hi Sara! Your order has been shipped."},
    {"number": "+971509876543", "message": "Hi Khalid! Your appointment is confirmed."},
]

data = client.send_bulk(messages)
print(f"Queued: {data['queued']} messages")
print(f"Batch ID: {data['batch_id']}")

const { OnyxWhatsAppClient } = require('./index');

const client = new OnyxWhatsAppClient('YOUR_USER_ID', 'YOUR_API_KEY');
const messages = [
  { number: '+971566599829', message: 'Hi Ahmed! Your invoice #1001 is ready.' },
  { number: '+971501234567', message: 'Hi Sara! Your order has been shipped.' },
  { number: '+971509876543', message: 'Hi Khalid! Your appointment is confirmed.' },
];

client.sendBulk(messages).then(res => {
  console.log(`Queued: ${res.queued}`);
  console.log(`Batch: ${res.batch_id}`);
});

{
  "status": "success",
  "response": "3 message(s) queued successfully.",
  "batch_id": "a3f2c1d0-4e5b-4f6a-8b9c-0d1e2f3a4b5c",
  "queued": 3,
  "queued_messages": [
    { "recipient": "971566599829", "saved_message_id": 8821, "message_status": "pending", "message_status_code": 0 }
  ],
  "skipped": [],
  "credits_remaining": 4997,
  "estimated_completion": {
    "min_seconds": 15,
    "max_seconds": 45,
    "note": "Actual delivery time depends on your configured message delay (5–15s). Adjust in Dashboard → Settings."
  },
  "warning": "IMPORTANT: Sending bulk messages carries a risk of WhatsApp account suspension...",
  "anti_ban_notice": {
    "delay_applied": "A random 5–15s delay is enforced between each message by the delivery engine.",
    "duplicate_filtering": "Duplicate phone numbers within this batch were automatically removed.",
    "queue_based": "Messages are delivered asynchronously — your account is never flooded.",
    "recommendation": "For large campaigns (200+ contacts), split into daily batches.",
    "onyxberry_liability": "OnyxBerry is not responsible for WhatsApp account bans."
  }
}

Send Media (PDF, Image, File)

Send any media file from a publicly accessible URL. Supports images, PDFs, Word docs, Excel files, videos and more. Maximum file size: 10MB.

require_once __DIR__ . '/OnyxWhatsAppClient.php';

$client = new OnyxWhatsAppClient('YOUR_USER_ID', 'YOUR_API_KEY');

$result = $client->sendFromURL(
    '+971566599829',
    'https://example.com/invoice.pdf',
    'Your November Invoice 📄'
);
print_r($result);

curl -X POST \
  "https://onyxberry.com/services/wapi/Api2/sendFromURL/YOUR_CLIENT_ID/YOUR_API_KEY" \
  -d "number=+971566599829" \
  -d "url=https://example.com/invoice.pdf" \
  -d "caption=Your November Invoice 📄"

const { OnyxWhatsAppClient } = require('./index');
const client = new OnyxWhatsAppClient('YOUR_USER_ID', 'YOUR_API_KEY');

client.sendFromURL('+971566599829', 'https://example.com/invoice.pdf', 'Your November Invoice 📄')
  .then(res => console.log(res));

from onyx_whatsapp_sdk import OnyxWhatsAppClient

client = OnyxWhatsAppClient("YOUR_USER_ID", "YOUR_API_KEY")
result = client.send_from_url(
    "+971566599829",
    "https://example.com/invoice.pdf",
    "Your November Invoice 📄"
)
print(result)

{ "status": 200, "message": "WhatsApp chat has been queued for sending!", "data": false, "saved_message_id": 8821, "message_status": "pending", "message_status_code": 0 }

Send Text to Group

Send a text message to a WhatsApp group. Use the group's internal ID (e.g. [email protected]). Get your Group IDs from the dashboard (Messages → My WA Groups) or the Get Groups API endpoint.

require_once __DIR__ . '/OnyxWhatsAppClient.php';

$client = new OnyxWhatsAppClient('YOUR_USER_ID', 'YOUR_API_KEY');

$result = $client->sendTextInGroup(
    '[email protected]',
    'Hello everyone! Team meeting at 3 PM 👋'
);
print_r($result);

curl -X POST \
  "https://onyxberry.com/services/wapi/Api2/sendTextInGroup/YOUR_CLIENT_ID/YOUR_API_KEY" \
  -d "[email protected]" \
  -d "message=Hello everyone! Team meeting at 3 PM 👋"

const { OnyxWhatsAppClient } = require('./index');
const client = new OnyxWhatsAppClient('YOUR_USER_ID', 'YOUR_API_KEY');

client.sendTextInGroup('[email protected]', 'Hello everyone! Team meeting at 3 PM 👋')
  .then(res => console.log(res));

from onyx_whatsapp_sdk import OnyxWhatsAppClient

client = OnyxWhatsAppClient("YOUR_USER_ID", "YOUR_API_KEY")
result = client.send_text_in_group(
    "[email protected]",
    "Hello everyone! Team meeting at 3 PM 👋"
)
print(result)

Send Media to Group

Send a PDF, image, or document to a WhatsApp group from a publicly accessible URL. Maximum file size: 10MB.

require_once __DIR__ . '/OnyxWhatsAppClient.php';

$client = new OnyxWhatsAppClient('YOUR_USER_ID', 'YOUR_API_KEY');

$result = $client->sendFromURLInGroup(
    '[email protected]',
    'https://example.com/report.pdf',
    'Monthly report attached 📄'
);
print_r($result);

curl -X POST \
  "https://onyxberry.com/services/wapi/Api2/sendFromURLInGroup/YOUR_CLIENT_ID/YOUR_API_KEY" \
  -d "[email protected]" \
  -d "url=https://example.com/report.pdf" \
  -d "caption=Monthly report attached 📄"

const { OnyxWhatsAppClient } = require('./index');
const client = new OnyxWhatsAppClient('YOUR_USER_ID', 'YOUR_API_KEY');

client.sendFromURLInGroup('[email protected]', 'https://example.com/report.pdf', 'Monthly report attached 📄')
  .then(res => console.log(res));

from onyx_whatsapp_sdk import OnyxWhatsAppClient

client = OnyxWhatsAppClient("YOUR_USER_ID", "YOUR_API_KEY")
result = client.send_from_url_in_group(
    "[email protected]",
    "https://example.com/report.pdf",
    "Monthly report attached 📄"
)
print(result)

Check WhatsApp Registration

Verify whether a phone number is registered on WhatsApp before sending messages to it.

require_once __DIR__ . '/OnyxWhatsAppClient.php';

$client = new OnyxWhatsAppClient('YOUR_USER_ID', 'YOUR_API_KEY');

$result = $client->isRegisteredUser('+971566599829');
print_r($result);

curl -X POST \
  "https://onyxberry.com/services/wapi/Api2/isRegisteredUser/YOUR_CLIENT_ID/YOUR_API_KEY" \
  -d "number=+971566599829"

const { OnyxWhatsAppClient } = require('./index');
const client = new OnyxWhatsAppClient('YOUR_USER_ID', 'YOUR_API_KEY');

client.isRegisteredUser('+971566599829')
  .then(res => console.log(res));

from onyx_whatsapp_sdk import OnyxWhatsAppClient

client = OnyxWhatsAppClient("YOUR_USER_ID", "YOUR_API_KEY")
result = client.is_registered_user("+971566599829")
print(result)

true

false

Get Message Status

Look up the delivery status of a message you previously sent using the saved_message_id returned from any send endpoint. You can only query messages belonging to your own account — attempting to read another user's message ID returns 404.

{
  "status": 200,
  "message": "Message status",
  "data": {
    "id": 8821,
    "recipient": "+971566599829",
    "message": "Your order has shipped!",
    "message_type": null,
    "message_status": "delivered",
    "message_status_code": 1,
    "created_at": "2026-07-18 08:30:00",
    "updated_at": "2026-07-18 08:30:12",
    "retry_count": 0,
    "fail_reason": null
  }
}

Get Received Chats

Retrieve incoming WhatsApp messages received on your connected number — paginated, newest first. Use this to build chatbots, support inboxes, or trigger your own backend workflows.

$url = "https://onyxberry.com/services/wapi/Api2/getReceivedChats?user_id=YOUR_USER_ID&api_key=YOUR_API_KEY&page=1&limit=20";

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
foreach ($data['data'] as $chat) {
    echo $chat['account'] . ' said: ' . $chat['message'] . PHP_EOL;
}

curl -X GET "https://onyxberry.com/services/wapi/Api2/getReceivedChats?user_id=YOUR_USER_ID&api_key=YOUR_API_KEY&page=1&limit=20"

import requests

r = requests.get('https://onyxberry.com/services/wapi/Api2/getReceivedChats', params={
    'user_id': 'YOUR_USER_ID',
    'api_key': 'YOUR_API_KEY',
    'page':    1,
    'limit':   20,
})
for chat in r.json()['data']:
    print(chat['account'], 'said:', chat['message'])

const axios = require('axios');

axios.get('https://onyxberry.com/services/wapi/Api2/getReceivedChats', {
    params: { user_id: 'YOUR_USER_ID', api_key: 'YOUR_API_KEY', page: 1, limit: 20 }
}).then(res => {
    res.data.data.forEach(c => console.log(c.account, 'said:', c.message));
});

{
  "status": 200,
  "message": "Received WhatsApp Chats",
  "data": [
    {
      "id": 301,
      "account":   "+447380294906",
      "recipient": "+639760713666",
      "message":   "Hello, I need help!",
      "attachment": null,
      "created":   1711234567
    }
  ]
}

SDKs & Integrations

Use our ready-made libraries to integrate in minutes — no need to write raw HTTP code. All endpoint examples above use these official SDKs.

PHP SDK — Quick Start

1. Download PHP SDK v3 below and unzip it.
2. Place OnyxWhatsAppClient.php in your project (same folder as your script is easiest).
3. Copy your User ID and API Key from Dashboard → API tab.
4. Require the class and create a client — see the example below.

require_once __DIR__ . '/OnyxWhatsAppClient.php';

$client = new OnyxWhatsAppClient('YOUR_USER_ID', 'YOUR_API_KEY');

// Validate credentials
print_r($client->validateCredentials());

// Send text
print_r($client->sendText('+971500000000', 'Hello from Onyx SDK v3'));

// Send media from URL
print_r($client->sendFromURL('+971500000000', 'https://example.com/invoice.pdf', 'Invoice'));

// Send bulk (up to 100)
print_r($client->sendBulk([
    ['number' => '+971500000001', 'message' => 'Hi A'],
    ['number' => '+971500000002', 'message' => 'Hi B'],
]));

// Groups & received chats
print_r($client->getGroups());
print_r($client->getReceivedChats(1, 20));

Video Tutorials

Watch these walkthroughs to get started quickly with the Onyx WhatsApp API.

Response Codes

Best Practices

Get Your WhatsApp Groups

Returns a list of all WhatsApp groups your connected number is a member of, including the Group ID (gid) you need to send group messages via the API.

<?php
$user_id = 'YOUR_USER_ID';
$api_key = 'YOUR_API_KEY';

$url = "https://onyxberry.com/services/wapi/Api2/getGroups?user_id=$user_id&api_key=$api_key";

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response  = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($http_code === 200) {
    $data = json_decode($response, true);
    foreach ($data['data'] as $group) {
        echo $group['name'] . ' → ' . $group['gid'] . PHP_EOL;
    }
}

curl -X GET "https://onyxberry.com/services/wapi/Api2/getGroups?user_id=YOUR_USER_ID&api_key=YOUR_API_KEY"

import requests

params = {
    'user_id': 'YOUR_USER_ID',
    'api_key': 'YOUR_API_KEY',
}

r = requests.get('https://onyxberry.com/services/wapi/Api2/getGroups', params=params)
if r.status_code == 200:
    for group in r.json()['data']:
        print(group['name'], '→', group['gid'])

const axios = require('axios');

axios.get('https://onyxberry.com/services/wapi/Api2/getGroups', {
    params: { user_id: 'YOUR_USER_ID', api_key: 'YOUR_API_KEY' }
}).then(res => {
    res.data.data.forEach(g => console.log(g.name, '->', g.gid));
});

{
  "status": 200,
  "message": "WhatsApp Groups",
  "data": [
    { "gid": "[email protected]", "name": "My Test Group" },
    { "gid": "[email protected]", "name": "Family Group" },
    { "gid": "[email protected]", "name": "Support Team" }
  ]
}

{
  "user_id":  "YOUR_USER_ID",
  "api_key":  "YOUR_API_KEY",
  "send_to":  "[email protected]",   // ← paste gid here
  "body":     "Hello everyone! 👋"
}

Account Management API Exclusive

The Account Management API lets approved accounts fully manage their WhatsApp session, QR code, message quota, and outbound message history from their own CRM — without using the Onyx dashboard.

These endpoints are separate from Api2 and do not change any existing messaging API behaviour. If the feature is not enabled, all Account Management calls return HTTP 403.

Typical CRM Integration Flow

Get Session Status

Returns the current WhatsApp connection state for your account — whether the session is connected, running, waiting for QR scan, or disconnected.

{
  "status": 200,
  "message": "WhatsApp session status",
  "data": {
    "connected": true,
    "session_running": true,
    "status_text": "WhatsApp is ready",
    "whatsapp_status": "",
    "pending_command": null,
    "has_qr": false,
    "last_activity": "2026-07-18 09:15:00",
    "sending_paused": false,
    "realtime_only": false,
    "package_expiry": "2027-07-18"
  }
}

Get QR Code

Returns the current QR code image (base64 data URL) when the session is waiting for a scan. Poll this endpoint after calling startSession. When connected is true, the QR field will be empty.

{
  "status": 200,
  "message": "QR code ready for scanning.",
  "data": {
    "connected": false,
    "status_text": "Waiting for QR scan...",
    "qr_code": "data:image/png;base64,iVBORw0KGgo..."
  }
}

Start, Stop & Reset Session

Control your WhatsApp cloud session programmatically. All three endpoints use POST and accept credentials in the URL path (same as messaging APIs).

{
  "status": 200,
  "message": "Session start initiated.",
  "data": { "command": "3", "action": "start" }
}

Get Message Quota

Returns your plan allowance, consumed count, remaining credits, and package expiry date — useful for displaying usage in your CRM.

{
  "status": 200,
  "message": "Message quota usage",
  "data": {
    "plan_name": "Pro Plan",
    "account_enabled": true,
    "total_allowed": 5000,
    "total_consumed": 1247,
    "remaining": 3753,
    "package_expiry": "2027-07-18",
    "usage_percent": 24.94
  }
}

Get Outbound Messages

Returns paginated outbound messages sent via the API for your account. Use this to sync delivery status into your CRM.

{
  "status": 200,
  "message": "Outbound messages",
  "data": {
    "page": 1,
    "limit": 20,
    "total": 142,
    "total_pages": 8,
    "filter": "all",
    "messages": [
      {
        "id": 8821,
        "recipient": "+971566599829",
        "message": "Your order has shipped!",
        "status": "delivered",
        "status_code": 1,
        "created_at": "2026-07-18 08:30:00",
        "updated_at": "2026-07-18 08:30:12",
        "retry_count": 0,
        "fail_reason": null
      }
    ]
  }
}

Auto-Reply Bot

The Auto-Reply Bot lets you automatically respond to incoming WhatsApp messages based on keyword rules. When a message matches your configured keywords, the bot instantly sends a reply — with text, image, or document — without any code on your side.

How It Works

Match Types

Reply Shortcodes

You can use these shortcodes inside your reply message text — they are replaced with live values at the time of sending:

Reply Message Types

Webhooks

Webhooks let Onyx WhatsApp API push real-time events to your own server using HTTP POST requests with a JSON body. Use them to sync messages with your CRM, trigger automations, update order status, or log activity — without polling the API.

How It Works

Events

Request Format

All webhook calls use HTTP POST with Content-Type: application/json, User-Agent: Onyx-WAPI-Webhook/1.0, and X-Onyx-User-Id (your account ID). Your endpoint should accept POST only, verify the user ID matches your account, and respond with HTTP 2xx as quickly as possible.

Payload — Message Received

{
  "event": "message.received",
  "user_id": 123,
  "timestamp": 1710000000,
  "message": {
    "from": "971566599829",
    "to": "971501234567",
    "chat_id": "[email protected]",
    "body": "Hello, I need help with my order",
    "has_media": false,
    "message_id": "3EB0...",
    "timestamp": 1710000000
  }
}

Payload — Message Sent (Delivered)

{
  "event": "message.sent",
  "user_id": 123,
  "timestamp": 1710000000,
  "delivery": {
    "ack": 2,
    "confirmed": true
  },
  "message": {
    "saved_message_id": "456",
    "recipient": "971566599829",
    "message": "Your order has shipped!",
    "media_url": null,
    "command": "sendText",
    "whatsapp_message_id": "3EB0..."
  }
}

The delivery.ack value reflects WhatsApp's delivery status. A send webhook fires only when delivery is confirmed (typically ack ≥ 2, meaning delivered to the recipient's device).

Example Receiver (PHP)

Your endpoint reads the raw JSON body from the POST request. Process quickly and return HTTP 200 — offload heavy work to a background queue if needed.

// webhook.php — must accept POST only
if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
    http_response_code(405);
    exit('Method not allowed');
}

$raw  = file_get_contents('php://input');
$data = json_decode($raw, true);
$expectedUserId = 123; // your Onyx user ID from the dashboard

if ((int) ($_SERVER['HTTP_X_ONYX_USER_ID'] ?? 0) !== $expectedUserId
    || (int) ($data['user_id'] ?? 0) !== $expectedUserId) {
    http_response_code(403);
    exit('Forbidden');
}

if (!is_array($data) || empty($data['event'])) {
    http_response_code(400);
    exit('Invalid payload');
}

switch ($data['event']) {
    case 'message.received':
        // e.g. create a support ticket from $data['message']['from'] and body
        break;
    case 'message.sent':
        // e.g. mark order as delivered in your CRM
        break;
}

http_response_code(200);
echo 'OK';

Node.js Example

app.post('/webhook/receive', express.json(), (req, res) => {
  const { event, message } = req.body;
  if (event === 'message.received') {
    console.log('New message from', message.from, ':', message.body);
  }
  res.sendStatus(200);
});

Dashboard & Logs

After webhooks are enabled, open Dashboard → Webhooks to:

• Save your send and receive URLs (one of each)
• Review delivery logs — time, event type, HTTP status, success/failure, and payload preview

Important Notes

How WhatsApp Detects Abuse

WhatsApp uses a combination of AI-based pattern detection, user reports, and device/account signals to identify abusive senders. The key signals they watch for:

Message Volume Risk Levels

Use this as a daily volume guide. These are conservative estimates — actual tolerance varies by account age, history, and recipient behaviour.

Safe vs Risky Message Examples

Configuring Your Message Delay

Your random delay (set in Dashboard → Settings) is applied between every message by the delivery engine. This is the single most important protection against WhatsApp bans.

10 Rules to Keep Your Account Safe

If Your Account Gets Banned

Built-in Protections in Onyx API

Onyx API includes several automatic safeguards — but they are not a substitute for responsible usage: