الوثائق التقنية

نظرة عامة على البنية

• الزحف — جلب الصفحات من نطاقك وفق sitemap والروابط الداخلية
• الرندر — رندر الصفحات الثقيلة بـJavaScript قبل الاستخراج
• الاستخراج — استخراج المحتوى بما في ذلك البيانات المهيكلة
• التقسيم — تقسيم المحتوى إلى مقاطع دلالية
• التمثيل — تحويل المقاطع إلى تمثيلات متجهية
• الفهرسة — تخزين التمثيلات للاسترجاع
• الاسترجاع — جلب المقاطع ذات الصلة بالتشابه الدلالي
• التوليد — صياغة الإجابة من المحتوى المسترجع
• الاقتباس — ربط صفحة المصدر عند العثور على محتوى ذي صلة

الزحف

ما الذي نزحفه

• صفحات HTML من sitemap أو الروابط الداخلية
• البيانات المهيكلة (JSON‑LD، schema.org)
• مستندات مرفوعة يدويًا (PDF، HTML، DOCX)

سلوك الزحف

• يحترم robots.txt
• User‑Agent محدد
• تحديد المعدل لتفادي حمل الخادم
• يتراجع عند 429 أو 5xx

رندر JavaScript — تُرندر الصفحات باستخدام متصفح دون واجهة قبل الاستخراج لـSPA والمحتوى الديناميكي.

إعادة الفهرسة

• مراقبة sitemap تُطلق إعادة فهرسة تلقائية
• إعادة فهرسة يدوية متاحة في أي وقت
• إعادة فهرسة مجدولة حسب الخطة

الاسترجاع

البحث الدلالي يتم تحويل الاستعلامات إلى تمثيلات ومطابقتها بالتشابه الدلالي، لا بالكلمات المفتاحية.

عتبات الصلة قابلة للتكوين. عتبة أعلى = إجابات أقل لكن أكثر ثقة. عتبة أقل = تغطية أوسع وأسئلة توضيحية أكثر.

توليد الإجابة

يمرر المحتوى المسترجع كنص سياقي للنموذج. تُبنى الإجابات فقط من هذا السياق.

مراجع المصدر — عند العثور على محتوى ذي صلة، تتضمن الإجابة رابط الصفحة. عند الاعتراف بعدم اليقين قد لا يوجد مرجع لعدم وجود مصدر.

سلوك الحدود

• يعترف بما لا يعرف
• يسأل أسئلة توضيحية
• يقترح مواضيع مرتبطة

تكامل التضمين

التثبيت مقطع سكربت واحد. تحميل غير متزامن.

التوافق

• WordPress
• Webflow
• Shopify
• Squarespace
• بُنى مخصصة
• SPA (React، Vue، Angular)

الإعداد عبر لوحة التحكم

• الألوان، الشعار، الموضع
• رسالة الترحيب، النبرة
• إعدادات اللغة
• عتبات الصلة

واجهة برمجة التطبيقات العامة

وصول آمن ومقيّد بالمستأجر لواجهات التذاكر والإجراءات عبر القنوات.

المصادقة والوصول

• أرسل مفتاح API في ترويسة `X-Api-Key`.
• أنشئ المفاتيح وألغها من Admin → API keys؛ مفتاح واحد لكل تكامل.
• المفاتيح مقيّدة بالمستأجر وتطبق أقلّ الصلاحيات عبر scopes.

النطاقات

• `support.read` — عرض التذاكر والرسائل والإجراءات واسترجاعها.
• `support.write` — إنشاء/تحديث التذاكر وإضافة الرسائل.
• `support.actions` — تنفيذ الإجراءات والاستعلام عن حالتها.

نقاط النهاية الأساسية

• `/api/v1/public/tickets` — عرض التذاكر أو إنشاؤها.
• `/api/v1/public/tickets/{ticket_id}` — جلب تفاصيل التذكرة أو تحديثها.
• `/api/v1/public/tickets/{ticket_id}/messages` — عرض الرسائل أو إضافتها.
• `/api/v1/public/tickets/{ticket_id}/actions` — تنفيذ إجراء لتذكرة.
• `/api/v1/public/actions` — عرض الإجراءات أو جلب حالتها.

تنسيق الاستجابة

• استجابات JSON؛ الطوابع الزمنية بتنسيق RFC 3339.
• الأخطاء تُرجع `{ error: { type, message, code } }`.
• نقاط النهاية القائمة تقبل `limit` و`page_token`.

قيم القنوات

• `web`, `email`, `sms`, `whatsapp`, `social`, `voice`, `custom`.
• استخدم `channel_id` و`channel_thread_id` لربط المحادثات الخارجية.
• استخدم `external_message_id` لمنع تكرار الرسائل.

إعداد Zapier

اربط Threada بـ Zapier لأتمتة بدون كود بسطح تحكم مضبوط.

أتمتة صادرة (Threada → Zapier)

• أنشئ Zap بمشغل “Catch Hook” من Webhooks by Zapier واحتفظ بعنوان URL للـ hook.
• في Admin → Support → Integrations أضف تكامل Zapier مع رابط الـ webhook وترويسة سرية اختيارية.
• استخدم إجراء HTTP مخصص لإرسال الحمولة؛ إذا لم يتم اختيار تكامل HTTP مخصص فسيتم استخدام Zapier افتراضيًا.

أتمتة واردة (Zapier → Threada)

• أنشئ مفتاح API بنطاقات محددة لـ Zapier (أقلّ صلاحيات).
• استخدم Webhooks by Zapier لاستدعاء نقاط نهاية API العامة للتذاكر والإجراءات.
• احفظ المفتاح بأمان في Zapier ودوّرَه وفق جدول.

ممارسات مؤسسية

• افصل المفاتيح حسب البيئة (الإنتاج مقابل التجربة).
• ألغِ المفاتيح عند تعطيل Zap أو تغيير المالك.
• فضّل النطاقات للقراءة فقط ما لم تكن الأتمتة تحتاج للكتابة.

الأمان

الاستضافة: GCP، افتراضيًا US‑Central1. التشفير: TLS 1.2+ أثناء النقل وAES‑256 أثناء التخزين. المصادقة: SSO عبر OIDC/SAML (Enterprise). الامتثال: متوافق مع GDPR، احتفاظ قابل للتكوين، سجلات تدقيق. نموذج التهديد يغطي prompt injection وXSS وSSRF وتسريب البيانات.

معالجة البيانات

المخزن

• المحتوى المفهرس
• التمثيلات
• سجلات الدردشة
• التحليلات
• الإعدادات

غير مخزن

• معلومات الدفع (تُعالج بواسطة المزود)
• بيانات اعتماد بنص واضح

الاحتفاظ قابل للتكوين حسب المستأجر. حذف عند الطلب.

التدريب لا يُستخدم محتواك لتدريب نماذج الذكاء الاصطناعي.