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.

Send Text Message

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

include('WhatsappAPI.php');
$wp = new WhatsappAPI("YOUR_CLIENT_ID", "YOUR_API_KEY");

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

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

const onxy = new OnxyMessaging('YOUR_ID', 'YOUR_KEY');
onxy.sendSimpleTextMessage('+971566599829', 'Hello! 👋')
  .then(res => console.log(res));

result = wp.send_simple_text_message('+971566599829', 'Hello! 👋')
print(result)

{ "status": 200, "message": "WhatsApp chat has been queued for sending!", "data": false }

{ "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.

$client_id = "YOUR_CLIENT_ID";
$api_key   = "YOUR_API_KEY";
$url       = "https://onyxberry.com/services/wapi/Api2/sendBulk/{$client_id}/{$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.'],
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['messages' => $messages]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

echo "Queued: " . $response['queued'] . " messages\n";
echo "Batch ID: " . $response['batch_id'] . "\n";
echo "ETA: " . $response['estimated_completion']['min_seconds'] . "–" . $response['estimated_completion']['max_seconds'] . "s\n";

curl -X POST \
  "https://onyxberry.com/services/wapi/Api2/sendBulk/YOUR_ID/YOUR_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." }
    ]
  }'

import requests

client_id = "YOUR_CLIENT_ID"
api_key   = "YOUR_API_KEY"
url       = f"https://onyxberry.com/services/wapi/Api2/sendBulk/{client_id}/{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."},
]

res = requests.post(url, json={"messages": messages})
data = res.json()

print(f"Queued: {data['queued']} messages")
print(f"Batch ID: {data['batch_id']}")
print(f"Skipped: {data['skipped']}")

const axios = require('axios');

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.' },
];

axios.post(
  `https://onyxberry.com/services/wapi/Api2/sendBulk/YOUR_ID/YOUR_KEY`,
  { messages }
).then(res => {
  console.log(`Queued: ${res.data.queued}`);
  console.log(`Batch: ${res.data.batch_id}`);
  console.log(`ETA: ${res.data.estimated_completion.min_seconds}–${res.data.estimated_completion.max_seconds}s`);
});

{
  "status": "success",
  "response": "3 message(s) queued successfully.",
  "batch_id": "a3f2c1d0-4e5b-4f6a-8b9c-0d1e2f3a4b5c",
  "queued": 3,
  "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.

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

Send Text to Group

Send a text message to a WhatsApp group. Use the group's internal ID (e.g. [email protected]). Contact support to get your group IDs.

Send Media to Group

Check WhatsApp Registration

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

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.

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! 👋"
}

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

Webhook Hooks

Webhook Hooks let you call your own server endpoint via HTTP GET whenever a WhatsApp message is sent or received on your connected number. Use this to sync messages with your CRM, trigger automations, or log activity in real time.

Hook Events

Available Shortcodes in URL

When building your webhook URL, add shortcodes as query parameters — they will be replaced with real values before the GET request is fired:

Example Webhook URL

https://yoursite.com/hook.php?phone={{phone}}&message={{message}}&time={{date.now}}

Receiving the Request

Your endpoint receives a standard HTTP GET request with the shortcodes replaced. Here's a minimal PHP handler:

$phone   = htmlspecialchars($_GET['phone']   ?? '');
$message = htmlspecialchars($_GET['message'] ?? '');
$time    = htmlspecialchars($_GET['time']    ?? '');

// Log or process the incoming message
file_put_contents('webhook_log.txt',
    "[$time] From: $phone — $message\n",
    FILE_APPEND
);

// Must return HTTP 200 OK
http_response_code(200);
echo 'OK';

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: