خطافات الويب (Webhooks) #

تتيح لك خطافات الويب (Webhooks) قيام Your AI Connector بإخطار أدوات عملك الأخرى تلقائيًا كلما حدث شيء مهم — مثل إنشاء جهة اتصال جديدة، أو حجز موعد، أو تلقي رسالة. بدلاً من التحقق يدويًا من وجود تحديثات، تتلقى أنظمتك المتصلة إشعارًا فوريًا في اللحظة التي يحدث فيها أي شيء.

ما هي خطافات الويب؟ #

فكر في خطاف الويب (webhook) كرسالة نصية تلقائية بين تطبيقين. عندما يحدث شيء ما في Your AI Connector (مثل تسجيل جهة اتصال جديدة)، ترسل المنصة إشعارًا على الفور إلى نظام آخر من اختيارك. أنت تقدم عنوان ويب (يسمى “عنوان URL لخطاف الويب”) حيث يجب إرسال هذه الإشعارات — وعادة ما يتم توفير هذا العنوان من قبل نظام إدارة علاقات العملاء (CRM) الخاص بك، أو منصة الأتمتة، أو المطور.

تعمل خطافات الويب (Webhooks) على إرسال البيانات إلى خارج Your AI Connector فقط. يُعد خطاف الويب طريقاً باتجاه واحد من Your AI Connector إلى أدواتك الأخرى. لا يوجد عنوان URL لخطاف الويب يقوم بإرسال العملاء المحتملين أو جهات الاتصال أو الرسائل إلى داخل المنصة. لإضافة عميل محتمل جديد — من نموذج موقع ويب، أو نظام إدارة علاقات العملاء (CRM) الخاص بك، أو GoHighLevel — يقوم نظامك بإجراء استدعاء API بدلاً من ذلك. راجع الوصول إلى API (عملية إنشاء جهة اتصال) والقمع التسويقي (Funnels). الشيء الوحيد الذي تحتاجه للاتجاه الوارد هو مفتاح API الخاص بك، والذي يوجد في قسم خاص به — راجع الوصول إلى API. صفحة خطافات الويب (Webhooks) الموضحة هنا مخصصة حصرياً للاتجاه الصادر.

تشمل الاستخدامات الشائعة ما يلي:

• مزامنة جهات الاتصال الجديدة مع نظام إدارة علاقات العملاء (CRM) الخاص بك.
• تشغيل سير عمل في Zapier أو Make أو Pabbly عند تطبيق وسم (Tag) معين.
• إخطار فريقك في Slack عند تنبيه أحد الموظفين البشريين.
• تحديث نظام التقويم الخاص بك عند حجز موعد.
• تسجيل ملخصات المحادثات في قاعدة بياناتك.

إعداد خطافات الويب #

1. في الشريط الجانبي الأيسر، انقر فوق الإعدادات (أيقونة الترس).
2. في الشريط الجانبي للإعدادات، ضمن مجموعة التكاملات، انقر فوق خطافات الويب.

في الحساب الذي لم يتم تكوين خطافات ويب (webhooks) له بعد، تبدو الصفحة كما يلي:

3. انقر على New webhook (خطاف ويب جديد) في أعلى اليمين. سيفتح نموذج مضمن في الصفحة:

4. املأ البيانات التالية:
   • عنوان URL لنقطة النهاية (Endpoint URL) — عنوان الويب الذي سترسل إليه Your AI Connector إشعارات الأحداث. تحصل عليه من نظامك الخارجي (نظام CRM، أو منصة أتمتة، أو خادم مخصص).
   • الاسم — تسمية ستتعرف عليها لاحقًا (مثل “تنبيهات Slack” أو “مزامنة CRM”). للرجوع إليها فقط.

يجب أن يكون عنوان URL لخطاف الويب الخاص بك عنوان https:// يمكن الوصول إليه بشكل عام. يتم رفض عناوين http:// العادية، أو عناوين localhost أو عناوين الشبكة الخاصة، وعناوين الشبكة الداخلية للمنصة عند الحفظ. للاختبار من جهازك الخاص، استخدم نفقًا عامًا (مثل webhook.site أو ngrok) بدلاً من localhost.

5. ضمن الأحداث (Events)، انقر فوق الأحداث التي تريد أن يتلقاها خطاف الويب (webhook) هذا — جميع الأحداث الـ 22 مدرجة في أحداث خطاف الويب الـ 22.
6. (اختياري) قم بتفعيل إعادة محاولة عمليات التسليم الفاشلة (Retry failed deliveries) إذا كنت تريد من Your AI Connector الاستمرار في المحاولة عند حدوث فشل مؤقت — راجع إعادة محاولة عمليات التسليم الفاشلة.
7. انقر فوق إنشاء خطاف ويب (Create webhook). سيظهر في القائمة أسفل النموذج، ويمكنك النقر فوق اختبار (Test) في صفه في أي وقت لإرسال حمولة نموذجية إلى نقطة النهاية الخاصة بك.

الإذن مطلوب. تتطلب إضافة خطافات الويب أو تعديلها أو اختبارها إذن “تعديل” للتكاملات (يرى أعضاء الفريق ذوو صلاحية العرض فقط إشعارًا للقراءة فقط بدلاً من النموذج).

توقيع خطاف الويب يتطلب أن يكون محفوظًا مسبقًا — افتح صف خطاف ويب موجود لتعديله، وستظهر لوحة سر التوقيع في أسفل نموذج التعديل. المسودة الجديدة تمامًا وغير المحفوظة لا تحتوي على خيار توقيع بعد — راجع الحمولات الموقعة أدناه.

