توثيق واجهة API

ابدأ الاتصال بواتساب. تُرجِع رمز QR إذا لم تتم المصادقة.

الاستجابة (يلزم رمز QR)

{
    "success": true,
    "data": {
        "status": "qr_ready",
        "qr": "2@ABC123...base64-qr-data..."
    }
}

الاستجابة (تمت المصادقة مسبقًا)

{
    "success": true,
    "data": {
        "status": "connecting",
        "message": "Reconnecting with saved credentials"
    }
}

اقطع جلسة واتساب (مع الاحتفاظ ببيانات الاعتماد لإعادة الاتصال).

الاستجابة

{
    "success": true,
    "message": "Disconnected successfully"
}

تسجيل الخروج من واتساب ومسح جميع بيانات الجلسة.

الاستجابة

{
    "success": true,
    "message": "Logged out successfully"
}

أرسل رسالة نصية إلى رقم واتساب.

جسم الطلب

{
    "to": "968XXXXXXXX",
    "message": "Hello from WA-Connect!"
}

الاستجابة

{
    "success": true,
    "data": {
        "message_id": "3EB0XXXXX",
        "to": "968XXXXXXXX@s.whatsapp.net",
        "status": "sent",
        "timestamp": "2026-02-27T10:00:00.000Z"
    }
}

أرسل صورة مع تعليق اختياري.

جسم الطلب

{
    "to": "968XXXXXXXX",
    "imageUrl": "https://example.com/image.jpg",
    "caption": "Check this out!"  // optional
}

الاستجابة

{
    "success": true,
    "data": {
        "message_id": "3EB0XXXXX",
        "to": "968XXXXXXXX@s.whatsapp.net",
        "status": "sent"
    }
}

أرسل مستندًا/ملفًا.

جسم الطلب

{
    "to": "968XXXXXXXX",
    "documentUrl": "https://example.com/document.pdf",
    "mimetype": "application/pdf",
    "fileName": "Invoice.pdf",
    "caption": "Here is your invoice"  // optional
}

الاستجابة

{
    "success": true,
    "data": {
        "message_id": "3EB0XXXXX",
        "to": "968XXXXXXXX@s.whatsapp.net",
        "status": "sent"
    }
}

أرسل مقطع فيديو مع تعليق اختياري.

جسم الطلب

{
    "to": "968XXXXXXXX",
    "videoUrl": "https://example.com/video.mp4",
    "caption": "Watch this!"  // optional
}

الاستجابة

{
    "success": true,
    "data": {
        "message_id": "3EB0XXXXX",
        "to": "968XXXXXXXX@s.whatsapp.net",
        "status": "sent"
    }
}

أرسل ملفًا صوتيًا أو رسالة صوتية.

جسم الطلب

{
    "to": "968XXXXXXXX",
    "audioUrl": "https://example.com/audio.mp3",
    "ptt": false  // set to true for voice note
}

الاستجابة

{
    "success": true,
    "data": {
        "message_id": "3EB0XXXXX",
        "to": "968XXXXXXXX@s.whatsapp.net",
        "status": "sent"
    }
}

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

جسم الطلب

{
    "to": "968XXXXXXXX",
    "latitude": 23.5880,
    "longitude": 58.3829,
    "name": "Muscat, Oman",       // optional
    "address": "Muscat, Oman"     // optional
}

الاستجابة

{
    "success": true,
    "data": {
        "message_id": "3EB0XXXXX",
        "to": "968XXXXXXXX@s.whatsapp.net",
        "status": "sent"
    }
}

أرسل بطاقة جهة اتصال (vCard).

جسم الطلب

{
    "to": "968XXXXXXXX",
    "contactName": "John Doe",
    "contactPhone": "+96899999999"
}

الاستجابة

{
    "success": true,
    "data": {
        "message_id": "3EB0XXXXX",
        "to": "968XXXXXXXX@s.whatsapp.net",
        "status": "sent"
    }
}

أرسل الرسالة نفسها إلى عدة مستلمين.

جسم الطلب

{
    "recipients": ["968XXXXXXXX", "968YYYYYYYY", "968ZZZZZZZZ"],
    "message": "Hello everyone!",
    "delay": 1000  // optional, delay between messages in ms (default: 1000)
}

الاستجابة

{
    "success": true,
    "data": {
        "total": 3,
        "successful": 3,
        "failed": 0,
        "results": [
            { "to": "968XXXXXXXX", "success": true, "message_id": "3EB0XXX" },
            { "to": "968YYYYYYYY", "success": true, "message_id": "3EB0YYY" },
            { "to": "968ZZZZZZZZ", "success": true, "message_id": "3EB0ZZZ" }
        ]
    }
}

أرسل قالبًا. يقبل params كمصفوفة (حسب الموضع) أو ككائن مرقَّم.

الجسم — صيغة المصفوفة

{
    "to": "96812345678",
    "language": "ar",
    "params": ["123456"]
}

الجسم — صيغة الكائن المرقَّم

