دليل تكامل واجهة API للمراسلة: REST وSMPP وWebhooks

هذا الدليل موجّه لمطوري الواجهات الخلفية ومعماريي الحلول ومديري التقنية الذين يربطون تطبيقًا بمزود مراسلة لـ WhatsApp أو SMS أو البريد الإلكتروني. ويشرح أي واجهة تستخدم، وكيف تتعامل مع المصادقة وعدم تكرار التنفيذ وتقارير التسليم وإعادة المحاولة وحدود المعدل والاختبار، مع أشكال توضيحية للطلبات والاستجابات. ولمزامنة المحادثات مع نظام CRM، راجع الدليل المرافق حول ربط CRM عبر webhooks.

أي واجهة تستخدم: REST أم SMPP أم webhooks؟

استخدم REST للإرسال، وwebhooks للاستقبال، وSMPP فقط لرسائل SMS بأحجام كبيرة حيث تشغّل SMPP بالفعل. وهي متكاملة لا متنافسة: تجمع معظم التكاملات بين استدعاءات REST الصادرة وwebhooks الراجعة.

تبدأ جلسات SMPP (Short Message Peer-to-Peer) بعملية ربط (bind) بصفة مرسل أو مستقبل أو مرسل ومستقبل معًا، وترسل الرسائل بـ submit_sm، وتستقبل تقارير التسليم ورسائل SMS الواردة عبر deliver_sm، وتبقى حية بـ enquire_link. وهو فعّال لكنه أثقل تشغيليًا من HTTPS.

كيف تتم المصادقة؟

استخدم أقوى طريقة يوفرها المزود، وأبقِ الأسرار خارج الشيفرة، وصادِق في الاتجاهين.

• الاستدعاءات الصادرة: مفاتيح API أو رموز OAuth 2.0 من نوع bearer تُرسل في ترويسة Authorization عبر TLS. خزّنها في مدير أسرار، وبدّلها وفق جدول وبعد أي تغيير في الموظفين.
• SMPP: معرّف النظام وكلمة المرور عند الربط، وعادةً مع تقييد بعناوين IP مسموح بها، وعبر TLS حيثما أمكن.
• webhooks الواردة: تحقق من التوقيع في كل حدث. توقّع Meta حمولات webhooks الخاصة بـ WhatsApp Cloud API بتوقيع HMAC-SHA256 في ترويسة X-Hub-Signature-256، يُحسب بسرّ تطبيقك؛ ويقدم المزودون عادةً مخططًا مماثلًا. احسب التوقيع على الجسم الخام قبل تحليله.

استخدم بيانات اعتماد منفصلة لكل بيئة حتى لا يستطيع مفتاح اختبار مسرَّب إرسال حركة إنتاج.

كيف ترسل رسالة بأمان؟

أرسل عبر طابور، وضمّن مفتاح idempotency، وتعامل مع الاستجابة على أنها "مقبولة" لا "مسلَّمة".

طلب إرسال توضيحي

الشكل أدناه JSON توضيحي (pseudo-JSON) وليس واجهة مزود بعينه.

POST /v1/messages
Authorization: Bearer <token>
Idempotency-Key: 7f3c9a2e-order-55821-shipped

{
  "channel": "whatsapp",
  "to": "+9715XXXXXXXX",
  "template": {
    "name": "order_shipped",
    "language": "ar",
    "variables": ["Layla", "55821", "15 March"]
  },
  "client_reference": "order-55821",
  "callback_url": "https://api.example.com/webhooks/messaging"
}

استجابة توضيحية

202 Accepted

{
  "message_id": "msg_01HZX...",
  "status": "accepted",
  "client_reference": "order-55821",
  "created_at": "2026-10-09T12:00:00Z"
}

خزّن message_id فورًا مقابل مرجعك الخاص. فكل ما يحدث بعد ذلك يصل بصورة غير متزامنة.

لماذا يهم عدم تكرار التنفيذ (idempotency)؟

لأن الشبكات تنتهي مهلتها بعد أن يكون الخادم قد نفذ الطلب بالفعل. فإذا انتهت مهلة طلب الإرسال وأعدت المحاولة دون تحقق، فقد يتلقى العميل رمزَي OTP أو إشعارَي شحن. ويتيح مفتاح idempotency للخادم التعرف على إعادة المحاولة وإرجاع النتيجة الأصلية.

قواعد مجرَّبة:

1. اشتق المفتاح من الحدث التجاري (مثل معرّف الطلب مع نوع الحدث)، لا من قيمة عشوائية لكل محاولة.
2. أعد استخدام المفتاح نفسه في كل إعادة محاولة لعملية الإرسال ذاتها.
3. اجعل المفاتيح طويلة بما يكفي لتغطية نافذة إعادة المحاولة لديك.
4. إن لم يدعم المزود المفاتيح، فأزل التكرار من جانبك قبل الإرسال.

وتوحّد مسودة ترويسة Idempotency-Key لدى IETF هذا النمط لواجهات HTTP؛ وتختلف تنفيذات المزودين، فاقرأ توثيقهم.

كيف تعمل تقارير التسليم؟

تصل حالة التسليم لاحقًا على شكل أحداث: من webhooks في WhatsApp ومعظم واجهات REST، ومن إيصالات deliver_sm في SMPP. وتختلف معاني الحالات بحسب القناة؛ ويشرح دليلنا حول حالات تسليم الرسائل كل واحدة منها.

webhook حالة توضيحي

POST /webhooks/messaging
X-Signature: sha256=<hmac>

