اربط رقم WhatsApp Business عبر بيانات اعتماد Meta Cloud API وwebhooks موقّعة.
اربط رقم WhatsApp Business عبر بيانات اعتماد Meta Cloud API وwebhooks موقّعة.
تجهيز تطبيق Meta والرقم#
اتبع دليل البدء الرسمي لـ WhatsApp Cloud API من Meta لإنشاء تطبيق Meta أو اختيار تطبيق موجود، وإضافة منتج WhatsApp، وربط حساب WhatsApp Business (WABA) ورقم الهاتف به.
اجمع هذه القيم الثلاث من التطبيق والرقم نفسيهما:
| حقل Make Agent Fast | القيمة لدى المزوّد | ملاحظات |
|---|---|---|
| Phone number ID | معرّف رقم الهاتف (Phone Number ID) الرقمي | ليس رقم الهاتف الظاهر الذي يبدأ بـ + ولا معرّف WABA |
| Access token | رمز وصول Cloud API | تنتهي صلاحية الرموز المؤقتة في لوحة التحكم؛ استخدم رمز مستخدم نظام (system-user) طويل الأمد مناسبًا للإنتاج |
| App secret | السر الخاص بتطبيق Meta | سر سداسي عشري من 32 حرفًا يُستخدم للتحقق من توقيع webhook |
امنح الأذونات اللازمة فقط للرقم وسير عمل المراسلة. وأبقِ أصول التطوير والاختبار منفصلة عن رقم الإنتاج.
حفظ بيانات الاعتماد والتحقق منها#
افتح صفحة القنوات الخاصة بالوكيل، واختر WhatsApp، وأدخل القيم الثلاث، ثم فعّل الرد بالصوت إذا لزم الأمر، واختر اتصال.
يتحقق Make Agent Fast من الرقم عبر Graph API باستخدام رمز الوصول مع appsecret_proof؛ وبذلك يُكتشف أي خطأ في الرقم أو الرمز أو سر التطبيق قبل بدء وصول حركة webhook. بعد ذلك تعرض بطاقة الموصل Webhook URL وVerify token فريدين.
إعداد webhook في Meta#
في تطبيق Meta نفسه:
- افتح إعدادات webhook الخاصة بـ WhatsApp.
- الصق Webhook URL الخاص بالموصل بوصفه عنوان callback.
- الصق Verify token الخاص بالموصل كما هو تمامًا؛ فهو حساس لحالة الأحرف.
- أكمل عملية التحقق.
- اشترك بحساب WhatsApp Business أو الرقم في حقل webhook المسمى
messages. - تأكد من أن التطبيق وأصول النشاط التجاري متاحة للمستخدمين المقصودين للاختبار أو الإنتاج.
يثبت verify token ملكيتك أثناء طلب التحقق GET. أما طلبات POST أثناء التشغيل فتُصادَق بشكل منفصل عبر توقيع سر تطبيق Meta؛ فلا تستبدل أحدهما بالآخر.
اختبار النص والصوت#
أرسل رسالة أولًا من رقم اختبار مسموح به. في وضع التطوير لدى Meta قد لا يتمكن المستخدمون غير المسجلين من الوصول إلى التطبيق. تأكد من ظهور المحادثة والقناة في المحادثات، وراقب آخر رسالة في بطاقة الموصل.
الرسائل النصية والصوتية الواردة مدعومة. عند تفعيل الرد بالصوت وإعداد خدمة الكلام، يرفع Make Agent Fast الصوت المُنشأ عبر Cloud API ويرسله مع الرد النصي. أما الصور والمواقع وجهات الاتصال وأنواع الرسائل الأخرى غير المدعومة فتُتجاهل.
الجاهزية للإنتاج#
قبل الإعلان عن الرقم، أكمل الخطوات التي تفرضها Meta لحالتك: توثيق النشاط التجاري، ومراجعة التطبيق، واسم العرض، والقوالب، وسياسة المراسلة. هذه المتطلبات تحددها Meta وقد تتغير بمعزل عن Make Agent Fast.
استخدم بيانات اعتماد إنتاجية لها مالك محدد وإجراء واضح لانتهاء الصلاحية والتدوير. سجّل تطبيق Meta ومستخدم النظام وWABA وPhone Number ID الخاصة بهذا الموصل، حتى يتمكن المشغّل من تدويرها دون تخمين.
التدوير أو قطع الاتصال#
أنشئ رمزًا بديلًا بصلاحيات الوصول إلى الأصول نفسها، ثم حدّث الموصل، وأرسل رسالة اختبار، وبعد ذلك فقط ألغِ الرمز القديم. وإذا تغيّر سر التطبيق، فحدّثه في Make Agent Fast فورًا، وإلا فستفشل كل طلبات webhook الواردة الموقّعة.
لا يؤدي تعطيل الموصل أو إزالته إلى إلغاء اشتراك webhook في Meta أو حذف إعداده. أزل الاشتراك لدى المزوّد أيضًا عند إيقاف الرقم نهائيًا.
استكشاف الأخطاء وإصلاحها#
| العَرَض | الحل |
|---|---|
| رفض بيانات الاعتماد | تأكد من أن الرمز يستطيع قراءة Phone Number ID المحدد بدقة، وأن سر التطبيق من التطبيق نفسه |
| تعذّر تحقق Meta من callback | استخدم عنوان HTTPS المنسوخ وverify token الصحيح تمامًا، وتأكد من أن الموصل لا يزال موجودًا |
| نجح التحقق لكن لا تصل أي رسائل | اشترك في messages، وتحقق من ربط WABA والرقم، ووضع التطبيق، وصلاحية وصول مستخدمي الاختبار، وسجلات التسليم لدى المزوّد |
| ترجع webhooks الخطأ unauthorized | أعد إدخال سر التطبيق الصحيح؛ فتوقيعات POST في Meta لا تستخدم verify token |
| فشل الردود الصادرة | تحقق من انتهاء صلاحية الرمز، وأذونات الرقم، وسياسة المستلم أو نافذة المراسلة، وأخطاء Graph API |
| يعمل النص لكن يفشل الصوت | تحقق من مفاتيح مزوّد تحويل الكلام إلى نص/نص إلى كلام، ومن صلاحية الرمز لرفع الوسائط وتنزيلها |
لا تكشف رمز الوصول أو سر التطبيق في شيفرة المتصفح أبدًا. استخدم Public API من خادم موثوق فقط عند أتمتة إنشاء الموصلات.