📱 WhatsApp Cloud API
يتم ربط WhatsApp عبر API Cloud من Meta — واجهة برمجة التطبيقات الرسمية المتاحة بالمستوى المجاني التي تتيح لك إرسال واستقبال رسائل WhatsApp من خادمك الخاص. لا حاجة لمزود حلول أعمال (BSP) من طرف ثالث.
المتطلبات الأساسية
- حساب مطور Meta على developers.facebook.com
- حساب Meta Business (المعروف أيضاً بـ Business Manager)
- رقم هاتف لـ WhatsApp غير مسجل بالفعل على WhatsApp الشخصي (يمكنك استخدام شريحة SIM أو رقم افتراضي أو هاتف أرضي)
خطوات الإعداد
1. إنشاء تطبيق Meta
- اذهب إلى developers.facebook.com/apps
- انقر على Create App
- اختر النوع Business
- أدخل اسماً واربط حساب Business الخاص بك
2. إضافة منتج WhatsApp
- في لوحة تحكم تطبيقك، انتقل إلى Add Products to Your App
- انقر على Set Up في WhatsApp
- اختر حساب Business الخاص بك
3. الحصول على بيانات الاعتماد
انتقل إلى WhatsApp → API Setup في لوحة تحكم تطبيقك:
| بيانات الاعتماد | أين تجدها |
|---|---|
| Phone Number ID | مدرج في قسم "From" — معرف رقمي مثل 123456789012345 |
| Access Token | الرمز المؤقت المعروض في هذه الصفحة. للإنتاج، أنشئ رمزاً دائماً عبر System Users. |
| App Secret | لوحة تحكم التطبيق → Settings → Basic → App Secret |
| Verify Token | سلسلة تختارها بنفسك — أي سلسلة عشوائية، مثل my_secret_verify_token_2024 |
4. إضافة القناة في PulseHub
- اذهب إلى القنوات → إضافة قناة
- اختر WhatsApp
- املأ الحقول الأربعة
- انقر على حفظ القناة
- انسخ عنوان URL الخاص بالـ Webhook المعروض على بطاقة القناة
5. تكوين Webhook في Meta
- في تطبيق Meta الخاص بك، اذهب إلى WhatsApp → Configuration
- انقر على Edit بجانب قسم Webhook
- Callback URL: الصق عنوان URL الخاص بـ webhook في PulseHub
- Verify Token: أدخل نفس السلسلة التي وضعتها في PulseHub
- انقر على Verify and Save
ستقوم Meta بإرسال طلب GET إلى عنوان URL الخاص بالـ webhook مع ?hub.mode=subscribe&hub.verify_token=...&hub.challenge=.... يتحقق PulseHub من الرمز ويعيد التحدي.
- ضمن Webhook Fields، اشترك في: messages
6. الاختبار
أرسل رسالة WhatsApp إلى رقم عملك. يجب أن تظهر كمحادثة جديدة في صندوق الوارد في PulseHub خلال ثوانٍ.
التحقق من التوقيع
تضمّن Meta ترويسة X-Hub-Signature-256 في كل webhook:
X-Hub-Signature-256: sha256=abc123...
يتحقق PulseHub منها باستخدام HMAC-SHA256 مع App Secret الخاص بك. إذا فشل التحقق، يُرجع webhook 401 Signature mismatch.
إرسال الرسائل
عندما يرسل وكيل رداً من صندوق الوارد، يستدعي PulseHub واجهة WhatsApp Cloud API:
POST https://graph.facebook.com/v18.0/{phone_number_id}/messages
Authorization: Bearer {access_token}
{
"messaging_product": "whatsapp",
"to": "{recipient_phone}",
"type": "text",
"text": {"body": "ردك هنا"}
}
الوصول إلى الإنتاج
تطبيق Meta الافتراضي في وضع Development — يمكنه فقط إرسال رسائل إلى أرقام مضافة كأرقام اختبار. للانتقال إلى البث المباشر:
- أكمل التحقق من الأعمال في Meta Business Manager
- قدم حالة استخدام WhatsApp الخاصة بك لـ مراجعة Meta
- بمجرد الموافقة، يحصل تطبيقك على صلاحية إرسال رسائل لجميع مستخدمي WhatsApp
المشاكل الشائعة
| العرض | السبب المحتمل |
|---|---|
| فشل التحقق أثناء إعداد webhook | verify_token في PulseHub لا يتطابق مع ما أدخلته في Meta |
| خطأ عدم تطابق التوقيع في السجلات | app_secret خاطئ — انسخه من App Settings → Basic، وليس من API Setup |
| الرسائل لا تصل | حقل webhook messages غير مشترك في لوحة تحكم Meta |
Invalid phone number عند الإرسال | يجب أن يكون تنسيق الرقم E.164 بدون + (مثل 15551234567) |
| خطأ التطبيق في وضع Development | فقط أرقام الاختبار المحققة يمكنها استقبال الرسائل في وضع dev |