بوابة التكامل الموحدة: قناة واحدة لإدارة واتساب وماسنجر والجميع

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

حين تتعامل شركتك مع واتساب وماسنجر وإنستغرام وتيليجرام والرسائل النصية والبريد، يتحول كل قناة إلى مكتبة SDK مختلفة وبنية حمولات مختلفة وأخطاء مختلفة. هذا المقال يبني بوابة تكامل موحدة: نموذج رسالة واحد، محولات (Adapters) لكل قناة، رسمية الهوية، إعادة المحاولة، إيصالات التسليم، ولوحة مركزية تلمس كل الحالات بلا تكاثر الكود.

ستتعرف على لماذا تكون الطبقة المركزية أرجح من تجميع الكود في الخدمات، وكيف تصمم Message واحدًا يغطي النص والمرفقات والأزرار، وكيف تحوّل الحمولة إلى شكل كل قناة، وكيف تضمن عدم الازدواجية عندما تعيد القناة إرسال نفس الحدث، وكيف تقيس التكلفة والنجاح لكل قناة في لوحة واحدة.

لماذا بوابة موحدة أصلًا؟

البديل الساذج: في كل خدمة تحتاج إرسال إشعار، تستدعي SDK القناة مباشرة. النتيجة بعد ثلاث قنوات: كود مراسلة مكرر في كل خدمة، وتعاليم إعادة محاولة مختلفة، ولا نظرة موحدة على ما يُرسل. البوابة المركزية تحول الرسالة إلى عقد موثق، ومن هذا العقد تولّد مخرج كل قناة، وتسجل كل حالة في مصدر واحد.

نموذج الرسالة الواحد: العقد الداخلي

عرّف نوع Message موحدًا يحمل ما تحتاجه كل القنوات بلا استثناء:

class Message {

    public string $id; public string $channel;

    public string $recipient; public ?string $text;

    public ?string $mediaUrl; public ?array $buttons;

    public ?array $metadata; public string $traceId;

}

• channel: من أي قناة جاء هذا الرسالة أو يذهب إليها.


• traceId: يربط الطلب عبر السجلات واللوحة حتى الخطأ النهائي.


• metadata: مفتاح تفاصيل القناة (مثل معرّف الرقم) دون تلوث العقد.

المحولات (Adapters): كل قناة بطبقتها

المحول هو الوحيد الذي يفهم فرق القناة: يعرف عناوينها، وتنسيقاتها، ونماذج قوالبها، وأخطاءها. البوابة تعرف المحول بطريقة موحدة تُرسل بها Message وتسمع Event:

interface ChannelAdapter {

    public function send(Message $m): ChannelReceipt;

    public function handleWebhook(array $payload): Message;

}

الاستقبال أيضًا موحّد: كل قناة تحوّل حمولتها الواردة إلى نفس نوع Message، فيتعامل منطق العمل مع القناة الواحدة لا مع أساليبها. أضف قناة جديدة؟ محول جديد فقط، بلا تغيير في خدمات العمل.

الموثوقية: عدم الازدواجية وقطع المحاولة

القنوات تعيد إرسال الأحداث؛ إن لم تمنع التكرار، سيتكرر «شحن المهمة» أو «تسجيل الدخول» عند العميل. اعتمد:

• مفتاح التفرد: wamid أو entry.id + time كمفتاح شامل في جدول inbound_events، ورفض التكرار قبل المعالجة.


• إعادة محاولة تصاعدية: لكل محول سياسة أوقاته؛ البوابة تراقب وتطبّق الفواصل تلقائيًا.


• الحالة الدائمة: pending/sent/delivered/read/failed تُحدَّث في كل استجابة من القناة.

CREATE TABLE inbound_events (

  id BIGINT AUTO_INCREMENT PRIMARY KEY,

  tenant_id BIGINT NOT NULL,

  channel  VARCHAR(32) NOT NULL,

  external_id VARCHAR(191) NOT NULL,

  payload  JSON NULL,

  processed_at DATETIME NULL,

  UNIQUE KEY uq_channel_ext (tenant_id, channel, external_id)

);

إيصالات التسليم واللوحة

عندما تبلغ القناة delivered وread، يمرّ Event موحّد إلى البوابة لتحدّث الحالة. اللوحة المركزية تعرض لكل قناة:

• إجمالي المرسلات والأخطاء في الساعة.


• معدل التحويل من queued إلى delivered لكل قناة.


• التكلفة التقديرية (عبر أسعار كل قناة) مقابل مرسلات الفعلية.


• قائمة failed مع رمز السبب للتصحيح المباشر.

قوالب القنوات المركزية

كل قناة لها قالبها (واتساب يُراجع، ماسنجر بأزرار، تيليجرام بترميز). البوابة تحوّل قالبًا داخليًا واحدًا إلى قالب أسبابه في كل محول، وتحتفظ بمسودات معتمدة لكل قناة. هكذا عندما يعلن فريق التسويق رسالة، تُنشر في كل القنوات بقوالبها الصحيحة بدل كتابة نصوص منفصلة يتعارض أسلوبها.

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

• نموذج Message واحد يعبر كل القنوات وtraceId يلحق كل حالة.


• كل قناة عبر محول خالص بلا منطق عمل.


• جدول inbound_events يمنع الازدواجية قبل المعالجة.


• حالات موحّدة تُحدَّث من إيصالات القناة.


• لوحة تصور المرسلات والتكلفة والفوائد لكل قناة.


• إعادة محاولة تصاعدية وفصل الأخطاء الدائمة عن المؤقتة لكل محول.

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

هل بوابة مركزية أبطأ من الاستدعاء المباشر؟

بالأجزاء من المللي ثانية، لكن التسامح المكتسب (إعادة المحاولة، التتبع، القوالب) يكسبك وقتًا أكثر بكثير مما تخسره في الظهور.

ماذا لو أضفنا قناة لا تدعم ميزة ما؟

المحول يرفضها بخطأ واضح قبل الإرسال، واللوحة تظهر «غير مدعومة» للميزة بدل صمت فاشل.

كيف أتجنب تعطل أي قناة منفردة يوقف كل المراسلة؟

بفصل المحولات بمهلات زمنية وحواجز (Circuit Breaker): تعطل واتساب لا يمنع ماسنجر، وتعطّل الحومة تُعالج خلف طابعة.

الخلاصة

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

ابدأ بـ المحول الأول (واتساب) ثم أضف ثانيًا (ماسنجر) حتى تتأكد أن تصميم العقد صامد. المقال القادم يتناول المقارنة بين السحابة والاستضافة في كل قناة وأثرها على التكلفة والخصوصية.

flowchart LR

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

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

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

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

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

    A --> B

    B --> C

    C --> D

    D --> E