خطاف ويب واحد لجميع حسابات عملائك (الوكالات) #

إذا كنت تدير وكالة، فلن تضطر إلى إعادة إنشاء نفس خطاف الويب في كل حساب عميل. في حساب الوكالة، يحتوي نموذج خطاف الويب على مفتاح تبديل إضافي: التفعيل أيضًا لجميع حسابات العملاء. قم بتفعيله وسيتلقى خطاف الويب هذا أيضًا الأحداث التي تحدث في كل حساب عميل تابع لوكالتك — نقطة نهاية واحدة، للوكالة بأكملها.

كيف يعمل:

• تخبرك كتلة user بالعميل الذي ينتمي إليه الحدث. يحمل كل إشعار بالفعل كتلة user تحدد الحساب الذي وقع فيه الحدث، بحيث يمكن لأتمتتك التوجيه حسب العميل.
• تُطبق إعدادات خطاف الويب الخاص بك في كل مكان. تُستخدم الأحداث التي اخترتها، وسر التوقيع، وإعداد إعادة المحاولة لعمليات التسليم الخاصة بحسابات العملاء أيضًا.
• لا توجد عمليات تسليم مزدوجة. إذا كان لدى حساب العميل خطاف ويب خاص به يشير إلى نفس عنوان URL، فسيتم استخدام ذلك الخطاف لأحداث ذلك الحساب بدلاً من ذلك — لن يصل نفس الحدث مرتين إلى نقطة نهاية واحدة.
• لا يرى العملاء ذلك. لا يظهر خطاف الويب في صفحة خطافات الويب الخاصة بحساب العميل، ولا يمكن للعملاء إيقاف تشغيله — فهو تحت إدارتك.
• يتم تتبع الموثوقية لكل حساب عميل. إذا استمرت نقطة النهاية الخاصة بك في الفشل، فسيتم إيقاف تشغيلها تلقائيًا للحساب الذي فشلت عمليات تسليمه (راجع موثوقية خطاف الويب)، وليس للوكالة بأكملها في وقت واحد.

يظهر مفتاح التبديل فقط في حسابات الوكالات. كما يتم دعم إعداده عبر واجهة برمجة التطبيقات (API) — راجع حقل apply_to_sub_accounts في واجهة برمجة تطبيقات خطافات الويب.

أحداث التشغيل المتاحة #

يمكنك تمكين أو تعطيل كل حدث من أحداث خطاف الويب الـ 22 بشكل مستقل. عند إطلاق حدث ما، يرسل Your AI Connector إشعاراً إلى عنوان URL الخاص بخطاف الويب الخاص بك مع البيانات ذات الصلة. كل حدث، وما يعنيه، ورمز event الذي يضعه في الحمولة مدرجون معاً في أحداث خطاف الويب الـ 22 أدناه في هذه الصفحة.

من الجيد معرفته: خيارات إنشاء مهمة (Task Created)، وتحديث مهمة (Task Updated)، وإكمال مهمة (Task Completed) قابلة للتحديد بالكامل ويتم حفظها بشكل صحيح. كما أن إنشاء ملخص يومي (Daily Summary Created) هو إضافة حديثة أيضاً. راجع خطاف ويب إكمال المهمة أدناه لمعرفة شكل تلك الحمولة.

مشغلات خطاف الويب (Webhook) المستندة إلى الوسوم #

لا يقوم subscribed_to_tags بتحديد نطاق أحداث خطاف الويب بناءً على وسم (tag). بل يقوم فقط بتضييق نطاق الوسوم التي تنتج إشعاراً بملخص المحادثة. للحصول على طلب عند تطبيق وسم معين، قم بتعيين عنوان URL لخطاف الويب على ذلك الوسم في علامة التبويب الوسوم (Tags) الخاصة بالوكيل (أو الحملة).

لا يحتوي نموذج خطاف الويب نفسه على أداة اختيار الوسوم، سواء عند إنشاء خطاف ويب جديد أو عند تعديل واحد موجود، لذا لا يمكن قراءة subscribed_to_tags أو تغييره إلا من خلال واجهة برمجة تطبيقات خطافات الويب، أو عن طريق طلب الدعم.

من الجيد معرفته: تعديل خطاف ويب موجود يحتوي على قائمة subscribed_to_tags (إعادة تسميته، تغيير أحداثه، تبديل عمليات إعادة المحاولة) لم يعد يمسح تلك القائمة — نظراً لأن النموذج لا يحتوي على أداة اختيار وسوم لإرسالها مرة أخرى، فإن الحفظ من هذه الصفحة الآن يترك القائمة الموجودة دون تغيير. (كان هذا خطأً برمجياً حقيقياً قبل 21 يوليو 2026: كان الحفظ من نموذج خطاف الويب يمسح القائمة لأنه كان يرسل دائماً قائمة وسوم فارغة. إذا فقد خطاف الويب قائمة subscribed_to_tags الخاصة به قبل ذلك التاريخ، فسيحتاج إلى إعادة تكوينه من خلال واجهة برمجة التطبيقات.)

إنشاء ملخص لجهات الاتصال التي تم وسمها #

