توثيق WhatsApp API

مرجع كامل لواجهة WhatsApp REST API. المصادقة ونقاط النهاية والـ webhooks ورموز الأخطاء وأمثلة الكود.

المصادقة

تتطلب جميع طلبات API مفتاح API يُمرَّر في ترويسة Authorization. يُنشأ مفتاح API الخاص بك عند إنشاء مثيل ويمكنك العثور عليه في لوحة التحكم.

Authorization: Bearer YOUR_API_KEY

تُرجع الطلبات التي لا تحتوي على مفتاح API صالح خطأ 401 Unauthorized. وتكون مفاتيح API مقيدة بنطاق المثيلات — لكل مثيل مفتاحه الخاص.

العنوان الأساسي (Base URL)

https://api2whats.com

جميع نقاط النهاية نسبية إلى هذا العنوان الأساسي. استخدم HTTPS فقط — تُرفض طلبات HTTP.

إرسال رسالة نصية

أرسل رسالة نصية إلى رقم WhatsApp.

POST /send-text

جسم الطلب:

{
  "to": "971501234567",
  "message": "Hello from the API!"
}

المعاملات:

to (سلسلة نصية، إلزامي) — رقم هاتف المستلم مع رمز الدولة، دون + أو مسافات
message (سلسلة نصية، إلزامي) — محتوى نصي، يدعم Unicode والإيموجي

الاستجابة:

{
  "success": true,
  "data": {
    "id": "3EB0A1B2C3D4E5F6",
    "status": "sent"
  }
}

إرسال صورة

أرسل صورة عبر URL أو Base64.

POST /send-image

{
  "to": "971501234567",
  "image": "https://example.com/photo.jpg",
  "caption": "Check out this product!"
}

المعاملات:

to (سلسلة نصية، إلزامي) — رقم هاتف المستلم
image (سلسلة نصية، إلزامي) — عنوان URL للصورة أو سلسلة بترميز Base64
caption (سلسلة نصية، اختياري) — تعليق نصي أسفل الصورة

إرسال فيديو

أرسل ملف فيديو.

POST /send-video

{
  "to": "971501234567",
  "video": "https://example.com/demo.mp4",
  "caption": "Product demo video"
}

إرسال صوت

أرسل ملفاً صوتياً (ملاحظة صوتية أو مقطع صوتي).

POST /send-audio

{
  "to": "971501234567",
  "audio": "https://example.com/voice.mp3"
}

إرسال ملصق

أرسل صورة ملصق (بصيغة WebP أو PNG).

POST /send-sticker

{
  "to": "971501234567",
  "sticker": "https://example.com/sticker.webp"
}

إرسال مستند

أرسل ملفاً مرفقاً (PDF أو DOCX أو XLSX وما إلى ذلك).

POST /send-document

{
  "to": "971501234567",
  "document": "https://example.com/invoice.pdf",
  "filename": "invoice-march-2026.pdf"
}

المعاملات:

to (سلسلة نصية، إلزامي) — رقم هاتف المستلم
document (سلسلة نصية، إلزامي) — عنوان URL للمستند أو سلسلة بترميز Base64
filename (سلسلة نصية، اختياري) — اسم الملف المعروض (الافتراضي هو اسم الملف في URL)

إرسال موقع

أرسل دبوس موقع جغرافي.

POST /send-location

{
  "to": "971501234567",
  "latitude": 25.2048,
  "longitude": 55.2708,
  "name": "Dubai Office"
}

تهيئة Webhook

تتيح الـ webhooks لخادمك استقبال الرسائل الواردة في الوقت الفعلي. عيّن عنوان URL للـ webhook عبر الواجهة:

POST /set-webhook

{
  "url": "https://yourserver.com/webhook"
}

عندما يرسل شخص ما رسالة إلى رقمك المتصل، ترسل الواجهة طلب POST إلى عنوانك:

