وثائق نبيه API
أرسل أول رسالة خلال دقيقة.
اربط نظامك بواتساب باستخدام Integration Token الخاص بك.
- 1أنشئ Integration من لوحة التحكم.
- 2انسخ Integration Token واحفظه في خادمك.
- 3أرسل أول رسالة إلى رقم واتساب.
POST /api/send-message
Authorization: Bearer YOUR_INTEGRATION_TOKEN
Content-Type: application/json
{
"to": "9665XXXXXXXX",
"message": "مرحبا",
"type": "text"
}
{
"success": true,
"message_id": "msg_...",
"status": "sent"
}
احتفظ بـ message_id لمتابعة الحالة. حالة sent تعني قبول الإرسال لدى المزود.
Authentication
استخدم نفس Integration Token في جميع الطلبات. يحدد التوكن التكامل تلقائيًا؛ لا ترسل معرّف الحساب أو التكامل في البيانات.
Authorization: Bearer YOUR_INTEGRATION_TOKEN
احفظ التوكن في الخادم أو متغيرات البيئة. لا تضعه في صفحة عامة أو JavaScript يعمل في متصفح الزائر.
إرسال رسالة
POST /api/send-message
| الحقل | الاستخدام |
|---|---|
| to | مطلوب. رقم المستلم مع رمز الدولة. |
| message | نص الرسالة، أو شرح اختياري للوسائط. |
| type | نوع الرسالة. الافتراضي text. |
| media_url | رابط عام مطلوب للوسائط. يستخدم أيضًا مع link. |
| link_url | رابط إضافي مع image_link. |
أنواع الرسائل
اختر نوع الرسالة ولغة المثال، وستحصل على طلب كامل جاهز للنسخ والتجربة مباشرة. يجب أن تكون روابط الوسائط عامة وقابلة للوصول. الفيديو مدعوم في نظام البوت وMeta؛ إرسال المستندات متاح عبر نظام البوت.
curl -X POST 'https://naabih.com/api/send-message' \
-H 'Authorization: Bearer YOUR_INTEGRATION_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"to":"9665XXXXXXXX","message":"مرحبا","type":"text"}'
$headers = @{ Authorization = 'Bearer YOUR_INTEGRATION_TOKEN' }
$body = @{
to = '9665XXXXXXXX'
message = 'مرحبا'
type = 'text'
} | ConvertTo-Json
Invoke-RestMethod `
-Uri 'https://naabih.com/api/send-message' `
-Method Post `
-Headers $headers `
-ContentType 'application/json; charset=utf-8' `
-Body ([System.Text.Encoding]::UTF8.GetBytes($body))
// احفظ المثال في send.mjs وشغّله في الخادم. احفظ التوكن في متغير بيئة.
const response = await fetch('https://naabih.com/api/send-message', {
method: 'POST',
headers: {
Authorization: 'Bearer ' + process.env.NAABIH_API_TOKEN,
'Content-Type': 'application/json'
},
body: JSON.stringify({
"to": "9665XXXXXXXX",
"message": "مرحبا",
"type": "text"
})
});
const result = await response.json();
if (!response.ok) throw new Error(result.code || 'SEND_FAILED');
console.log(result.message_id, result.status);
<?php
$ch = curl_init('https://naabih.com/api/send-message');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('NAABIH_API_TOKEN'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'to' => '9665XXXXXXXX',
'message' => 'مرحبا',
'type' => 'text'
], JSON_UNESCAPED_UNICODE),
]);
$response = curl_exec($ch);
if ($response === false) throw new RuntimeException(curl_error($ch));
$httpStatus = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$result = json_decode($response, true);
if ($httpStatus >= 400) throw new RuntimeException($result['code'] ?? 'SEND_FAILED');
echo $result['message_id'];
curl -X POST 'https://naabih.com/api/send-message' \
-H 'Authorization: Bearer YOUR_INTEGRATION_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"to":"9665XXXXXXXX","message":"الصورة","type":"image","media_url":"https://example.com/image.jpg"}'
$headers = @{ Authorization = 'Bearer YOUR_INTEGRATION_TOKEN' }
$body = @{
to = '9665XXXXXXXX'
message = 'الصورة'
type = 'image'
media_url = 'https://example.com/image.jpg'
} | ConvertTo-Json
Invoke-RestMethod `
-Uri 'https://naabih.com/api/send-message' `
-Method Post `
-Headers $headers `
-ContentType 'application/json; charset=utf-8' `
-Body ([System.Text.Encoding]::UTF8.GetBytes($body))
// احفظ المثال في send.mjs وشغّله في الخادم. احفظ التوكن في متغير بيئة.
const response = await fetch('https://naabih.com/api/send-message', {
method: 'POST',
headers: {
Authorization: 'Bearer ' + process.env.NAABIH_API_TOKEN,
'Content-Type': 'application/json'
},
body: JSON.stringify({
"to": "9665XXXXXXXX",
"message": "الصورة",
"type": "image",
"media_url": "https://example.com/image.jpg"
})
});
const result = await response.json();
if (!response.ok) throw new Error(result.code || 'SEND_FAILED');
console.log(result.message_id, result.status);
<?php
$ch = curl_init('https://naabih.com/api/send-message');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('NAABIH_API_TOKEN'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'to' => '9665XXXXXXXX',
'message' => 'الصورة',
'type' => 'image',
'media_url' => 'https://example.com/image.jpg'
], JSON_UNESCAPED_UNICODE),
]);
$response = curl_exec($ch);
if ($response === false) throw new RuntimeException(curl_error($ch));
$httpStatus = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$result = json_decode($response, true);
if ($httpStatus >= 400) throw new RuntimeException($result['code'] ?? 'SEND_FAILED');
echo $result['message_id'];
curl -X POST 'https://naabih.com/api/send-message' \
-H 'Authorization: Bearer YOUR_INTEGRATION_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"to":"9665XXXXXXXX","type":"audio","media_url":"https://example.com/audio.mp4"}'
$headers = @{ Authorization = 'Bearer YOUR_INTEGRATION_TOKEN' }
$body = @{
to = '9665XXXXXXXX'
type = 'audio'
media_url = 'https://example.com/audio.mp4'
} | ConvertTo-Json
Invoke-RestMethod `
-Uri 'https://naabih.com/api/send-message' `
-Method Post `
-Headers $headers `
-ContentType 'application/json; charset=utf-8' `
-Body ([System.Text.Encoding]::UTF8.GetBytes($body))
// احفظ المثال في send.mjs وشغّله في الخادم. احفظ التوكن في متغير بيئة.
const response = await fetch('https://naabih.com/api/send-message', {
method: 'POST',
headers: {
Authorization: 'Bearer ' + process.env.NAABIH_API_TOKEN,
'Content-Type': 'application/json'
},
body: JSON.stringify({
"to": "9665XXXXXXXX",
"type": "audio",
"media_url": "https://example.com/audio.mp4"
})
});
const result = await response.json();
if (!response.ok) throw new Error(result.code || 'SEND_FAILED');
console.log(result.message_id, result.status);
<?php
$ch = curl_init('https://naabih.com/api/send-message');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('NAABIH_API_TOKEN'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'to' => '9665XXXXXXXX',
'type' => 'audio',
'media_url' => 'https://example.com/audio.mp4'
], JSON_UNESCAPED_UNICODE),
]);
$response = curl_exec($ch);
if ($response === false) throw new RuntimeException(curl_error($ch));
$httpStatus = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$result = json_decode($response, true);
if ($httpStatus >= 400) throw new RuntimeException($result['code'] ?? 'SEND_FAILED');
echo $result['message_id'];
curl -X POST 'https://naabih.com/api/send-message' \
-H 'Authorization: Bearer YOUR_INTEGRATION_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"to":"9665XXXXXXXX","message":"الفيديو","type":"video","media_url":"https://example.com/video.mp4"}'
$headers = @{ Authorization = 'Bearer YOUR_INTEGRATION_TOKEN' }
$body = @{
to = '9665XXXXXXXX'
message = 'الفيديو'
type = 'video'
media_url = 'https://example.com/video.mp4'
} | ConvertTo-Json
Invoke-RestMethod `
-Uri 'https://naabih.com/api/send-message' `
-Method Post `
-Headers $headers `
-ContentType 'application/json; charset=utf-8' `
-Body ([System.Text.Encoding]::UTF8.GetBytes($body))
// احفظ المثال في send.mjs وشغّله في الخادم. احفظ التوكن في متغير بيئة.
const response = await fetch('https://naabih.com/api/send-message', {
method: 'POST',
headers: {
Authorization: 'Bearer ' + process.env.NAABIH_API_TOKEN,
'Content-Type': 'application/json'
},
body: JSON.stringify({
"to": "9665XXXXXXXX",
"message": "الفيديو",
"type": "video",
"media_url": "https://example.com/video.mp4"
})
});
const result = await response.json();
if (!response.ok) throw new Error(result.code || 'SEND_FAILED');
console.log(result.message_id, result.status);
<?php
$ch = curl_init('https://naabih.com/api/send-message');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('NAABIH_API_TOKEN'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'to' => '9665XXXXXXXX',
'message' => 'الفيديو',
'type' => 'video',
'media_url' => 'https://example.com/video.mp4'
], JSON_UNESCAPED_UNICODE),
]);
$response = curl_exec($ch);
if ($response === false) throw new RuntimeException(curl_error($ch));
$httpStatus = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$result = json_decode($response, true);
if ($httpStatus >= 400) throw new RuntimeException($result['code'] ?? 'SEND_FAILED');
echo $result['message_id'];
curl -X POST 'https://naabih.com/api/send-message' \
-H 'Authorization: Bearer YOUR_INTEGRATION_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"to":"9665XXXXXXXX","message":"المستند","type":"document","media_url":"https://example.com/file.pdf"}'
$headers = @{ Authorization = 'Bearer YOUR_INTEGRATION_TOKEN' }
$body = @{
to = '9665XXXXXXXX'
message = 'المستند'
type = 'document'
media_url = 'https://example.com/file.pdf'
} | ConvertTo-Json
Invoke-RestMethod `
-Uri 'https://naabih.com/api/send-message' `
-Method Post `
-Headers $headers `
-ContentType 'application/json; charset=utf-8' `
-Body ([System.Text.Encoding]::UTF8.GetBytes($body))
// احفظ المثال في send.mjs وشغّله في الخادم. احفظ التوكن في متغير بيئة.
const response = await fetch('https://naabih.com/api/send-message', {
method: 'POST',
headers: {
Authorization: 'Bearer ' + process.env.NAABIH_API_TOKEN,
'Content-Type': 'application/json'
},
body: JSON.stringify({
"to": "9665XXXXXXXX",
"message": "المستند",
"type": "document",
"media_url": "https://example.com/file.pdf"
})
});
const result = await response.json();
if (!response.ok) throw new Error(result.code || 'SEND_FAILED');
console.log(result.message_id, result.status);
<?php
$ch = curl_init('https://naabih.com/api/send-message');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('NAABIH_API_TOKEN'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'to' => '9665XXXXXXXX',
'message' => 'المستند',
'type' => 'document',
'media_url' => 'https://example.com/file.pdf'
], JSON_UNESCAPED_UNICODE),
]);
$response = curl_exec($ch);
if ($response === false) throw new RuntimeException(curl_error($ch));
$httpStatus = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$result = json_decode($response, true);
if ($httpStatus >= 400) throw new RuntimeException($result['code'] ?? 'SEND_FAILED');
echo $result['message_id'];
curl -X POST 'https://naabih.com/api/send-message' \
-H 'Authorization: Bearer YOUR_INTEGRATION_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"to":"9665XXXXXXXX","message":"الرابط","type":"link","media_url":"https://example.com/page"}'
$headers = @{ Authorization = 'Bearer YOUR_INTEGRATION_TOKEN' }
$body = @{
to = '9665XXXXXXXX'
message = 'الرابط'
type = 'link'
media_url = 'https://example.com/page'
} | ConvertTo-Json
Invoke-RestMethod `
-Uri 'https://naabih.com/api/send-message' `
-Method Post `
-Headers $headers `
-ContentType 'application/json; charset=utf-8' `
-Body ([System.Text.Encoding]::UTF8.GetBytes($body))
// احفظ المثال في send.mjs وشغّله في الخادم. احفظ التوكن في متغير بيئة.
const response = await fetch('https://naabih.com/api/send-message', {
method: 'POST',
headers: {
Authorization: 'Bearer ' + process.env.NAABIH_API_TOKEN,
'Content-Type': 'application/json'
},
body: JSON.stringify({
"to": "9665XXXXXXXX",
"message": "الرابط",
"type": "link",
"media_url": "https://example.com/page"
})
});
const result = await response.json();
if (!response.ok) throw new Error(result.code || 'SEND_FAILED');
console.log(result.message_id, result.status);
<?php
$ch = curl_init('https://naabih.com/api/send-message');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('NAABIH_API_TOKEN'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'to' => '9665XXXXXXXX',
'message' => 'الرابط',
'type' => 'link',
'media_url' => 'https://example.com/page'
], JSON_UNESCAPED_UNICODE),
]);
$response = curl_exec($ch);
if ($response === false) throw new RuntimeException(curl_error($ch));
$httpStatus = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$result = json_decode($response, true);
if ($httpStatus >= 400) throw new RuntimeException($result['code'] ?? 'SEND_FAILED');
echo $result['message_id'];
curl -X POST 'https://naabih.com/api/send-message' \
-H 'Authorization: Bearer YOUR_INTEGRATION_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"to":"9665XXXXXXXX","message":"شاهد التفاصيل","type":"image_link","media_url":"https://example.com/image.jpg","link_url":"https://example.com/page"}'
$headers = @{ Authorization = 'Bearer YOUR_INTEGRATION_TOKEN' }
$body = @{
to = '9665XXXXXXXX'
message = 'شاهد التفاصيل'
type = 'image_link'
media_url = 'https://example.com/image.jpg'
link_url = 'https://example.com/page'
} | ConvertTo-Json
Invoke-RestMethod `
-Uri 'https://naabih.com/api/send-message' `
-Method Post `
-Headers $headers `
-ContentType 'application/json; charset=utf-8' `
-Body ([System.Text.Encoding]::UTF8.GetBytes($body))
// احفظ المثال في send.mjs وشغّله في الخادم. احفظ التوكن في متغير بيئة.
const response = await fetch('https://naabih.com/api/send-message', {
method: 'POST',
headers: {
Authorization: 'Bearer ' + process.env.NAABIH_API_TOKEN,
'Content-Type': 'application/json'
},
body: JSON.stringify({
"to": "9665XXXXXXXX",
"message": "شاهد التفاصيل",
"type": "image_link",
"media_url": "https://example.com/image.jpg",
"link_url": "https://example.com/page"
})
});
const result = await response.json();
if (!response.ok) throw new Error(result.code || 'SEND_FAILED');
console.log(result.message_id, result.status);
<?php
$ch = curl_init('https://naabih.com/api/send-message');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('NAABIH_API_TOKEN'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'to' => '9665XXXXXXXX',
'message' => 'شاهد التفاصيل',
'type' => 'image_link',
'media_url' => 'https://example.com/image.jpg',
'link_url' => 'https://example.com/page'
], JSON_UNESCAPED_UNICODE),
]);
$response = curl_exec($ch);
if ($response === false) throw new RuntimeException(curl_error($ch));
$httpStatus = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$result = json_decode($response, true);
if ($httpStatus >= 400) throw new RuntimeException($result['code'] ?? 'SEND_FAILED');
echo $result['message_id'];
متابعة حالة الرسالة
GET /api/messages/:message_id
أرسل Authorization بنفس توكن التكامل الذي أرسل الرسالة. معرّف الرسالة عشوائي ولا يكشف بيانات الحساب.
{
"success": true,
"message_id": "msg_...",
"status": "sent"
}
- queued
- العملية قيد المعالجة.
- sent
- قبل المزود الإرسال.
- delivered
- أكد المزود وصول الرسالة.
- read
- أكد المزود قراءة الرسالة.
- failed
- فشلت العملية.
تظهر delivered وread فقط عند وصول تأكيد من المزود. غياب التأكيد لا يعني أن الرسالة لم تصل.
حالة الاتصال
GET /api/connection
تحقق من جاهزية اتصال واتساب باستخدام نفس Authorization. قيمة provider تكون direct أو meta حسب طريقة الربط.
{
"success": true,
"connected": true,
"provider": "direct",
"status": "connected"
}
منع التكرار
اختياري. استخدم Idempotency-Key إذا كنت تريد منع إرسال نفس العملية مرتين عند إعادة المحاولة.
Idempotency-Key: order-12345
نفس المفتاح مع نفس البيانات يرجع نفس message_id والنتيجة دون إرسال إضافي. استخدم مفتاحًا مختلفًا لكل عملية إرسال مستقلة.
تفاصيل إعادة المحاولة
المفتاح خاص بالتكامل، وطوله من 1 إلى 256 حرفًا. تحفظ النتائج المكتملة 7 أيام على الأقل. تغيير البيانات مع نفس المفتاح يرجع HTTP 409. الطلب المتزامن أثناء الإرسال يرجع HTTP 202 مع نفس message_id؛ هذه عملية قائمة وليست إرسالًا إضافيًا. عند timeout قد يكون المزود استلم الرسالة؛ تبقى الحالة queued إلى أن يتوفر تأكيد، ولا يعاد الإرسال تلقائيًا. تابع الحالة ولا تنشئ مفتاحًا جديدًا تلقائيًا.
Webhooks
إذا أضفت رابط Webhook للتكامل، يرسل نبيه ردود العميل إلى هذا الرابط بطلب POST خلال 72 ساعة من آخر رسالة ناجحة أرسلها التكامل لهذا العميل. كل طلب موقّع بسر خاص بتكاملك، تجده في لوحة التحكم من زر «سر توقيع Webhook».
X-Naabih-Timestamp: 1760000000
X-Signature: sha256=<hex>
التوقيع هو HMAC-SHA256 بسر التكامل على النص timestamp.rawBody. تحقق منه على الجسم كما وصل قبل تحويله إلى JSON، وارفض الطلب إذا كان الوقت أقدم من 5 دقائق.
const crypto = require('crypto');
// rawBody: the request body exactly as received (before JSON parsing)
function isFromNaabih(rawBody, headers, secret) {
const timestamp = headers['x-naabih-timestamp'];
const signature = String(headers['x-signature'] || '');
if (!timestamp || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const expected = 'sha256=' + crypto.createHmac('sha256', secret)
.update(timestamp + '.' + rawBody).digest('hex');
return signature.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}
احفظ السر في الخادم فقط. إذا تسرب، ولّد سرًا جديدًا من لوحة التحكم ثم حدّثه في موقعك.
Rate Limits
توجد حماية تلقائية من الإغراق وكثرة الطلبات غير الطبيعية. عند تجاوز الحد يرجع النظام HTTP 429 مع Retry-After الذي يحدد وقت الانتظار بالثواني.
Retry-After: 60
{
"success": false,
"error": "Too many requests",
"code": "RATE_LIMITED"
}
انتظر المدة المحددة قبل إعادة المحاولة. احتفظ بنفس Idempotency-Key عند استخدامه.
Errors
استخدم code لمعالجة الخطأ، وحقل error لقراءة وصفه.
{
"success": false,
"error": "Target (to) is required",
"code": "INVALID_RECIPIENT"
}
| HTTP | code | الإجراء |
|---|---|---|
| 400 | INVALID_REQUEST | راجع حقول الطلب. |
| 400 | INVALID_RECIPIENT | تحقق من رقم المستلم. |
| 400 | INVALID_MEDIA_URL | تحقق من رابط الوسائط العام. |
| 401 | UNAUTHORIZED | تحقق من Integration Token. |
| 404 | MESSAGE_NOT_FOUND | راجع المعرّف واستخدم توكن التكامل الذي أرسل الرسالة. |
| 409 | IDEMPOTENCY_CONFLICT | لا تغيّر البيانات مع نفس المفتاح. |
| 429 | RATE_LIMITED | انتظر Retry-After. |
| 503 | NOT_CONNECTED | تحقق من اتصال واتساب. |
| 503 | WHATSAPP_NOT_CONNECTED | أعد ربط واتساب. |
| 500 / 503 | SEND_FAILED | تابع حالة العملية قبل تكرار إرسالها. |
OTP API
POST /api/v1/otp/send
نبيه يرسل الكود الذي يولده نظامك فقط. توليد الكود وتخزينه وصلاحيته والتحقق منه مسؤولية نظامك. استخدم نفس Authorization.
{
"phone": "9665XXXXXXXX",
"code": "123456"
}
يمكن إضافة message اختياريًا لتخصيص نص رسالة التحقق.
مثال رسالة مخصصة
{
"phone": "9665XXXXXXXX",
"code": "123456",
"message": "رمز التحقق الخاص بك هو: 123456"
}