حيثما يحتوي خطاف الويب على قائمة subscribed_to_tags، يمكنك تشغيل إنشاء ملخص (Generate Summary). عند التمكين، يقوم Your AI Connector تلقائياً بإنشاء ملخص محادثة لجهة الاتصال عند تطبيق أحد تلك الوسوم، ويضمنه في بيانات خطاف الويب — سياق كامل دون الحاجة إلى طلب منفصل.

اختبار خطاف الويب الخاص بك #

1. افتح الإعدادات ← عمليات التكامل ← خطافات الويب (Webhooks).
2. في صف خطاف الويب الخاص بك، انقر على اختبار (Test).
3. تحقق من نظامك الخارجي للتأكد من استلامه لبيانات الاختبار.
4. راجع تنسيق البيانات للتأكد من أن نظامك يمكنه تحليلها بشكل صحيح.

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

ما الذي يُعد تسليماً ناجحاً #

سواء نقرت على Test (اختبار) أو تم تشغيل الحدث فعلياً، فإننا نرسل الشيء نفسه:

• طلب POST (وليس GET أبداً)، مع كون النص الأساسي بتنسيق JSON و Content-Type: application/json.
• الرؤوس المدرجة تحت الحمولات الموقعة. لا يتم تضمين رؤوس التوقيع إلا بمجرد تعيين سر توقيع.

نعتبر التسليم ناجحاً عندما:

• تستجيب نقطة النهاية الخاصة بك بأي حالة 2xx (200، 201، 204 — كلها مقبولة).
• تستجيب في غضون 30 ثانية.

بعض الأمور التي قد تفاجئ المستخدمين:

• يتم تجاهل نص الاستجابة. لست بحاجة إلى إرجاع أي JSON محدد. يكفي إرجاع استجابة فارغة برمز 200.
• تُحتسب عمليات إعادة التوجيه كفشل. نحن لا نتبع عمليات إعادة التوجيه، لذا يتم تسجيل أي استجابة برمز 301 أو 302 (بما في ذلك إعادة التوجيه بسبب الشرطة المائلة في النهاية، أو من http إلى https) كعملية تسليم فاشلة. احفظ عنوان URL النهائي، وليس العنوان الذي يؤدي إلى إعادة توجيه.
• سلاسل الاستعلام مدعومة بالكامل. يتم إرسال https://your-app.com/hook?token=abc123 تماماً كما حفظته، لذا فإن وضع رمز في سلسلة الاستعلام يعمل بنفس كفاءة وضعه في المسار.
• يجب أن يكون عنوان URL الخاص بك https:// ويمكن الوصول إليه بشكل عام. يتم رفض العناوين التي تنتمي إلى البنية التحتية الخاصة بـ Your AI Connector، ولكن نقاط النهاية الخاصة بك على Google Cloud Functions أو Cloud Run أو App Engine أو Firebase Hosting أو أي مكان آخر مقبولة.
• قد يقوم جدار حماية أو طبقة حماية من الروبوتات أمام نقطة النهاية الخاصة بك بحظرنا. الحالة الأكثر شيوعاً هي Cloudflare: إذا كانت منطقتك تحتوي على وضع “Bot Fight Mode” أو تحدٍ مُدار مفعّل، فسيحصل طلبنا على صفحة تحدٍ “Just a moment…” برمز 403 بدلاً من الوصول إلى خادمك — ولا يمكن لطلب من خادم إلى خادم تجاوز تحدي المتصفح أبداً، لذا يفشل كل من زر Test والأحداث الحقيقية بنفس الطريقة. سيخبرك زر الاختبار عندما يحدث هذا (“Cloudflare is showing a bot challenge to our request”). قم بإصلاح ذلك في Cloudflare باستخدام قاعدة أمان / WAF تتخطى التحديات لمسار خطاف الويب الخاص بك (أو لوكيل المستخدم Webhook-Delivery/1.0)، ثم انقر فوق Test مرة أخرى.
• إذا كان جدار الحماية الخاص بك يحتاج إلى قائمة سماح لعناوين IP بدلاً من ذلك (على سبيل المثال، خطة Cloudflare المجانية، حيث لا يمكن تخطي وضع Bot Fight Mode العادي بواسطة قاعدة WAF، ولكن قاعدة الوصول إلى IP المعينة على “سماح” تعمل قبلها)، يمكننا المساعدة: يتم إرسال كل عملية تسليم، سواء من زر Test أو من حدث مباشر، من عنوان IPv4 ثابت واحد (لا توجد نطاقات، لا يوجد IPv6، لا يوجد تبديل). اتصل بالدعم وسنعطيك العنوان لإضافته إلى قائمة السماح. احتفظ بـ التحقق من التوقيع كفحص ثقة فعلي، لأنه يتحقق من صحة كل حمولة بغض النظر عن مصدرها.
• تخبرك نتيجة الاختبار بالضبط بما أجابت به نقطة النهاية الخاصة بك. يُظهر الاختبار الفاشل الآن السبب الحقيقي (حالة HTTP التي أعادتها نقطة النهاية، أو انتهاء المهلة، أو أننا لم نتمكن من الوصول إلى العنوان على الإطلاق) بدلاً من خطأ عام، ويتم إرسال اختبار على خطاف ويب محفوظ موقعاً عند تفعيل التوقيع، تماماً مثل الحدث المباشر.

استخدام n8n أو Make أو Zapier (“رابط الاختبار” مقابل “رابط الإنتاج”) #

عادةً ما تمنحك منصات الأتمتة عنوانين مختلفين لخطافات الويب (webhook)، وهذا يسبب ارتباكاً للمستخدمين:

