بعد تسجيل حساب مطور Meta والحصول على مفتاح API، لاستدعاء نقطة النهاية الرسمية (مثل https://graph.facebook.com/v19.0/<PHONE_NUMBER_ID>/messages) باستخدام طلب POST، يجب حمل رؤوس Authorization: Bearer <ACCESS_TOKEN> و Content-Type: application/json، وإرسال رسالة بتنسيق JSON (مثال: {"messaging_product":"whatsapp","to":"886912345678","text":{"body":"رسالة اختبار"}}). لاحظ أن حد التردد هو 200 رسالة في الثانية.

تسجيل الحساب والحصول على الشهادة

وفقًا للبيانات الرسمية لـ Meta، تستخدم حاليًا أكثر من 5 ملايين شركة واجهة برمجة تطبيقات WhatsApp Business للتواصل مع العملاء، بمتوسط ​​وقت استجابة محسّن إلى في غضون 3 دقائق، ومعدل فتح رسائل يصل إلى 98%. تستغرق عملية التسجيل عادةً 1-3 أيام عمل، ولكن اختيار قناة الموزع يمكن أن يقللها إلى أقل من ساعتين. فيما يلي تفاصيل التشغيل المحددة:

اذهب أولاً إلى منصة المطورين الرسمية لـ Meta (developers.facebook.com)، وانقر على “إنشاء تطبيق” واختر نوع “الأعمال”. سيطلب منك النظام ملء اسم التطبيق (يوصى باستخدام اسم الشركة باللغة الإنجليزية)، والبريد الإلكتروني للاتصال (يجب أن يتطابق مع نطاق الشركة)، واختيار “WhatsApp” كمنتج رئيسي. هنا، يجب ملاحظة أن اسم التطبيق لا يمكن تعديله بمجرد تقديمه، ويمكن لكل حساب أعمال إنشاء 5 تطبيقات كحد أقصى. بعد الانتهاء من التسجيل الأساسي، ستنشئ المنصة معرف تطبيق مكون من 64 حرفًا (App ID) و مفتاح سري مكون من 32 حرفًا (App Secret). يجب تنزيل وحفظ هذين الكودين على الفور، لأن المفتاح السري يظهر مرة واحدة فقط.

الخطوة التالية هي إجراء التحقق التجاري. يجب على الشركة تحميل مستندات تجارية رسمية (شهادة تسجيل تجاري، شهادة تسجيل ضريبي، أو شهادة تسجيل شركة). تنسيق الملفات يقتصر على PDF/JPG/PNG، وحجمها لا يتجاوز 5 ميجابايت. يستغرق وقت المراجعة عادةً 24-72 ساعة، ولكن إذا اخترت التعاون مع مزود حلول أعمال (BSP) معتمد، فيمكنك تخطي هذه الخطوة واستخدام قناتهم السريعة مباشرةً. بعد اجتياز التحقق، سيقوم النظام بتنشيط صلاحيات الوصول إلى API وتوفير رمز وصول أساسي دائم الصلاحية (Access Token). هذا الرمز الافتراضي صالح لمدة 90 يومًا، ولكن يمكن تمديده من خلال آلية التحديث الدورية.

بعد الحصول على الرمز الأساسي، تحتاج أيضًا إلى ربط رقم هاتف. يمكن لكل تطبيق ربط 25 رقمًا كحد أقصى. يجب أن يكون الرقم رقمًا فعليًا لم يتم تسجيله في WhatsApp Business من قبل (يوصى بشراء بطاقة SIM جديدة). يتطلب الربط دفع رسوم شهرية ثابتة (حوالي 0.5-5 دولار أمريكي حسب الدولة) وتلقي رمز تحقق مكون من 6 أرقام عبر رسالة نصية أو مكالمة صوتية. بعد الانتهاء من الربط، ستنشئ المنصة عنوان URL مخصص لنقطة نهاية API (يحتوي على معلمة مشفرة مكونة من 128 بت). هذا URL هو الشهادة الأساسية لجميع استدعاءات API اللاحقة.

أخيرًا، يجب إعداد Webhook لتلقي الرسائل. يجب أن يدعم الخادم بروتوكول HTTPS وأن يكون مُكوَّنًا بتشفير TLS 1.2 أو أعلى. يمكن تعيين الحد الأدنى للفاصل الزمني لدفع كل رسالة إلى 100 مللي ثانية. يوصى بتكوين موازن تحميل مسبقًا. تطلب Meta رسميًا أن يكون وقت استجابة الخادم أقل من 300 مللي ثانية، وإلا سيتم تشغيل آلية إعادة المحاولة (بحد أقصى 3 مرات إعادة محاولة، بفاصل زمني 5 دقائق في كل مرة). بعد الانتهاء من جميع الإعدادات، تذكر تشغيل “وضع تصحيح أخطاء API” في الخلفية، والذي سيسجل البيانات الأولية بتنسيق JSON لجميع الطلبات، مما يسهل استكشاف المشكلات لاحقًا. التكلفة الإجمالية للعملية حوالي 15-50 دولارًا أمريكيًا (باستثناء الرسوم الشهرية للرقم). إذا تم التعامل معها من خلال موزع، فعادةً ما يتم إضافة رسوم خدمة فنية لمرة واحدة بقيمة 50-100 دولار أمريكي.

إعداد صلاحيات الوصول إلى API

وفقًا لإحصائيات Meta الرسمية، فإن أكثر من 30% من فشل استدعاءات API ينبع من أخطاء في تكوين الصلاحيات. يمكن أن يؤدي التكوين الصحيح للصلاحيات إلى رفع معدل تسليم الرسائل من متوسط 75% إلى 99.8%، وتقليل سرعة الاستجابة إلى أقل من 500 مللي ثانية. يتضمن إعداد الصلاحيات 4 مستويات أساسية: مستوى الأعمال (Business Level)، مستوى التطبيق (App Level)، مستوى الرقم (Phone Level)، ومستوى الميزة (Feature Level). يتطلب كل مستوى صلاحية مراجعة مستقلة، ويستغرق إجمالي وقت المراجعة حوالي 2-6 ساعات. فيما يلي تفاصيل التشغيل المحددة:

ادخل أولاً إلى واجهة Meta for Developers الخلفية، وابحث عن علامة التبويب “الصلاحيات” في “إعدادات التطبيق”. ستعرض هنا 13 مفتاح تبديل للصلاحيات الأساسية. تتضمن الصلاحيات الأساسية التي يجب تشغيلها: messages (إرسال واستقبال الرسائل)، contacts (قراءة جهات الاتصال)، webhooks (خطافات الويب)، و message_templates (رسائل القوالب). يتطلب تشغيل كل صلاحية تقديمها للمراجعة بشكل منفصل. مراجعة صلاحية رسائل القوالب هي الأكثر صرامة، وعادة ما تتطلب توفير 3 رسائل محتوى افتراضية على الأقل (بحد أقصى 1024 حرفًا لكل رسالة) وشرح تردد الإرسال (مثل إرسال 200 رسالة كحد أقصى في الساعة).

يجب إيلاء اهتمام خاص لعملية ربط صلاحية رقم الهاتف. يجب ربط كل رقم بصلاحيات تشغيل API المقابلة، بما في ذلك: القدرة على إرسال ملفات الوسائط المتعددة (صور/فيديوهات/مستندات)، القدرة على إجراء مكالمات صوتية، والقدرة على إرسال معلومات الموقع. صلاحية الوسائط المتعددة تكون مغلقة افتراضيًا. يتطلب تشغيلها تحميل وصف لنوع الملف (مثل اقتصار على تنسيق jpg/png، بحد أقصى 16 ميجابايت للملف الواحد). صلاحية المكالمات الصوتية متاحة فقط للحسابات التي اجتازت التحقق التجاري، وتبلغ الحد الأدنى لتكلفة كل مكالمة 0.015 دولار أمريكي.

إعداد Webhook هو النقطة الرئيسية في تكوين الصلاحيات. يجب ملء حقل “خطافات الويب” بعنوان URL للرد عبر HTTPS المعد مسبقًا (يوصى باستخدام خادم وكيل عكسي Nginx)، وتعيين 6 أنواع من الأحداث المراد تلقيها: message (تلقي الرسائل)، status (تحديث الحالة)، template (حالة القالب)، contact (تغيير جهة الاتصال)، location (تحديث الموقع)، error (سجل الأخطاء). يجب أن يستجيب الخادم برمز حالة 200 OK في غضون 3 ثوانٍ، وإلا سيقوم خادم Meta بتشغيل آلية إعادة المحاولة (بحد أقصى 5 مرات إعادة محاولة، بفاصل زمني 15 دقيقة في كل مرة).

فيما يلي معايير إعداد المعلمات لفئات الصلاحيات الرئيسية:

في “الإعدادات المتقدمة”، يمكنك تخصيص الحد الأقصى لاستدعاء API في الدقيقة/الساعة/اليوم. القيمة الافتراضية هي 1000 طلب في الدقيقة (يمكن زيادتها إلى 10000 طلب في الدقيقة بناءً على احتياجات العمل). يوصى بتشغيل وضع التوسع التلقائي. عندما يتجاوز حجم الطلبات 80% من القيمة المحددة لمدة 5 دقائق متتالية، سيقوم النظام تلقائيًا بزيادة حصة السعة بنسبة 20%. يتم تسجيل جميع تغييرات الصلاحيات فورًا في سجل التدقيق، ويمكن تتبع جميع عمليات التشغيل التي تمت خلال 180 يومًا. بعد الانتهاء من الإعداد، تأكد من النقر على زر “محاكاة اختبار الصلاحيات”. سيقوم النظام تلقائيًا بتشغيل 25 عنصر اختبار. يستغرق وقت الاختبار حوالي 8 دقائق، ويجب أن يكون معدل النجاح 100% لتفعيل خدمة API رسميًا.

كتابة كود إرسال الرسائل

وفقًا للإحصائيات الفعلية لواجهة برمجة تطبيقات WhatsApp Business، يمكن أن يؤدي الكود المُحسَّن بشكل صحيح إلى رفع معدل تسليم الرسائل من 92% إلى 99.7%، وتقليل متوسط وقت الاستجابة إلى أقل من 800 مللي ثانية. تتضمن وحدة الإرسال القياسية عادة 5 وحدات أساسية: وحدة المصادقة (Authentication)، وحدة بناء الحمولة (Payload Building)، وحدة التشفير (Encryption)، وحدة الإرسال (Dispatching)، وآلية إعادة المحاولة (Retry Mechanism). يجب أن يتم التحكم في وقت تنفيذ كل وحدة ليكون أقل من 200 مللي ثانية.

في وحدة المصادقة، يجب تضمين 3 معلمات رئيسية في رأس كل طلب HTTP: يجب أن يستخدم رأس Authorization تنسيق Bearer Token (بطول 64 حرفًا)، ويجب تعيين Content-Type على application/json، ويجب تضمين رقم إصدار API (مثل v17.0). عادة ما يكون الرمز صالحًا لمدة 24 ساعة. بعد انتهاء الصلاحية، يجب تحديثه من خلال عملية OAuth 2.0 (صلاحية رمز التحديث هي 60 يومًا). يوصى بتنفيذ آلية تحديث الرمز التلقائي في الكود. عندما يتم الكشف عن رمز الخطأ 401، يتم تشغيل عملية التحديث تلقائيًا. تستغرق هذه العملية عادة 1500 مللي ثانية للإكمال.

تتطلب وحدة بناء الحمولة الالتزام الصارم بهيكل JSON المحدد من قبل Meta. تتضمن حمولة الرسائل النصية القياسية 12 حقلًا إلزاميًا و 8 حقول اختيارية، ويجب ألا يتجاوز الحجم الإجمالي 10 كيلوبايت. فيما يلي مقارنة لهياكل أنواع الرسائل الرئيسية:

انتبه بشكل خاص: يجب تحميل جميع ملفات الوسائط أولاً إلى خادم Meta للحصول على معرف الوسائط (بطول 26 حرفًا). تستغرق عملية التحميل هذه عادة 3-5 ثوانٍ (حسب حجم الملف). معرف الوسائط الذي تم الحصول عليه صالح لمدة 30 يومًا ويمكن إعادة استخدامه.

تتطلب وحدة التشفير استخدام بروتوكول TLS 1.2 أو أعلى لإجراء التشفير من طرف إلى طرف. يوصى باستخدام خوارزمية AES-256-GCM لتشفير نص الرسالة، ويجب أن يصل طول المفتاح إلى 256 بت. يتطلب كل طلب إنشاء متجه تهيئة فريد (IV، بطول 12 بايت) وعلامة مصادقة (Authentication Tag، بطول 16 بايت). يجب أن تتم عملية التشفير محليًا، ويجب أن يتم التحكم في التأخير الإضافي الناتج عن عملية التشفير وفك التشفير بأكملها ليكون أقل من 300 مللي ثانية.

تحتاج وحدة الإرسال إلى معالجة مشكلات عدم استقرار الشبكة. يوصى بتعيين آلية مهلة من 3 طبقات: تعيين مهلة الاتصال (Connect Timeout) على 3 ثوانٍ، مهلة الإرسال (Write Timeout) على 5 ثوانٍ، ومهلة القراءة (Read Timeout) على 10 ثوانٍ. عندما يُرجع الخادم خطأ 5xx، يجب تشغيل آلية إعادة المحاولة فورًا (بحد أقصى 3 مرات إعادة محاولة، مع زيادة الفاصل الزمني: الثانية الأولى 2 ثانية، الثانية 4 ثوانٍ، الثالثة 8 ثوانٍ). في الوقت نفسه، يجب مراقبة تردد استدعاء API، والالتزام الصارم بحد معدل الرسائل الأساسي البالغ رسالة واحدة في الثانية (يمكن التقدم لزيادته إلى 5 رسائل في الثانية).

اختبار عملية الإرسال

وفقًا للبيانات الفعلية في الصناعة، فإن أنظمة إرسال رسائل WhatsApp التي لم يتم اختبارها بشكل كافٍ تسجل متوسط ​​معدل فشل في التسليم يبلغ 12%، بينما يمكن للأنظمة التي خضعت لعملية اختبار كاملة تقليل معدل الفشل إلى أقل من 0.3%. تتطلب دورة الاختبار الكاملة عادة 72 ساعة، وتتضمن 3 مراحل رئيسية: اختبار الوحدة (يجب أن تصل التغطية إلى 95%)، اختبار التكامل (محاكاة 1000 مستخدم متزامن)، واختبار الضغط (التشغيل المستمر لمدة 24 ساعة). تتطلب عملية الاختبار مراقبة 17 مؤشرًا رئيسيًا، أهمها معدل نجاح التسليم، متوسط ​​وقت الاستجابة، وذروة معدل الخطأ. فيما يلي تفاصيل التنفيذ المحددة للاختبار:

أولاً، عند إنشاء بيئة الاختبار، يجب استخدام بيئة الحماية (Sandbox Environment) التي توفرها Meta. هذه البيئة معزولة تمامًا عن بيئة الإنتاج ولكنها متطابقة في الوظائف. تدعم بيئة الحماية محاكاة ما يصل إلى 50 رقمًا للاختبار، ويمكن لكل رقم إرسال 1000 رسالة اختبار مجانية شهريًا. يتطلب الاختبار تكوين شهادات API مخصصة. هذه الشهادات صالحة لمدة 30 يومًا وتقتصر على استخدام بيئة الحماية. يوصى باستخدام أدوات الاختبار الآلي لبناء نصوص الاختبار، لمحاكاة سلوك المستخدم الحقيقي: بما في ذلك إرسال الرسائل النصية (تشكل 60%)، رسائل الوسائط المتعددة (تشكل 25%)، ورسائل القوالب (تشكل 15%) من الأنواع الثلاثة.

إعداد عتبة مؤشرات الاختبار الرئيسية: يجب أن يكون معدل نجاح التسليم ≥99.5%، ومتوسط ​​وقت الاستجابة يجب أن يكون ≤1200 مللي ثانية، ومعدل الخطأ يجب أن يكون ≤0.2%، وتوافر النظام يجب أن يكون ≥99.9%. يجب تعيين عتبة تحذير لكل مؤشر (عند الوصول إلى 80% من الحد الأقصى) وعتبة خطر (وقف الاختبار فورًا عند الوصول إلى 95% من الحد الأقصى).

في مرحلة الاختبار الوظيفي، يجب التحقق من 8 سيناريوهات أساسية: إرسال الرسائل العادي، الرسائل ذات المرفقات، إرسال الرسائل الجماعية، مراجعة رسائل القوالب، تلقي ردود حالة (Callback)، آلية معالجة الأخطاء، تشغيل حد المعدل، ومنطق إعادة المحاولة التلقائي. يجب تنفيذ ما لا يقل عن 200 حالة اختبار لكل سيناريو، وبإجمالي عدد اختبارات لا يقل عن 1600 مرة. يجب إيلاء اهتمام خاص لاختبار رسائل القوالب، لأن هذا يتطلب تقديم القوالب للمراجعة مسبقًا (وقت المراجعة 2-48 ساعة). يجب أن يغطي الاختبار جميع تنسيقات المتغيرات المدعومة: المتغيرات النصية (بحد أقصى 10)، متغيرات العملة (تدعم 42 نوعًا من العملات)، متغيرات التاريخ والوقت (تدعم 12 تنسيقًا)، ومتغيرات الوسائط (تدعم الصور والمستندات).

يجب إجراء اختبار الأداء بثلاثة مستويات شدة: أولاً، اختبار الحمل الأساسي (محاكاة إرسال 5 رسائل في الثانية، لمدة ساعة واحدة)، ثم اختبار ذروة الحمل (محاكاة 20 رسالة في الثانية، لمدة 30 دقيقة)، وأخيرًا اختبار التحمل (محاكاة 10 رسائل في الثانية، لمدة 24 ساعة). خلال هذه العملية، يجب تسجيل 17 مؤشر أداء للنظام، بما في ذلك: استخدام وحدة المعالجة المركزية (يجب أن يكون أقل من 70%)، استخدام الذاكرة (يجب أن يكون أقل من 80%)، إنتاجية الشبكة (يجب أن تصل إلى 100 ميجابت في الثانية)، وقت استجابة قاعدة البيانات (يجب أن يكون أقل من 50 مللي ثانية). يجب إيلاء اهتمام خاص لسلوك النظام عند الوصول إلى أقصى حد للحمل، لضمان عدم ارتفاع معدل الخطأ فجأة إلى أكثر من 5%.

تتطلب مرحلة الاختبار في البيئة الحقيقية اختيار 3 فترات زمنية مختلفة: صباح يوم عمل 10-12 ظهرًا (ذروة)، مساء 8-10 مساءً (ذروة ثانوية)، وفجر 2-4 صباحًا (وقت منخفض). يجب أن يستمر الاختبار لمدة ساعتين في كل فترة، وأن يكون إجمالي عدد الرسائل المرسلة تحت سيطرة 500 رسالة. خلال فترة الاختبار، يجب مراقبة حالة الرسالة في الوقت الفعلي، وتسجيل متوسط ​​الوقت من الإرسال إلى التسليم (يجب أن يكون في غضون 3 ثوانٍ)، ومتوسط ​​الوقت من التسليم إلى القراءة (عادة ما يتقلب في غضون 60 ثانية). في الوقت نفسه، يجب التحقق من آلية الرد (Callback): التأكد من دفع 100% من تحديثات الحالة بشكل صحيح إلى Webhook، وأن تأخير المعالجة أقل من 500 مللي ثانية.