{
  "event": "message",
  "instance": "instance_abc123",
  "data": {
    "id": "3EB0A1B2C3D4E5F6",
    "from": "971501234567",
    "message": "Hi, I need help",
    "timestamp": 1691234567,
    "type": "text"
  }
}

تحقق من الـ webhooks الواردة باستخدام ترويسة X-Signature المرفقة مع كل طلب.

إدارة المثيلات

تحقق من حالة اتصال مثيل WhatsApp الخاص بك:

GET /instance/status

الاستجابة:
{
  "connected": true,
  "phone": "971501234567",
  "name": "Business Account"
}

رموز الأخطاء

رمز HTTP	رمز الخطأ	الوصف
400	INVALID_PHONE	صيغة رقم الهاتف غير صالحة
400	MISSING_FIELD	حقل إلزامي مفقود من الطلب
401	INVALID_API_KEY	مفتاح API غير صالح أو مفقود
404	INSTANCE_NOT_FOUND	المثيل غير موجود أو غير متصل
429	RATE_LIMIT_EXCEEDED	طلبات كثيرة جداً، تحقق من ترويسة Retry-After
500	INTERNAL_ERROR	خطأ في الخادم، أعد المحاولة مع تراجع أُسّي

حدود المعدل

تختلف حدود المعدل حسب الخطة:

Basic — 100 طلب/دقيقة
Professional — 300 طلب/دقيقة
Enterprise — 1000 طلب/دقيقة

عند تجاوز حد المعدل، تُرجع الواجهة 429 Too Many Requests مع ترويسة Retry-After توضح متى يمكنك إعادة المحاولة.

نماذج الكود

تتوفر أمثلة عملية بـ PHP وPython وJavaScript وcURL في قسم نماذج الكود لدينا. كل نموذج هو سكربت كامل قابل للتشغيل.

ترقيم الصفحات والحدود

عند سرد الموارد (المثيلات وسجل الرسائل)، تدعم الواجهة ترقيم الصفحات عبر معاملات الاستعلام:

GET /messages?page=1&limit=50

الاستجابة:
{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 342,
    "pages": 7
  }
}

حجم الصفحة الافتراضي هو 50، والحد الأقصى 100. استخدم معاملَي الاستعلام page وlimit للتنقل بين النتائج.

الإرسال المجمّع

أرسل رسائل إلى عدة مستلمين في استدعاء API واحد. هذا أكثر كفاءة من إجراء طلبات منفصلة لكل مستلم.

POST /send-batch

{
  "messages": [
    { "to": "971501234567", "message": "Hello Ahmed!" },
    { "to": "971509876543", "message": "Hello Sara!" },
    { "to": "971501112222", "message": "Hello Omar!" }
  ]
}

يطبّق الإرسال المجمّع حدود المعدل تلقائياً. وتتضمن الاستجابة حالة كل رسالة على حدة لتعرف أي الرسائل نجحت وأيها فشلت.

إرشادات رفع الوسائط

عند إرسال الوسائط، اتبع هذه الإرشادات لضمان تسليم مثالي:

Images — JPEG أو PNG، بحد أقصى 5 ميجابايت عبر Base64، والأكبر عبر URL. الأبعاد الموصى بها: 1200x630 للعرض الأفقي و600x600 للمربع.
Videos — بصيغة MP4، بحد أقصى 16 ميجابايت. يُوصى بترميز H.264 للحصول على أفضل توافق.
Documents — PDF وDOCX وXLSX وPPTX وTXT. بحد أقصى 100 ميجابايت عبر URL.
Audio — بصيغة MP3 أو OGG. بحد أقصى 16 ميجابايت.
Stickers — WebP أو PNG، بمقاس 512x512 بكسل، بحد أقصى 500 كيلوبايت.
Locations — إحداثيات خط العرض/خط الطول مع اسم وعنوان اختياريين.

بالنسبة لترميز Base64، أدرج بادئة data URI: data:image/jpeg;base64,/9j/4AAQ.... وبالنسبة لعناوين URL، تأكد من أن العنوان متاح للعامة ويُرجع ترويسة Content-Type الصحيحة.