• رابط الاختبار (Test URL) (في n8n يحتوي على /webhook-test/). هذا الرابط يستقبل البيانات فقط أثناء مراقبتك النشطة للوحة العمل (canvas) وبعد نقرك مباشرة على الاستماع لحدث الاختبار (Listen for test event) (أو اختبار سير العمل (Test workflow)). إنه يلتقط حدثًا واحدًا ثم يتوقف عن الاستماع — لذا فإن النقر على اختبار في Your AI Connector عدة مرات متتالية يلتقط الحدث الأول فقط، وفقط إذا كانت نافذة الاستماع نشطة في تلك اللحظة بالضبط. للاختبار: انقر على الاستماع لحدث الاختبار في n8n أولاً، ثم عد إلى Your AI Connector وانقر على اختبار مرة واحدة.
• رابط الإنتاج (Production URL) (في n8n يحتوي على /webhook/، بدون -test). هذا هو الرابط الذي يجب لصقه في Your AI Connector للأحداث المباشرة. إنه يعمل فقط بمجرد تحويل سير العمل الخاص بك إلى نشط (Active). إذا لم يكن سير العمل نشطًا، سيرفض n8n الطلب بخطأ “404 / webhook not registered”، على الرغم من أن Your AI Connector أرسل البيانات بشكل صحيح.

باختصار: اختبر باستخدام رابط الاختبار (Test URL) أثناء الاستماع، ولكن لكي يستمر الـ webhook في العمل مع جهات الاتصال الحقيقية، احفظ رابط الإنتاج (Production URL) في Your AI Connector وتأكد من أن سير العمل نشط (Active).

تنسيق بيانات خطاف الويب #

عند إطلاق خطاف الويب، ترسل Your AI Connector بيانات منظمة (JSON) إلى عنوان URL الخاص بخطاف الويب. إذا كنت تستخدم منصة أتمتة مثل Zapier أو Make، فإنها تقوم بتحليل هذه البيانات لك تلقائيًا. إذا كنت تبني تكاملاً مخصصًا:

{
  "event": "contactCreated",
  "contact": { "id": "<contact-id>", "first_name": "Jane", "...": "..." },
  "campaign": { "id": "<campaign-id>", "name": "AI Receptionist", "status": "Live" },
  "agent": { "id": "<agent-id>", "name": "Front Desk" },
  "user": { "id": "<account-id>", "email": "owner@example.com" }
}

campaign أو agent — عادةً أحدهما، وليس كلاهما. إذا كان حسابك يستخدم وكلاء، فإن جهات الاتصال الخاصة بك تتبع وكيلاً بدلاً من حملة، لذا يصل campaign كـ null ويخبرك agent بمن تولى الأمر. الحسابات القديمة القائمة على الحملات ترى العكس. اقرأ أياً منهما المعبأ؛ لا تفترض أن campaign موجود دائماً.

وصلت كتلة agent في 15 أغسطس 2026. وهي توجد بجانب campaign في الأحداث المرتبطة بمحادثة — محادثة منتهية، عدم الإزعاج، استئناف، إلغاء الأرشفة، إيقاف مؤقت للذكاء الاصطناعي، رسالة جديدة، ملخص محادثة، وخطاف الويب (webhook) الذي يمكنك تعيينه على وسم — وتحمل id و name الخاصين بالوكيل المعالج، أو null عندما لا يكون هناك وكيل مشارك. إنها إضافة بحتة: كل حقل تتلقاه بالفعل يظل دون تغيير، لذا فإن المستقبل الذي بنيته قبل ذلك التاريخ يستمر في العمل دون الحاجة إلى تحديث أي شيء.

تضيف بعض الأحداث كتلة إضافية خاصة بها على المستوى الأعلى. على سبيل المثال، يضيف حدث حجز موعد (Appointment Booked) كتلة appointment (راجع خطاف حجز الموعد)، ويضيف حدث رسالة جديدة (New Message) كتلة message كاملة تحتوي على النص (راجع خطاف الرسالة الجديدة)، بينما تضيف أحداث التسليم (Deliveries) والقراءة (Reads) كتلة message قصيرة تحتوي فقط على معرف الرسالة وحالتها (راجع خطاف التسليم والقراءة).

تخبرك أحداث التسليم والقراءة بالرسالة المعنية، ولكن ليس بمحتواها. فهي تحمل كتلة message تحتوي على id وstatus الخاصين بالرسالة — وهذا الـ id هو نفس الـ messageId الذي يعيده نقطة نهاية إرسال الرسالة، لذا يمكنك مطابقة إيصال التسليم أو القراءة بالرسالة التي أرسلتها بالضبط — ولكن لا يوجد نص للرسالة. لا تحمل أحداث الردود (Replies) أي كتلة message على الإطلاق. إذا كنت بحاجة إلى الكلمات التي تم إرسالها أو استلامها، فاشترك في حدث رسالة جديدة (New Message) بجانبها.

أمران يجب معرفتهما قبل كتابة مستقبِل البيانات الخاص بك. لا يوجد حقل timestamp، ولا يوجد غلاف data. كل كتلة توجد في المستوى الأعلى من كائن JSON، كما هو موضح أعلاه.

أحداث خطاف الويب الـ 22 #