{
    "to": "96812345678",
    "language": "ar",
    "params": {
        "1": "Ahmed",
        "2": "1234",
        "3": "150 SAR"
    }
}

تُحلَّل مفاتيح صيغة الكائن كأعداد صحيحة وتُرتَّب، فيكون {"2":"b","1":"a"} مكافئًا لـ ["a","b"]. وتصبح الأرقام الوسطية المفقودة سلاسل نصية فارغة.

الجسم — معاملات الترويسة والأزرار

{
    "to": "96812345678",
    "language": "ar",
    "params": { "1": "Ahmed", "2": "8656", "3": "A13322257" },
    "header_params": { "1": "إشعار إنشاء شحنة" },
    "button_params": { "0": ["8656"] }
}

يملأ header_params العنصر {{1}} في الترويسة — سواء كمصفوفة حسب الموضع أو ككائن مرقَّم، وكلاهما مقبول. ويملأ button_params لواحق أزرار الروابط الديناميكية — المفاتيح هي فهارس الأزرار ("0"، "1"…)، والقيم هي معاملات ذلك الزر؛ كما تُقبل صيغة المصفوفة ضمن مصفوفة حسب الموضع [["8656"]]. وكلا الحقلين اختياري ويمكن قراءتهما أيضًا بصيغة camelCase (headerParams / buttonParams). والطلبات التي لا تتضمنهما تعمل تمامًا كما في السابق (مكوّن الجسم فقط). أما قالب الترويسة المتغيّرة المُرسَل دون header_params فترفضه Meta بالرمز #132000 — ولا يُملأ تلقائيًا عن قصد، حتى تظهر القيمة المفقودة بدلًا من التخمين.

الاستجابة

{
    "success": true,
    "data": {
        "messaging_product": "whatsapp",
        "messages": [{ "id": "wamid.HB..." }],
        "sent_at": "2026-07-23T10:15:00.000Z"
    }
}

يُطلَق عند استقبال رسالة جديدة.

الحمولة

{
    "event": "message.received",
    "timestamp": "2026-02-27T10:00:00.000Z",
    "data": {
        "message_id": "3EB0XXXXX",
        "from": "968XXXXXXXX@s.whatsapp.net",
        "from_name": "John Doe",
        "type": "text",
        "content": "Hello!",
        "media_url": null,
        "is_group": false,
        "timestamp": "2026-02-27T10:00:00.000Z"
    }
}

يُطلَق عند إرسال رسالة بنجاح.

الحمولة

{
    "event": "message.sent",
    "timestamp": "2026-02-27T10:00:00.000Z",
    "data": {
        "message_id": "3EB0XXXXX",
        "to": "968XXXXXXXX@s.whatsapp.net",
        "type": "text",
        "content": "Hello!",
        "status": "sent"
    }
}

يُطلَق عند تحديث حالة تسليم الرسالة.

الحمولة

{
    "event": "message.status",
    "timestamp": "2026-02-27T10:00:00.000Z",
    "data": {
        "message_id": "3EB0XXXXX",
        "remote_jid": "968XXXXXXXX@s.whatsapp.net",
        "status": "delivered"  // "sent", "delivered", "read", "failed"
    }
}

يُطلَق عند اتصال جلسة واتساب.

الحمولة

{
    "event": "connection.connected",
    "timestamp": "2026-02-27T10:00:00.000Z",
    "data": {
        "status": "connected",
        "phone_number": "968XXXXXXXX",
        "wa_name": "Your Name"
    }
}

يُطلَق عند قطع جلسة واتساب.

الحمولة

{
    "event": "connection.disconnected",
    "timestamp": "2026-02-27T10:00:00.000Z",
    "data": {
        "status": "disconnected",
        "reason": "logout"
    }
}

يُطلَق عند استقبال مكالمة واردة.

الحمولة

{
    "event": "call.incoming",
    "timestamp": "2026-02-27T10:00:00.000Z",
    "data": {
        "from": "968XXXXXXXX@s.whatsapp.net",
        "call_id": "CALL_ID_HERE",
        "is_video": false
    }
}

تحقق مما إذا كان رقم هاتف مسجَّلًا على واتساب.

جسم الطلب

{
    "phone": "968XXXXXXXX"
}

الاستجابة (الرقم على واتساب)

{
    "success": true,
    "exists": true,
    "message": "Number is on WhatsApp",
    "contact": {
        "jid": "968XXXXXXXX@s.whatsapp.net",
        "phone": "968XXXXXXXX",
        "name": "John Doe"
    }
}

الاستجابة (الرقم ليس على واتساب)

{
    "success": true,
    "exists": false,
    "message": "Number is not on WhatsApp"
}

ابدأ مزامنة يدوية لجهات الاتصال من واتساب. ملاحظة: تتم مزامنة جهات الاتصال تلقائيًا عند اتصال واتساب.

الاستجابة

{
    "success": true,
    "message": "Contacts are synced automatically when WhatsApp connects."
}