متغيرات البيئة

خزّن مفتاح API وإعداداتك في متغيرات البيئة، وليس في الكود الخاص بك:

# .env file
WHATSAPP_API_KEY=your_api_key_here
WHATSAPP_API_BASE=https://api2whats.com
WEBHOOK_SECRET=your_webhook_secret_here

لا ترفع ملف .env الخاص بك إلى نظام التحكم بالإصدارات أبداً. أضفه إلى .gitignore. واستخدم إعدادات متغيرات البيئة في منصة النشر لديك في بيئة الإنتاج.

إصدارات الواجهة

تُدار إصدارات الواجهة عبر مسار URL. الإصدار الحالي هو v1 (الافتراضي). وعند إدخال تغييرات جوهرية، سنُطلق إصداراً جديداً ونحافظ على الإصدار القديم لمدة 12 شهراً على الأقل.

# Current version (implicit)
https://api2whats.com/send-text

# Explicit version (future-proof)
https://api2whats.com/v1/send-text

سجل التغييرات

نحتفظ بسجل تغييرات عام لجميع تغييرات الواجهة. اشترك في خلاصة RSS لسجل التغييرات أو تابعنا على GitHub للبقاء على اطلاع. تُعلن التغييرات المهمة عبر البريد الإلكتروني لجميع المستخدمين المسجلين قبل 30 يوماً على الأقل من النشر.

هل تحتاج إلى مساعدة؟

راجع الأسئلة الشائعة للاطلاع على الأسئلة العامة. وبالنسبة للمشكلات المحددة، تواصل مع فريق الدعم لدينا. نرد خلال 24 ساعة.

الأسئلة الشائعة

ما الحد الأقصى لطول الرسالة؟

تدعم الرسائل النصية حتى 4096 حرفاً. وبالنسبة للمحتوى الأطول، فكّر في إرسال مستند أو تقسيم الرسالة على عدة عمليات إرسال.

هل يمكنني إرسال رسائل إلى المجموعات؟

حالياً، تدعم الواجهة المراسلة الفردية (1-1) فقط. والمراسلة الجماعية مدرجة في خارطة الطريق لدينا لإصدار مستقبلي.

ما سرعة تسليم الرسائل؟

تُسلَّم معظم الرسائل خلال 1-3 ثوانٍ. ويعتمد وقت التسليم على اتصال شبكة المستلم وحالة جهازه. تُوضَع الرسائل إلى الأجهزة غير المتصلة في قائمة انتظار من قبل WhatsApp وتُسلَّم عندما يعود الجهاز متصلاً.

هل توجد فئة مجانية؟

يمكنك إنشاء حساب واستكشاف لوحة التحكم مجاناً. تبدأ الخطط المدفوعة من 9.99 دولار/شهر للوصول إلى الواجهة وإرسال الرسائل. تواصل معنا للحصول على وصول تجريبي.

ماذا يحدث إذا تم اختراق مفتاح API الخاص بي؟

ألغِ المفتاح المخترق فوراً من لوحة التحكم وأنشئ مفتاحاً جديداً. وستُنهى جميع الجلسات النشطة التي تستخدم المفتاح القديم. نوصي بتدوير مفاتيح API بشكل دوري وتخزينها في متغيرات البيئة.

هل يمكنني استخدام الواجهة للمراسلة الجماعية؟

Yes, with proper rate limiting. Send messages with 2-3 second delays between them. Do not send identical messages to large groups — personalize each message. Monitor delivery rates and slow down if they drop below 90%. docspage.faq.a6.link

صفحة الحالة

تحقق من حالة نظامنا وسجل التوفر التاريخي في صفحة الحالة لدينا. نقدم تحديثات فورية أثناء الحوادث وننشر تحليلات لاحقة مفصلة لأي انقطاعات في الخدمة.

هل أنت مستعد للتكامل؟

أنشئ حساباً وابدأ إرسال الرسائل خلال دقائق.

ابدأ مجاناً