التكامل مع WhatsApp Business API: نافذة المحادثة والقوالب والتكلفة

ماذا ستخرج به من هذا المقال؟

رسالة واتساب تصل إلى جيب المستخدم بموثوقية نادرة؛ لذلك تحوّلت من أداة شخصية إلى قناة أعمال رسمية بقواعد صارمة. هذا المقال يشرح التكامل مع WhatsApp Business API: كيف تختار بين Cloud API والاستضافة الذاتية، وتنشئ حساب عمل على Meta، وتصمم القوالب المعتمدة، وتستقبل الرسائل بالـ Webhooks، وتدير التكلفة والحصص في الإنتاج.

ستبني النية بشكل صحيح: الإنتاج والرسوم لكل محادثة، وسياسة النافذة الزمنية 24 ساعة، وآلية القوالب عندما تكون خارج النافذة، ومعرّفات النبذات والحالة، وأخطاء 131026 و131047 الشائعة، وكيفية إرسال المرفقات وتتبّع التسليم.

Cloud API مقابل الاستضافة الذاتية

الخياران: Cloud API تُدار بالكامل من Meta وترسل الاستدعاءات إلى `graph.facebook.com/v21.0`، أو واجهة على الويب تُثبّت على خادمك (On-Premises) واسمع بعض الحكومات تفرضه لبقاء البيانات محليًا. الممارسة السائدة: Cloud API لمعظم الحالات لأنها تخفّف عبء التشغيل، والاستضافة الذاتية فقط لمتطلبات تنظيمية حاضرة.

إنشاء حساب العمل وتجهيز الرسائل

كل رسالة تجارية تُرسل باسم رقم مسجّل في لوحة Meta المرتبطة بحساب عمل Meta (Business portfolio). تحتاج:

• رقم هاتف تجاري: غير مسجّل بتطبيق واتساب شخصي، ويُتحقق منه برمز OTP.


• اسم العرض: يظهر للمستلم، ويخضع للمراجعة.


• رمز المراسلة: كل رقم يستلم system-user-access-token مُخوَّل بمنتج WhatsApp.


• Webhook: تُسجَّل نقطة استقبال عندما تُرسل الرسائل والأحداث.

// إرسال رسالة نصية عبر Cloud API

$url = 'https://graph.facebook.com/v21.0/' . env('WHATSAPP_PHONE_ID') . '/messages';

post($url, [

    'messaging_product' => 'whatsapp',

    'to' => $recipient,

    'type' => 'text',

    'text' => ['preview_url' => false, 'body' => $body],

], ['Authorization' => 'Bearer ' . env('WHATSAPP_TOKEN')]);

قواعد الـ Inbox: النافذة 24 ساعة والقوالب

يرسم واتساب حدود الزمن بصرامة:

• خلال 24 ساعة من رسالة المستخدم: ترسل رسائل حرة (Session) مفتوحة — نصية، صور، متاجر.


• خارج النافذة: المرسل الوحيد هو القالب المعتمد (Template) عبر المعرّف template.


• فتح النافذة: قد يفتح أي حدث «إدخال نص في متجر» النافذة مجددًا.

تُنشأ القوالب في لوحة Meta بقوالب رسائل مثل marketing وutility وauthentication، ويجب أن تمرّ بمراجعة الوكالة قبل الاستخدام. لا تتعامل مع القالب كهامة: كل حقل نصوص فيه بيانات ديناميكية تُنمّذج ببارامترات body.

الاستقبال: الرسائل والأحداث والتوقيع

كل الأحداث ترسل إلى الـ Callback URL المسجّلة. يصل نوع الرسالة message (نص/صورة/مستند) وحالات التسليم status. تأكد من:

• توقيع الدخول: تفاوض عن X-Hub-Signature-<Версия> من الرؤوس بنفس App Secret المتمركز.


• رد فوري: عدل 200 بسرعة ثم عالج بالطابعة؛ وإلا ستعيد Meta الإرسال.


• المعرّف: وحدّد wamid لمنع التكرار على المعلّمة.

{

  "entry": [{

    "changes": [{

      "value": {

        "metadata": { "display_phone_number": "15550015555", "phone_number_id": "1123581321" },

        "messages": [{ "from": "15551234567", "id": "wamid.HBgNzUxNDE0NDQ1NTY5NZQ", "timestamp": "1708108507", "text": { "body": "الحمد لله انتهيت" } }],

        "statuses": [{ "id": "wamid...", "status": "delivered" }]

      }

    }]

  }]

}

الحصص والتكلفة

حصة المراسلة تنسب إلى Markup Tier أو مستوى الجودة والرسائل السابقة. الرسائل غير المفلترة تُحصى بـ «الرسائل التجارية» التي تسقط ضمن النافذة وتُدفع كل 24 ساعة، والقوالب خارج النافذة من فئة منفصلة بـ pricing_model. راجع تسعير الدول لكل رسالة حتى لا تتفاجأ بفاتورة عند حمل التسويق.

الأخطاء الشائعة وإعادة المحاولة

• 131047: رسالة ارتُكبت خارج نافذة 24 ساعة — افحص أن القالب هو الطلب.


• 131026: عامل إرسال محظور مؤقتًا أو رقم غير مُخوَّل.


• 132000: مشاكل عامة في رسالة غير منجزة — تحقق من المعرّف.


• 131030: عدم توثيق الرقم للتشغيل — عدّ الرقم إلى حالة connected.

لا تُعد المحاولة للقيم مثل 131047 و131026 من غير إصلاح السبب؛ أعد فقط للأخطاء المؤقتة (شبكة، 5xx، تجاوز حدّ مؤقت). استخدم الفواصل التصاعدية بعد إكمال كل إعادة محاولة.

قائمة تحقق قبل الإنتاج

• حساب العمل في حالته النشطة والرقم connected.


• القوالب المعتمدة جاهزة بفئاتها الصحيحة ومتغيراتها.


• Webhook يتحقق من التوقيع ويعيد 200 بسرعة ويعالج بالطابعة.


• خريطة «خارج النافذة → القالب» محددة ومعتمدة.


• مقياس حصص وتكلفة ورسالة إشعارات بالاقتراب من الحد.


• اختبار إرسال واستقبال خارج النافذة وخلالها.

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

لماذا يعتبر إرسال «سؤال/جواب» عبر القوالب خارج النافذة خطأ؟

لأن القوالب رسائل مرسلة بتوجيه تعريفي؛ المحادثة الحية تتم داخل النافذة. إن فتح المستخدم لومًا عبر زر، تصبح الرسالة ضمن النافذة.

كيف أطلع على رسالة في النافذة؟

تحقق من timestamp الأحدث لرسالة واردة وافحص فرق 24 ساعة؛ إن تجاوزته، استخدم قالبًا.

هل تظهر نجمة المرفقات في الحصص؟

نعم. الصور والمستندات تُحسب بنفس منهج السعر لكل رسالة تجارية؛ إن لم تكن ضمن نافذة، اضطرت إلى تنسيق قالب مع media.

الخلاصة

الخطوة التالية

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

flowchart LR

    A["طلب العميل"]

    B["مصادقة وتوثيق"]

    C["طبقة التكامل"]

    D["الخدمة الخارجية"]

    E["التحقق والتدقيق"]

    A --> B

    B --> C

    C --> D

    D --> E