API وWebhooks

واتساب API للمطورين: اربط نظامك بمحادثات عملائك

واتساب API للمطورين وأصحاب الأنظمة: استقبل رسائل العملاء على Webhook موقّع، ورد عليها من نظامك أو من بوت n8n بطلب REST واحد، وحوّل المحادثة إلى موظف عندما يلزم. كل ذلك على أرقامك المربوطة في إعلانيشن.

curl -X POST https://e3lanition.com/api/v1/messages \
  -H "Authorization: Bearer e3l_live_…" \
  -H "Content-Type: application/json" \
  -d '{"conversationId": "cm…",
       "text": "Order 1042 is on the way"}'

200 OK
{"id": "cm…", "waMessageId": "wamid.…",
 "status": "sent", "conversationId": "cm…"}

كيف تعمل

1

أنشئ مفتاح API

ينشئ مالك الحساب المفتاح من الإعدادات على شكل e3l_live_xxxx، ويظهر مرة واحدة فقط، ونحفظ منه بصمة SHA-256 لا المفتاح نفسه. وترسله في كل طلب داخل ترويسة Authorization: Bearer.

2

استقبل الأحداث على Webhook

أضف رابط https لنظامك واختر ما يصله: الرسائل الواردة (message.received)، وحالات التسليم (message.status)، وجاهزية الوسائط (message.media.ready). ثم تحقق من توقيع كل طلب بالسر الخاص بالرابط.

3

رد من نظامك

أرسل الرد إلى POST /api/v1/messages بالـ conversationId الذي وصلك في الحدث، أو حوّل المحادثة إلى موظف عبر handoff مع سبب التحويل.

ماذا تقدّم لك

مفاتيح API بصلاحيات

لكل مفتاح صلاحية الإرسال messages:send وصلاحية المحادثات conversations:write، وتظهر بدايته وآخر استخدام له في لوحة التحكم، ويمكن إلغاؤه فورًا. وحتى 5 مفاتيح نشطة معًا لتبديلها دون توقف.

أربع نقاط نهاية REST

إرسال رسالة نصية حتى 4096 حرفًا، وتغيير حالة المحادثة إلى OPEN أو PENDING أو RESOLVED، وتحويلها إلى موظف مع تعيينه بالبريد الإلكتروني، وإضافة ملاحظة داخلية لا يراها العميل.

Webhooks موقّعة بـ HMAC

يحمل كل طلب ترويسة X-E3lanition-Signature فيها توقيع HMAC-SHA256 للجسم الخام بسر الرابط (بالصيغة sha256=hex)، ويحمل الجسم وقت الحدث، ويمكنك توليد سر جديد في أي وقت.

إعادة محاولة تلقائية

إذا لم يرد نظامك بنجاح خلال 10 ثوانٍ نعيد المحاولة حتى 5 مرات بفواصل تتضاعف بدءًا من 5 ثوانٍ، ونحتفظ بسجل لكل تسليم بحالته ورمز الاستجابة وعدد المحاولات لمدة 30 يومًا.

حماية من SSRF

نقبل روابط https فقط، ونرفض localhost والعناوين الخاصة والمحلية وعنوان بيانات السحابة 169.254، ونفحص كل سجلات DNS للرابط ثم نتصل بالعنوان الذي فحصناه نفسه، ولا نتبع أي تحويل 3xx.

الوسائط عبر message.media.ready

عندما يرسل العميل صورة أو ملفًا يصلك هذا الحدث بعد حفظ الملف، ومعه رابط موقّع صالح لساعة واحدة ونوع الملف واسمه وحجمه.

أمثلة من السوق الكويتي

شركات التوصيل

شركة توصيل في العارضية يستقبل نظامها رسالة «وين طلبي؟» عبر message.received، فيبحث عن الشحنة برقم العميل ويرد بحالتها عبر POST /api/v1/messages خلال ثوانٍ.

وكالات التسويق الرقمي

وكالة تسويق في القبلة تشغّل بوت n8n على رقم أحد عملائها في وضع «بوت خارجي»، يرد على الأسئلة المتكررة، ويحوّل طلبات عروض الأسعار إلى موظف المبيعات عبر handoff مع سبب التحويل.

شركات التأمين

شركة تأمين في الصالحية تستقبل صور الحوادث عبر message.media.ready وتحفظها في نظام المطالبات خلال الساعة، ثم تضيف رقم المطالبة كملاحظة داخلية على المحادثة.

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

لا. يرسل الـ API رسائل نصية إلى عميل راسلك خلال آخر 24 ساعة على واتساب، أو في أي وقت على تليجرام بعد أن يبدأ العميل المحادثة. وخارج النافذة يرد بالخطأ outside_service_window. أما القوالب والحملات فمن لوحة التحكم.

اربط نظامك بمحادثات واتساب

مفاتيح API وWebhooks موقّعة في الباقة الاحترافية. قارن الباقات واختر ما يناسب فريقك.

اطّلع على الباقات