أحداث خطاف الويب الـ 22، مع تسمية العرض التي تحددها في التطبيق ورمز event المرسل في الحمولة. رمز event عبارة عن سلسلة قصيرة لا تطابق تسمية العرض، لذا قم بمطابقة جهاز الاستقبال الخاص بك بناءً على الرمز، وليس التسمية:

لا يظهر رمزان آخران في تلك القائمة لأنك لا تشترك فيهما: contact_tags_updated، المرسل بواسطة عنوان URL لخطاف ويب معين على وسم فردي، و summary_generated، المرسل عند كتابة ملخص دردشة لوسم في قائمة subscribed_to_tags الخاصة بخطاف الويب.

لم يتم إرسال “تم توصيل القناة” بعد. يظهر في قائمة الأحداث، ولكن لا يوجد شيء يرسله حالياً. لا تقم بالبناء بناءً عليه.

تستخدم الإشعارات القائمة على العلامات والمهام أشكالاً منفصلة خاصة بها. راجع Contact Tags Updated و Task Completed.

خطاف ويب إنشاء جهة اتصال (Contact Created Webhook) #

يتم إرساله عند تشغيل حدث إنشاء جهة اتصال (Contact Created) (إضافة جهة اتصال جديدة يدويًا، أو عبر الاستيراد، أو عبر واجهة برمجة التطبيقات API).

اسم الحدث #

contactCreated

تنسيق الحمولة (Payload) #

{
  "event": "contactCreated",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null,
    "is_bot_active": true,
    "ad_referral": null
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  }
}

نموذج “الاختبار” والحدث الحقيقي يبدوان مختلفين قليلاً. يرسل زر الاختبار بيانات نائبة (John Doe، حملة تجريبية). أما حدث “إنشاء جهة اتصال” الحقيقي فيحمل تفاصيل جهة الاتصال الفعلية، وقد تكون بعض الحقول فارغة اعتمادًا على القناة.

خطاف رسالة جديدة #

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

اسم الحدث #

new_message

تنسيق الحمولة (Payload) #

{
  "event": "new_message",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null,
    "is_bot_active": true,
    "ad_referral": null
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<message-id>",
    "body": "Hi, are you open on Saturday?",
    "direction": "inbound",
    "status": "received",
    "created_at": "2026-07-30T17:27:06.000Z",
    "channel": "whatsapp_web"
  }
}

لا تزال لا توجد كتلة campaign في حمولة البيانات هذه. ترسل الرسالة الجديدة contact، و agent، و user، و message. تمت إضافة كتلة agent في 15 أغسطس 2026 وتخبرك بالوكيل الذي يعالج المحادثة؛ إذا كنت بحاجة إلى سياق الحملة أيضاً، فابحث عن جهة الاتصال عبر واجهة برمجة التطبيقات (API) باستخدام contact.id.

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

خطاف التسليم والقراءة #

يُبلغ هذان الحدثان عما حدث لرسالة بعد مغادرتها Your AI Connector: يتم إطلاق حدث التسليم (Deliveries) عندما تصل الرسالة إلى جهة الاتصال (أو تفشل في ذلك)، ويتم إطلاق حدث القراءة (Reads) عندما تفتحها جهة الاتصال، وذلك على القنوات التي تدعم إيصالات القراءة.

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

أسماء الأحداث #

delivered وundelivered لحدث التسليم، وread لحدث القراءة.

تنسيق الحمولة (Payload) #

{
  "event": "delivered",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "ad_referral": null
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<message-id>",
    "status": "delivered"
  }
}

كيفية مطابقة تحديث بالرسالة التي أرسلتها. قم بتخزين الـ messageId الذي تحصل عليه عند إرسال رسالة عبر واجهة برمجة التطبيقات. عندما يصل إشعار التسليم أو القراءة، ابحث عن ذلك المعرف المخزن مقابل message.id في الحمولة — هذا هو إيصال التسليم أو القراءة الخاص بتلك الرسالة بالضبط.

لا يوجد نص رسالة هنا. تحمل كتلة message المعرف والحالة فقط. اشترك في رسالة جديدة إذا كنت بحاجة إلى محتوى الرسالة أيضاً.

تكون كتلة message موجودة فقط عندما نعرف أي رسالة كانت. في التحديث النادر الذي لا يمكننا ربطه برسالة مخزنة، يتم استبعاد الكتلة تماماً بدلاً من إرسالها فارغة — لذا تحقق من وجود message قبل قراءة message.id.

إشعار واحد لكل تغيير في الحالة. تنتج الرسالة الصادرة الواحدة عادةً إشعار delivered ثم، على القنوات التي تدعم إيصالات القراءة، إشعار read. ينتج عن الإرسال الفاشل undelivered بدلاً من ذلك.

Appointment Booked Webhook #

يتم تشغيله عندما تحجز جهة اتصال موعدًا. يتم تشغيله بنفس الطريقة سواء حجز الذكاء الاصطناعي الموعد أثناء محادثة، أو قمت أنت بحجزه يدويًا، أو جاء عبر واجهة برمجة التطبيقات API.

اسم الحدث #

booked

تنسيق الحمولة (Payload) #

{
  "event": "booked",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith"
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com"
  },
  "appointment": {
    "appointment_id": "<appointment-id>",
    "start_time": "2026-07-20T15:00:00.000Z",
    "end_time": "2026-07-20T15:30:00.000Z",
    "status": "confirmed",
    "room_name": "Room 1",
    "description": "Discovery call",
    "summary": "30 min intro",
    "google_calendar_event_id": null,
    "event": {
      "id": "<service-id>",
      "event_name": "Intro Call",
      "slot_duration": 30,
      "location": "Zoom",
      "meeting_link": "https://...",
      "event_type": "online"
    }
  }
}

