توثيق واجهة البرمجة API — madarmsg

Authentication

Every request requires your device API key. Create a device in the panel and copy the key from the device details page. You can pass the key using either the Authorization header or the X-API-Key header.

Authorization: Bearer YOUR_API_KEY
# or
X-API-Key: YOUR_API_KEY

POSTSend Text Message

Send a plain text message to a WhatsApp number (international format) or a group.

POST /api/send-message
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "phone": "9665XXXXXXXX",
  "message": "Hello from madarmsg",
  "isGroup": false
}

✅ Success Response: {"success": true, "type": "text", "messageId": "XXXXXXXXXXX", "phoneNumber": "9665XXXXXXXX"}

POSTSend Image — via Public URL

Send an image by providing a publicly accessible URL. The server will download the image and forward it to WhatsApp. Use Content-Type: application/json.

POST /api/send-media
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "phone": "9665XXXXXXXX",
  "url": "https://example.com/photo.jpg",
  "caption": "Check this photo!",
  "isGroup": false
}

✅ Success Response: {"success": true, "type": "image", "messageId": "XXXXXXXXXXX", "phoneNumber": "9665XXXXXXXX"}

POSTSend Image — via File Upload (from Disk)

Upload an image directly from your local disk or server. Use Content-Type: multipart/form-data and attach the file in the file field.

POST /api/send-media
Authorization: Bearer YOUR_API_KEY
Content-Type: multipart/form-data

phone=9665XXXXXXXX
caption=Check this photo!
file=<binary image file>

✅ Success Response: {"success": true, "type": "image", "messageId": "XXXXXXXXXXX", "phoneNumber": "9665XXXXXXXX"}

💡 Python example:

import requests

resp = requests.post(
    "https://your-panel.com/api/send-media",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    data={"phone": "9665XXXXXXXX", "caption": "My photo"},
    files={"file": open("/path/to/photo.jpg", "rb")}
)
print(resp.json())

💡 PHP (Guzzle) example:

$client = new GuzzleHttp\Client();
$response = $client->post('https://your-panel.com/api/send-media', [
    'headers' => ['Authorization' => 'Bearer YOUR_API_KEY'],
    'multipart' => [
        ['name' => 'phone',   'contents' => '9665XXXXXXXX'],
        ['name' => 'caption', 'contents' => 'My photo'],
        ['name' => 'file',    'contents' => fopen('/path/to/photo.jpg', 'r'),
                              'filename'  => 'photo.jpg'],
    ]
]);

POSTSend Document — via Public URL

Send any document (PDF, Word, Excel, ZIP…) by providing a publicly accessible URL. Use Content-Type: application/json.

POST /api/send-document
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "phone": "9665XXXXXXXX",
  "url": "https://example.com/invoice.pdf",
  "fileName": "invoice.pdf",
  "caption": "Your invoice is attached",
  "isGroup": false
}

✅ Success Response: {"success": true, "type": "document", "messageId": "XXXXXXXXXXX", "phoneNumber": "9665XXXXXXXX"}

POSTSend Document — via File Upload (from Disk)

Upload any document directly from your local disk or server. Use Content-Type: multipart/form-data and attach the file in the file field.

POST /api/send-document
Authorization: Bearer YOUR_API_KEY
Content-Type: multipart/form-data

phone=9665XXXXXXXX
fileName=invoice.pdf
caption=Your invoice is attached
file=<binary document file>

✅ Success Response: {"success": true, "type": "document", "messageId": "XXXXXXXXXXX", "phoneNumber": "9665XXXXXXXX"}

💡 Python example:

import requests

resp = requests.post(
    "https://your-panel.com/api/send-document",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    data={"phone": "9665XXXXXXXX", "fileName": "report.pdf", "caption": "Monthly report"},
    files={"file": open("/path/to/report.pdf", "rb")}
)
print(resp.json())

💡 PHP (Guzzle) example:

$client = new GuzzleHttp\Client();
$response = $client->post('https://your-panel.com/api/send-document', [
    'headers' => ['Authorization' => 'Bearer YOUR_API_KEY'],
    'multipart' => [
        ['name' => 'phone',    'contents' => '9665XXXXXXXX'],
        ['name' => 'fileName', 'contents' => 'invoice.pdf'],
        ['name' => 'caption',  'contents' => 'Your invoice'],
        ['name' => 'file',     'contents' => fopen('/path/to/invoice.pdf', 'r'),
                               'filename'  => 'invoice.pdf'],
    ]
]);

GETDevice Info

Returns connection status, linked WhatsApp phone, and remaining message quota for your device.

GET /api/device/info
Authorization: Bearer YOUR_API_KEY

{
  "success": true,
  "device_id": "...",
  "label": "My Device",
  "connection_status": "connected",
  "messages_remaining": 450
}

Webhooks

Configure a webhook URL on your device to receive inbound WhatsApp messages (text, image, document, video, audio, location, groups). madarmsg will POST the following JSON payload to your URL on every incoming message.

POST https://your-server.com/webhook
Content-Type: application/json

{
  "event": "message.received",
  "deviceId": "your-device-id",
  "timestamp": "2026-07-14T12:00:00.000Z",
  "isGroup": false,
  "groupId": null,
  "message": {
    "id": "wa-message-id",
    "from": "9665XXXXXXXX",
    "from_jid": "9665XXXXXXXX@s.whatsapp.net",
    "from_name": "Customer",
    "type": "text",
    "text": "Customer reply",
    "isGroup": false,
    "groupId": null
  }
}