وثائق نبيه API

أرسل أول رسالة خلال دقيقة.

اربط نظامك بواتساب باستخدام Integration Token الخاص بك.

  1. 1أنشئ Integration من لوحة التحكم.
  2. 2انسخ Integration Token واحفظه في خادمك.
  3. 3أرسل أول رسالة إلى رقم واتساب.

POST /api/send-message

Request
Authorization: Bearer YOUR_INTEGRATION_TOKEN
Content-Type: application/json

{
  "to": "9665XXXXXXXX",
  "message": "مرحبا",
  "type": "text"
}
Response · 200
{
  "success": true,
  "message_id": "msg_...",
  "status": "sent"
}

احتفظ بـ message_id لمتابعة الحالة. حالة sent تعني قبول الإرسال لدى المزود.

Authentication

استخدم نفس Integration Token في جميع الطلبات. يحدد التوكن التكامل تلقائيًا؛ لا ترسل معرّف الحساب أو التكامل في البيانات.

Header
Authorization: Bearer YOUR_INTEGRATION_TOKEN

احفظ التوكن في الخادم أو متغيرات البيئة. لا تضعه في صفحة عامة أو JavaScript يعمل في متصفح الزائر.

إرسال رسالة

POST /api/send-message

الحقلالاستخدام
toمطلوب. رقم المستلم مع رمز الدولة.
messageنص الرسالة، أو شرح اختياري للوسائط.
typeنوع الرسالة. الافتراضي text.
media_urlرابط عام مطلوب للوسائط. يستخدم أيضًا مع link.
link_urlرابط إضافي مع image_link.

أنواع الرسائل

اختر نوع الرسالة ولغة المثال، وستحصل على طلب كامل جاهز للنسخ والتجربة مباشرة. يجب أن تكون روابط الوسائط عامة وقابلة للوصول. الفيديو مدعوم في نظام البوت وMeta؛ إرسال المستندات متاح عبر نظام البوت.

Text · PowerShell
$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))

متابعة حالة الرسالة

GET /api/messages/:message_id

أرسل Authorization بنفس توكن التكامل الذي أرسل الرسالة. معرّف الرسالة عشوائي ولا يكشف بيانات الحساب.

Response
{
  "success": true,
  "message_id": "msg_...",
  "status": "sent"
}
queued
العملية قيد المعالجة.
sent
قبل المزود الإرسال.
delivered
أكد المزود وصول الرسالة.
read
أكد المزود قراءة الرسالة.
failed
فشلت العملية.

تظهر delivered وread فقط عند وصول تأكيد من المزود. غياب التأكيد لا يعني أن الرسالة لم تصل.

حالة الاتصال

GET /api/connection

تحقق من جاهزية اتصال واتساب باستخدام نفس Authorization. قيمة provider تكون direct أو meta حسب طريقة الربط.

Response
{
  "success": true,
  "connected": true,
  "provider": "direct",
  "status": "connected"
}

منع التكرار

اختياري. استخدم Idempotency-Key إذا كنت تريد منع إرسال نفس العملية مرتين عند إعادة المحاولة.

Optional header · POST /api/send-message
Idempotency-Key: order-12345

نفس المفتاح مع نفس البيانات يرجع نفس message_id والنتيجة دون إرسال إضافي. استخدم مفتاحًا مختلفًا لكل عملية إرسال مستقلة.

تفاصيل إعادة المحاولة

المفتاح خاص بالتكامل، وطوله من 1 إلى 256 حرفًا. تحفظ النتائج المكتملة 7 أيام على الأقل. تغيير البيانات مع نفس المفتاح يرجع HTTP 409. الطلب المتزامن أثناء الإرسال يرجع HTTP 202 مع نفس message_id؛ هذه عملية قائمة وليست إرسالًا إضافيًا. عند timeout قد يكون المزود استلم الرسالة؛ تبقى الحالة queued إلى أن يتوفر تأكيد، ولا يعاد الإرسال تلقائيًا. تابع الحالة ولا تنشئ مفتاحًا جديدًا تلقائيًا.

Webhooks

إذا أضفت رابط Webhook للتكامل، يرسل نبيه ردود العميل إلى هذا الرابط بطلب POST خلال 72 ساعة من آخر رسالة ناجحة أرسلها التكامل لهذا العميل. كل طلب موقّع بسر خاص بتكاملك، تجده في لوحة التحكم من زر «سر توقيع Webhook».

Headers
X-Naabih-Timestamp: 1760000000
X-Signature: sha256=<hex>

التوقيع هو HMAC-SHA256 بسر التكامل على النص timestamp.rawBody. تحقق منه على الجسم كما وصل قبل تحويله إلى JSON، وارفض الطلب إذا كان الوقت أقدم من 5 دقائق.

Node.js
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 الذي يحدد وقت الانتظار بالثواني.

HTTP 429
Retry-After: 60

{
  "success": false,
  "error": "Too many requests",
  "code": "RATE_LIMITED"
}

انتظر المدة المحددة قبل إعادة المحاولة. احتفظ بنفس Idempotency-Key عند استخدامه.

Errors

استخدم code لمعالجة الخطأ، وحقل error لقراءة وصفه.

HTTP 400
{
  "success": false,
  "error": "Target (to) is required",
  "code": "INVALID_RECIPIENT"
}
HTTPcodeالإجراء
400INVALID_REQUESTراجع حقول الطلب.
400INVALID_RECIPIENTتحقق من رقم المستلم.
400INVALID_MEDIA_URLتحقق من رابط الوسائط العام.
401UNAUTHORIZEDتحقق من Integration Token.
404MESSAGE_NOT_FOUNDراجع المعرّف واستخدم توكن التكامل الذي أرسل الرسالة.
409IDEMPOTENCY_CONFLICTلا تغيّر البيانات مع نفس المفتاح.
429RATE_LIMITEDانتظر Retry-After.
503NOT_CONNECTEDتحقق من اتصال واتساب.
503WHATSAPP_NOT_CONNECTEDأعد ربط واتساب.
500 / 503SEND_FAILEDتابع حالة العملية قبل تكرار إرسالها.

OTP API

POST /api/v1/otp/send

نبيه يرسل الكود الذي يولده نظامك فقط. توليد الكود وتخزينه وصلاحيته والتحقق منه مسؤولية نظامك. استخدم نفس Authorization.

Request
{
  "phone": "9665XXXXXXXX",
  "code": "123456"
}

يمكن إضافة message اختياريًا لتخصيص نص رسالة التحقق.

مثال رسالة مخصصة
Optional message
{
  "phone": "9665XXXXXXXX",
  "code": "123456",
  "message": "رمز التحقق الخاص بك هو: 123456"
}