غالبًا ما يكون google_calendar_event_id هو null في خطاف الويب هذا، وهذا أمر طبيعي. يتم إنشاء حدث تقويم Google في نفس لحظة إرسال هذا الإشعار، لذا عادةً لا يكون المعرف جاهزًا بعد. أعد جلب الموعد بواسطة appointment_id الخاص به بعد لحظات إذا كنت بحاجة إليه. يظل null بشكل دائم إذا لم يكن الحساب متصلاً بتقويم Google، لذا لا تنتظره للأبد.

زر “الاختبار” لا يتضمن كتلة appointment. استخدمه لتأكيد استجابة نقطة النهاية الخاصة بك، ثم قم بإجراء حجز حقيقي واحد لرؤية الحمولة الكاملة.

هناك حالتان لا يتم فيهما إطلاق خطاف الويب (webhook) هذا: المواعيد المستوردة من تقويم خارجي، والحجوزات التي تأتي من خلال تكامل Formitable.

خطاف الويب لتحديث وسوم جهات الاتصال #

يتم التشغيل عند تطبيق وسم (tag) على جهة اتصال، وكان لهذا الوسم عنوان URL لخطاف الويب (webhook) تم تكوينه على الوكيل أو الحملة التي تنتمي إليها جهة الاتصال.

اسم الحدث #

contact_tags_updated

متى يتم إطلاقها #

• يتم تطبيق وسم على جهة اتصال لديها وكيل معين، أو حملة معينة، أو كلاهما.
• يحتوي واحد على الأقل من الوسوم المطبقة على عنوان URL لخطاف الويب تم تعيينه في علامة التبويب “الوسوم” (Tags) الخاصة بذلك الوكيل أو الحملة.

إذا كانت جهة الاتصال مرتبطة بكليهما وكانت وسوم الحملة تحمل عناوين URL لخطاف الويب، فسيتم اعتمادها؛ وإلا فسيتم استخدام وسوم الوكيل.

إذا تم تطبيق وسوم متعددة ذات عناوين URL مختلفة لخطافات الويب في نفس التحديث، يتم إرسال طلب واحد لكل عنوان URL، ويحتوي كل منها فقط على الوسوم التي ترتبط بعنوان URL ذلك.

إزالة وسم لا تؤدي أبداً إلى إرسال طلب. يقوم معظم الأشخاص بتوجيه عناوين URL هذه إلى إجراء ما — مثل تحصيل وديعة، أو حجز موعد، أو تنبيه ممثل — لذا كان يُستخدم سابقاً وسم يتم إزالته من جهة اتصال لإعادة تشغيل ذلك الإجراء. لم يعد بإمكانه القيام بذلك. لا تزال عملية الإزالة تظهر في removed_tags عندما تحدث في نفس التحديث مع عملية تطبيق تذهب إلى نفس عنوان URL، لذا فإن الأتمتة التي تقرأ كلا المصفوفتين تحتفظ بالصورة الكاملة؛ ما لن تراه أبداً هو طلب ناتج عن عملية إزالة وحدها. (تم التغيير في 12 أغسطس 2026. قبل ذلك التاريخ، كانت عمليات الإزالة ترسل طلباً أيضاً.)

تنسيق الحمولة (Payload) #

{
  "event": "contact_tags_updated",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "is_bot_active": true,
    "ad_referral": {
      "ctwa_clid": "ARAbc123...",
      "source_id": "120210000000000",
      "source_type": "ad",
      "source_url": "https://fb.me/xxxx",
      "headline": "Get 20% off today",
      "body": "Message us now to claim your discount",
      "channel": "whatsapp"
    }
  },
  "added_tags": ["qualified-lead"],
  "removed_tags": ["new-lead"],
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  }
}

اختبار خطاف الويب (webhook) الخاص بالوسم #

بجوار حقل عنوان URL الخاص بخطاف الويب في علامة التبويب “الوسوم” (Tags)، يوجد زر اختبار (Test). يقوم هذا الزر بإرسال حمولة نموذجية إلى عنوان URL ذلك على الفور، حتى تتمكن من التأكد من أن أتمتتك تستقبلها قبل انتظار محادثة حقيقية.

يرسل الاختبار نفس شكل contact_tags_updated الموضح أعلاه، باستخدام جهة اتصال نائبة، مع الوسم الذي تختبره في added_tags و removed_tags فارغ. ما تراه أتمتتك في الاختبار هو ما ستراه في بيئة الإنتاج.

أمران يجب معرفتهما:

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

إذا فشل الاختبار، تخبرك الرسالة بما أجابت به نقطة النهاية الخاصة بك (على سبيل المثال 404 أو 500)، وهو ما يكفي عادةً لاكتشاف عنوان URL خاطئ أو سير عمل لم يتم تشغيله.

خطاف الويب لإكمال المهام #

للمرجعية فقط. تم توثيق خطافات ويب المهام (كبيانات) هنا للمطورين؛ أحداث إنشاء مهمة و تحديث مهمة و إكمال مهمة قابلة للتحديد في قائمة الأحداث القياسية في نموذج خطاف الويب مثل أي حدث آخر — راجع أحداث المشغل المتاحة و أحداث خطاف الويب الـ 22.

