فشل Webhooks، وأخطاء API، ومشكلات مزامنة CRM

مشكلات التكامل الشائعة بنظرة سريعة

Webhook لا يعمل

1. 1

   تحقق أن رابط Webhook قابل للوصول عامًا

   يجب أن يكون رابط Webhook نقطة نهاية HTTPS عامة. روابط localhost والعناوين الداخلية و HTTP (بدون HTTPS) لن تعمل. اختبر قابلية الوصول بإرسال طلب curl للرابط من جهاز خارجي.

2. 2

   تأكد من اختيار أنواع الأحداث الصحيحة

   انتقل إلى لوحة التحكم > الإعدادات > Webhooks وتحقق أنواع الأحداث المفعّلة لـ Webhook الخاص بك. إذا اخترت "conversation.closed" فقط لكنك تتوقع أحداث "conversation.created"، لن تستقبلها.

3. 3

   تحقق من سجلات Webhook لرموز حالة HTTP

   في إعدادات Webhook، راجع سجل التسليم. تعرض كل محاولة رمز حالة HTTP الذي أعادته نقطة نهايتك. 200 يعني نجاح. 4xx أو 5xx يعني أن خادمك رفض أو فشل في معالجة الطلب.

4. 4

   استخدم ميزة "إرسال Webhook تجريبي"

   انقر "إرسال تجريبي" في إعدادات Webhook. يرسل Teammates.ai حدثًا تجريبيًا لنقطة نهايتك. تحقق من سجلات خادمك لتأكيد الاستقبال والمعالجة الصحيحة.

5. 5

   تحقق من التحقق من التوقيع

   إذا كان خادمك يتحقق من توقيعات Webhook، تأكد أن سر التوقيع في كودك يطابق الموجود في لوحة التحكم > الإعدادات > Webhooks. عدم التطابق يجعل خادمك يرفض الأحداث الصالحة بخطأ 401 أو 403.

أخطاء API 401/403

1. 1

   أعد إنشاء رمز API

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

2. 2

   تحقق من تنسيق رأس Authorization

   يتوقع API التنسيق: Authorization: Bearer YOUR_TOKEN. تأكد من عدم وجود مسافات زائدة أو بادئة "Bearer" مفقودة أو مشكلات ترميز في رؤوس طلبك.

3. 3

   تحقق من صلاحيات الرمز

   إذا حصلت على 403 (وليس 401)، فرمزك صالح لكنه يفتقر للصلاحيات للإجراء المطلوب. تأكد أن المستخدم الذي أنشأ الرمز يملك الدور الصحيح (مالك، مدير نظام، مدير) لنقطة نهاية API التي تستدعيها.

4. 4

   تحقق من حدود المعدل

   إذا أرسلت طلبات كثيرة في وقت قصير، يعيد API خطأ 429 (طلبات كثيرة). تحقق من رؤوس الاستجابة لمعلومات حد المعدل وأضف منطق إعادة المحاولة مع تأخير تراجعي لكودك.

مشكلات مزامنة CRM

1. 1

   أعد تفويض اتصال CRM

   انتقل إلى لوحة التحكم > التكاملات وتحقق هل يعرض CRM (Salesforce أو HubSpot أو غيره) "متصل". إذا عرض "غير متصل" أو "منتهي"، انقر "إعادة التفويض" لتجديد رمز OAuth.

2. 2

   راجع تعيين الحقول

   في إعدادات تكامل CRM، تحقق أن حقول Teammates.ai ترتبط بحقول CRM الصحيحة. عدم التطابق (مثلًا ربط "البريد الإلكتروني" بحقل "الهاتف" في CRM) يجعل البيانات تظهر في المكان الخطأ أو لا تظهر إطلاقًا.

3. 3

   تحقق من صلاحيات مستخدم CRM

   يحتاج حساب مستخدم CRM المستخدم للتكامل إلى صلاحيات قراءة/كتابة للكائنات التي يزامنها Teammates.ai (جهات الاتصال، العملاء المحتملون، الصفقات، الأنشطة). إذا افتقر المستخدم للصلاحيات، تفشل المزامنة بصمت.

4. 4

   تحقق من سجلات المزامنة

   في لوحة التحكم > التكاملات > CRM الخاص بك، راجع سجل المزامنة. المزامنات الفاشلة تعرض تفاصيل الخطأ (مثلًا "حقل مطلوب مفقود"، "سجل مكرر"، "صلاحية مرفوضة") التي تحدد المشكلة بدقة.

الحصول على مساعدة إضافية