{
  "event_id": "evt_9c1...",
  "type": "message.status",
  "message_id": "msg_01HZX...",
  "client_reference": "order-55821",
  "status": "delivered",
  "timestamp": "2026-10-09T12:00:04Z",
  "error": null
}

تعامل مع أحداث الحالة بأسلوب دفاعي:

• أزل التكرار بحسب event_id، أو بحسب معرّف الرسالة مع الحالة.
• لا تُرجع رسالة من حالة "مقروءة" إلى "مسلَّمة" عندما تصل الأحداث بغير ترتيبها.
• ردّ بـ 2xx بسرعة، ثم عالج من طابور.
• سجّل رموز الأخطاء للرسائل الفاشلة، وحدد أيها قابل لإعادة المحاولة.
• توقّع الفجوات: بعض مسارات SMS تعيد إيصالات محدودة، وتعتمد حالة القراءة على القناة وإعدادات المستخدم.

كيف تتعامل مع إعادة المحاولة وحدود المعدل؟

أعد محاولة ما يمكن أن ينجح فقط، وتراجع أسيًا مع جيتر، والتزم بإشارات الخادم.

يعرّف RFC 9110 ترويسة Retry-After، التي قد تحمل ثواني أو تاريخًا. وضع محدِّد معدل من جانب العميل أمام عمليات الإرسال لتبقى دون الحدود الموثقة لدى المزود بدل اكتشافها عبر الأخطاء. ولدى WhatsApp أيضًا حدود من جانب Meta على عدد العملاء الفريدين الذين يمكنك مراسلتهم، موضحة في حدود المراسلة وتقييم الجودة.

كيف تختبر قبل الإطلاق؟

اختبر مسارات الفشل لا المسار السليم فقط.

قائمة تدقيق ما قبل الإنتاج

1. أرسل كل قالب بقيم بأطوال حقيقية، بما فيها نص عربي.
2. أجبر مهلة منتهية وتأكد من أن إعادة المحاولة لا تكرر الرسالة.
3. أرسل إلى رقم غير صالح وتأكد من معالجة الخطأ دون إعادة محاولة.
4. أعد تشغيل webhook مرتين وبغير ترتيبه؛ وتأكد من حالة نهائية واحدة.
5. أرسل webhook بتوقيع خاطئ وتأكد من رفضه.
6. أثِر استجابات 429 باختبار حمل على بيئة sandbox إن كان ذلك مسموحًا.
7. بدّل مفتاح API وتأكد من عدم حدوث انقطاع.
8. تحقق من أن السجلات تتضمن معرّفات الرسائل لا نصوصها الكاملة أو رموز OTP.
9. شغّل تجربة إنتاج صغيرة بأرقام داخلية على كل قناة.

نادرًا ما تحاكي بيئات sandbox سلوك شركات الاتصالات وMeta بدقة، فواصل المراقبة في الأسابيع الأولى من الإنتاج.

مثال تطبيقي: خدمة OTP وإشعارات الطلبات

ترسل "قافلة للخدمات اللوجستية" (اسم افتراضي)، وهي شركة طرود في السعودية، تحديثات الطلبات عبر WhatsApp مع SMS احتياطيًا، ورموز OTP للمصادقة.

• البنية: تذهب أحداث الطلبات إلى طابور؛ وينفذ عامل الإرسال استدعاء REST API بمفتاح idempotency هو shipment-id:event.
• الاحتياطي: إذا أعاد WhatsApp حالة فشل لمستخدم لا يملك WhatsApp، يرسل العامل SMS بمفتاح جديد هو shipment-id:event:sms.
• OTP: تنتهي صلاحية الرموز سريعًا، فلا تُعاد محاولة إرسال OTP بعد نافذة الانتهاء؛ ويطلب المستخدم رمزًا جديدًا. راجع دليل رسائل مصادقة OTP.
• الإيصالات: يتحقق مستقبِل webhook من التواقيع، ويزيل التكرار، ويحدّث جدول حالات لا يرجع إلى الوراء.
• الحدود: يضع محدِّد token-bucket سقفًا لمعدل الإرسال لكل قناة دون الحدود الموثقة.

ما أخطاء التكامل الشائعة؟

• معاملة "مقبول" على أنه "مسلَّم".
• إعادة المحاولة بمفتاح idempotency جديد في كل مرة.
• إجراء معالجة ثقيلة داخل طلب webhook.
• تخطي التحقق من توقيع webhooks.
• إعادة محاولة أخطاء التحقق 4xx في حلقة.
• تسجيل رموز OTP ومحتوى الرسائل الكامل.
• استخدام بيانات اعتماد الإنتاج في بيئات الاختبار.

كيف تساعدك OmniChannels.ai

توفر OmniChannels.ai، المدعومة من BroadNet Technologies، واجهة REST/JSON API موثّقة للعموم بمواصفات OpenAPI 3.1 وحزمة SDK بلغة TypeScript، تغطي SMS وWhatsApp وRCS وMessenger وInstagram وTelegram والبريد الإلكتروني والإشعارات الفورية، بما في ذلك قوالب مصادقة WhatsApp مع OTP بالنقرة الواحدة (one-tap) وبلا نقر (zero-tap) ونسخ الرمز (copy-code). وتُبلغ webhooks عن حالات التسليم بصيغة موحّدة واحدة، ويخدم SMPP 3.4 عبر TLS رسائل SMS بالأحجام الكبيرة، ويربط خادم MCP وكلاء الذكاء الاصطناعي. وتساعدك تقارير التسليم، مع عوامل التصفية وتصدير CSV، على مطابقة ما أرسله تكاملك. ابدأ من وثائق المطورين ودليل البدء السريع.