يتم إرسال حمولة البيانات هذه عندما تنتقل المهمة إلى مرحلة محددة كمرحلة إكمال. أما المهمة التي تنتقل بين مراحل غير مراحل الإكمال فترسل الشكل taskUpdated بدلاً من ذلك.

اسم الحدث #

taskCompleted

متى يتم إطلاقها #

• يتم تحديث مهمة ما.
• تغيرت قيمة stage الخاصة بها مقارنة بقيمتها السابقة.
• تم تكوين المرحلة الجديدة كمرحلة إكمال في إعدادات مراحل المهام الخاصة بالحساب.

تنسيق الحمولة (Payload) #

{
  "event": "taskCompleted",
  "contact": {
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null
  },
  "user": {
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<task-id>",
    "title": "Follow up with Jane",
    "description": "Confirm pricing and send proposal",
    "type": "follow_up",
    "priority": "high",
    "stage": "<stage-id>",
    "due_date": "2026-01-20T15:00:00Z",
    "source": "ai",
    "source_detail": "<source-detail>",
    "campaign_id": "<campaign-id>",
    "linked_human_alert": "<human-alert-id>",
    "tags": ["qualified-lead"],
    "notes": "Customer requested a callback"
  }
}

إيقاف تشغيل Webhook (أو حذفه) #

يحتوي كل خطاف ويب على مفتاح تشغيل/إيقاف، موجود مباشرة في صفه. يؤدي إيقاف تشغيل أحدها إلى توقفه عن تلقي الأحداث، ولكنه يحتفظ بكل ما قمت بتكوينه — عنوان URL، والأحداث، وأي سر توقيع. أعد تشغيله وسيكمل من حيث توقف؛ لن يتم تسليم أي شيء حدث أثناء فترة إيقافه لاحقاً.

استخدم هذا الخيار عندما تريد إيقاف عمليات التسليم لفترة من الوقت: إذا كنت تعيد بناء نقطة النهاية الخاصة بك، أو تقوم بتصحيح أخطاء تكامل مزعج، أو تقوم بإيقاف أتمتة مؤقتاً.

يؤدي حذف خطاف الويب (أيقونة سلة المهملات في صفه) إلى إزالته نهائياً، بما في ذلك سر التوقيع الخاص به. إذا كنت تريد فقط إيقاف عمليات التسليم، فقم بإيقاف تشغيله بدلاً من ذلك — الحذف مخصص للحالات التي تنتهي فيها من استخدام نقطة النهاية تماماً.

هذا يختلف عن إيقاف تشغيل خطاف الويب (webhook) تلقائيًا. إذا قمنا بتعطيل خطاف الويب الخاص بك بعد فشله بشكل متكرر (راجع موثوقية خطاف الويب)، فلن يؤدي زر التبديل أعلاه إلى إعادته. بمجرد إصلاح نقطة النهاية الخاصة بك، قم بتحرير خطاف الويب واحفظه مع تغيير عنوان URL (أي تغيير في عنوان URL يعيد تفعيله)، أو اتصل بـ نقطة نهاية إعادة التفعيل عبر واجهة برمجة التطبيقات (API) — أو اطلب من الدعم وسنقوم بإعادة تفعيله لك.

الحمولات الموقعة (التحقق من أن خطاف الويب (Webhook) جاء منا حقاً) #

يمكن لأي شخص يعرف عنوان URL الخاص بخطاف الويب الخاص بك إرسال طلب مزيف إليه. إذا كنت تتخذ إجراءات بناءً على خطافات الويب تلقائياً — مثل تحديث الفواتير أو إنشاء سجلات CRM — فإن تفعيل التوقيع يتيح لك التحقق من أن كل طلب جاء منا حقاً.

التوقيع اختياري ومعطل افتراضياً، وتقوم بتفعيله لكل خطاف ويب على حدة، من عرض تحرير خطاف الويب ذلك (افتح صف خطاف الويب المحفوظ).

تفعيل التوقيع #

1. افتح خطاف الويب (الإعدادات ← عمليات التكامل ← خطافات الويب ← انقر على صف خطاف الويب الخاص بك).
2. في قسم سر التوقيع، انقر على إنشاء.
3. انسخ السر (يبدأ بـ whsec_) وقم بتخزينه في نظام الاستقبال الخاص بك. تعامل معه ككلمة مرور.

يمكنك العودة وكشف السر، أو نسخه، أو تدويره، أو إيقاف تشغيله في أي وقت من نفس هذه اللوحة.

ما نرسله #

بمجرد تفعيل التوقيع، سيحمل كل تسليم لخطاف الويب هذا رأسي HTTP إضافيين:

هذه الرؤوس الثلاثة موجودة في كل عملية تسليم، سواء كانت موقعة أم لا:

كيفية التحقق #

التوقيع هو HMAC-SHA256 للسلسلة <timestamp>.<raw request body>، باستخدام سر التوقيع الخاص بك كمفتاح.

تحقق مقابل نص الطلب الخام — البايتات الدقيقة التي تلقيتها. إذا قام إطار العمل الخاص بك بتحليل JSON وإعادة تسلسله قبل التحقق، فقد تتغير البايتات ولن يتطابق التوقيع.

مثال Node.js:

const crypto = require("crypto");

function verify(rawBody, headers, secret) {
  const timestamp = headers["x-webhook-timestamp"];
  const signature = headers["x-webhook-signature"]; // "v1=<hex>"

  // Reject anything older than 5 minutes so a captured request can't be replayed later.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");

  return crypto.timingSafeEqual(Buffer.from(signature.replace("v1=", "")), Buffer.from(expected));
}

مثال Python:

import hashlib, hmac, time

def verify(raw_body: bytes, headers, secret: str) -> bool:
    timestamp = headers["X-Webhook-Timestamp"]
    signature = headers["X-Webhook-Signature"].replace("v1=", "")

    # Reject anything older than 5 minutes so a captured request can't be replayed later.
    if abs(time.time() - int(timestamp)) > 300:
        return False

    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest()

    return hmac.compare_digest(signature, expected)

قارن التوقيعات باستخدام دالة آمنة ضد هجمات التوقيت (timingSafeEqual / compare_digest)، وليس ==. هذا لا يكلف شيئاً ويجنبك فئة خفية من الهجمات.

تدوير السر #

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

إيقاف التوقيع ببساطة يوقف إرسال ترويسات التوقيع.

إعادة محاولة عمليات التسليم الفاشلة #

افتراضياً، لا تتم إعادة محاولة التسليم الذي يفشل — إذا كان نظامك معطلاً في تلك اللحظة، فسيتم فقدان ذلك الحدث.

قم بتفعيل إعادة محاولة عمليات التسليم الفاشلة (Retry failed deliveries) على خطاف الويب (في نموذج الإنشاء/التعديل) وسنستمر في المحاولة:

يستغرق ذلك حوالي ساعتين و40 دقيقة، لذا يمكن لخطاف الويب تجاوز نافذة الصيانة أو انقطاع قصير من جانبك.

ما الذي تتم إعادة محاولته: المشكلات المؤقتة — مثل إرجاع خادمك لخطأ 5xx، أو انتهاء المهلة، أو فشل الاتصال.

ما لا نقوم بإعادة محاولته: إذا رفضت نقطة النهاية الخاصة بك الطلب نفسه (أي رمز خطأ 4xx)، فإننا لا نعيد المحاولة — فإرسال الطلب المتطابق مرة أخرى لن يؤدي إلا إلى نفس الرفض.

الأحداث التي تتم إعادة محاولتها: خطافات الويب الخاصة بالوسوم (contact_tags_updated)، وأحداث المهام الثلاثة، والملخص اليومي. أما البقية فيتم إرسالها مرة واحدة، لذا لا يوجد شيء يعمل عليه مفتاح التبديل بالنسبة لها. لا يزال كل حدث يحمل X-Webhook-Delivery، لذا تغطي قاعدة إلغاء التكرار الواحدة جميع هذه الأحداث.

قم بتفعيل عمليات إعادة المحاولة فقط إذا كانت نقطة النهاية الخاصة بك تدعم التكرار (idempotent). تعني عمليات إعادة المحاولة أن الحدث نفسه قد يصل أكثر من مرة. استخدم الترويسة X-Webhook-Delivery للتعرف على التكرار: فهي تظل ثابتة عبر كل محاولة لنفس الحدث، لذا يمكنك تجاهل المعرف (ID) الذي تعاملت معه بالفعل بأمان.

تتفاعل عمليات إعادة المحاولة مع ميزة الإيقاف التلقائي بعد الإخفاقات المتكررة (راجع موثوقية خطاف الويب) بالطريقة التي تتوقعها: يحسب عداد الإخفاق عملية تسليم كاملة، فقط بعد استنفاد كل محاولة إعادة محاولة — وليس كل محاولة فردية.

موثوقية خطاف الويب (Webhook) #

• ترسل Your AI Connector خطافات الويب عبر اتصال آمن (HTTPS). تأكد من أن عنوان الويب الذي تقدمه يستخدم HTTPS.
• إذا أرجع نظامك خطأً، فسيتم اعتبار التسليم فاشلاً.
• راقب وقت تشغيل النظام المتلقي لتجنب فقدان الأحداث.
• لسير العمل الهام، قم بتشغيل إعادة محاولة عمليات التسليم الفاشلة، وفكر في آلية احتياطية أيضًا.

يتم إيقاف تشغيل خطافات الويب (webhooks) تلقائيًا بعد الفشل المتكرر. إذا فشل عنوان URL الخاص بخطاف الويب بشكل متكرر (حوالي 5 أخطاء متتالية، أو 3 أخطاء متتالية لأخطاء من نوع التكوين)، فإن Your AI Connector يتوقف تلقائيًا عن إرسال الأحداث إلى عنوان URL هذا. لإعادته للعمل بمجرد أن تصبح نقطة النهاية الخاصة بك سليمة: قم بتحرير خطاف الويب واحفظه مع تغيير عنوان URL (أي تغيير في عنوان URL يعيد تفعيله)، أو استخدم نقطة نهاية إعادة التفعيل عبر واجهة برمجة التطبيقات (API) — فالحفظ مرة أخرى بنفس عنوان URL لا يكفي. يمكن للدعم أيضًا إعادة تفعيله لك.

استكشاف الأخطاء وإصلاحها #

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

• تكامل GoHighLevel — استخدم خطافات الويب لدمج Your AI Connector مع GHL.
• الوصول إلى API — اجمع بين خطافات الويب وAPI للحصول على أتمتة قوية.
• استخدام العلامات لتصنيف جهات الاتصال — قم بإعداد علامات تؤدي إلى تشغيل خطافات الويب الخاصة بك.