# أداة الدردشة

## دليل دمج أداة الدردشة في الموقع الإلكتروني

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


### إنشاء وتكوين أداة الدردشة

**كيفية الوصول إلى هناك:**

1. انقر على **الإعدادات (Settings)** بالقرب من أسفل الشريط الجانبي الأيسر. (على الهاتف، اضغط أولاً على أيقونة القائمة **☰** في الزاوية العلوية لفتح الشريط الجانبي.)
2. في الشريط الجانبي للإعدادات، تحت **القنوات (Channels)**، انقر على **القنوات (Channels)**.
3. ابحث عن بطاقة **أداة دردشة الموقع (Website chat widget)**.
4. إذا لم تكن لديك أداة بعد، انقر على **اتصال (Connect)** لإنشاء واحدة باسم عرض ورسالة ترحيب.
5. بمجرد إنشائها، انقر على **إدارة (Manage)** في أي وقت لفتح لوحة التكوين الكاملة.


التغييرات التي تحفظها تُطبق على أداتك المباشرة تلقائياً — لا حاجة لإعادة لصق كود التثبيت بعد إجراء أي تغيير.

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

### ما يمكنك تخصيصه

لوحة الإدارة منظمة في أربعة أقسام.

#### المظهر

- **سمة النمط:** أعد تصميم الأداة بالكامل بنقرة واحدة. تحدد ست سمات المظهر والألوان والزوايا والخط معاً: **Classic** (المظهر الأصلي الصلب — شريط رأس ملون على لوحة مسطحة)، و **Glass** (لوحة شفافة بلورية تعمل على تمويه الصفحة خلفها بنعومة، مع ظهور الرأس ومربع الرسائل كبطاقات مستديرة بداخلها)، و **Midnight** (نمط Glass بألوان داكنة)، و **Bloom** (وردي ناعم، بزوايا أكثر استدارة)، و **Ember** (نمط Glass بلون برتقالي دافئ)، و **Mono** (أسود وأبيض، بزوايا حادة). السمة هي نقطة بداية — بعد اختيار واحدة، لا يزال بإمكانك تغيير أي لون أو إعداد بشكل فردي. تبدأ الأدوات الجديدة بنمط Glass؛ التبديل فوري في كل مكان يتم فيه تضمين الأداة، دون الحاجة إلى تغييرات في الكود على موقعك.
- **الزوايا والخط:** مقبضان مستقلان للنمط. يحدد **الزوايا** مدى استدارة اللوحة والفقاعات والأزرار (مستديرة، ناعمة، أو حادة)، ويختار **الخط** نوع الخط الذي يراه الزوار (افتراضي، Serif، مستدير، أو Mono) — تأتي الخطوط من الخطوط الموجودة بالفعل على جهاز الزائر، لذا لا يتم تحميل أي شيء إضافي على موقعك.
- **اسم العرض:** يظهر في رأس الأداة.
- **الشعار:** قم بتحميل صورة تظهر في أعلى الدردشة. استخدم شعار شركتك أو صورة شخصية ودودة.
- **أيقونة المشغل:** الأيقونة الموجودة على زر الدردشة العائم نفسه. اختر واحدة من الأيقونات المدمجة (فقاعة دردشة، طائرة ورقية، علامة استفهام، والمزيد)، أو أعد استخدام شعارك الذي قمت بتحميله، أو قم بتحميل صورة منفصلة خاصة بك — مفيد إذا كنت تريد صورة لعضو حقيقي من الفريق يرحب بالزوار.
- **الألوان:** خمسة ألوان، كل منها يحدد الجزء الذي يلوننه في الأداة. **لون العلامة التجارية** هو للزر العائم، والرأس، ورسائل الزائر نفسه، مع **نص العلامة التجارية** للنص الموجود فوقه. **فقاعة البوت** هي خلفية ردود البوت ومؤشر الكتابة، مع **نص فقاعة البوت** للكلمات بداخلها ونقاط الكتابة المتحركة. **نافذة الدردشة** هي اللوحة الموجودة خلف جميع الرسائل. اختر لوناً لفقاعة البوت يختلف بوضوح عن لون علامتك التجارية — إذا تطابق الاثنان، فسيظهر جانبا المحادثة بنفس اللون ولن يتمكن الزوار من التمييز بين ردود البوت وردودهم. فقاعة بوت رمادية فاتحة مع نص داكن بجانب لون علامتك التجارية هي التركيبة الآمنة.
- **الموضع:** ضع زر الدردشة العائم في الزاوية **السفلية اليمنى** أو **السفلية اليسرى**، مع إزاحة أفقية ورأسية (بالبكسل) إذا كان يتداخل مع شيء آخر على صفحتك.
- **أسئلة البداية:** اقتراحات للرد السريع (شرائح قابلة للنقر) تظهر في الدردشة حتى يتمكن الزوار من البدء بنقرة واحدة بدلاً من الكتابة — على سبيل المثال "ما هي أسعاركم؟" أو "هل تقدمون الدعم؟" — بحد أقصى 10 أسئلة.


#### السلوك

- **رسالة الترحيب:** أول رسالة يراها الزوار عند فتح الدردشة (على سبيل المثال، "كيف يمكنني مساعدتك؟").
- **الصوت:** تشغيل صوت عند وصول رسالة جديدة في الدردشة.
- **طلب إذن الإشعارات:** مطالبة الزوار اختيارياً بالسماح بإشعارات المتصفح، حتى يتم تنبيههم بالردود حتى عند تبديل علامات التبويب.
- **فقاعة منبثقة استباقية:** فقاعة صغيرة اختيارية تظهر بجوار زر الدردشة لدعوة الأشخاص. قم بتفعيلها لتعيين رسالتها، ونص زر القبول/الرفض، وعدد الثواني التي يجب انتظارها قبل ظهورها. تختفي الفقاعة تلقائياً بعد 20 ثانية إذا لم ينقر عليها أحد (هذا الرقم ثابت)، وبمجرد أن ينقر الزائر على **ليس الآن**، فإنها تظل مخفية لبقية زيارتهم. لا تفتح نافذة الدردشة نفسها من تلقاء نفسها أبداً: فهي تفتح عندما ينقر الزائر على زر الدردشة أو الفقاعة، وتظل مفتوحة حتى يقوم بإغلاقها.
- **سرعة استجابة الذكاء الاصطناعي:** شريط تمرير بين **أبطأ** (أكثر شبهاً بالبشر - يأخذ الذكاء الاصطناعي وقتاً قبل الرد) و **أقصى سرعة** (أكثر آلية - تأتي الردود بأسرع ما يمكن). يقع خيار "متوازن" في المنتصف.


#### اللغات

الأداة متعددة اللغات بطبيعتها — ولا يوجد شيء تحتاج إلى تفعيله.

- **يتم اختيار لغة الزائر تلقائياً.** أولاً، ينظر إلى اللغة التي تعلن عنها صفحتك في HTML الخاص بها (`<html lang="it">`)، ثم يعود إلى لغة متصفح الزائر. إذا لم تكن أي منهما لغة ندعمها، فسيتم عرض اللغة الإنجليزية.
- **أو اختر لغة بنفسك.** يتم تعيين حقل **لغة الأداة** في قسم السلوك على "تلقائي" افتراضياً، وهو ما يمثل الكشف المذكور أعلاه. اختر لغة من هناك وستظل تسميات الأداة نفسها (حقول الاسم الأول والبريد الإلكتروني والهاتف في نموذج الزائر ونصها النموذجي، وإشعار الخصوصية، والأزرار) بتلك اللغة بغض النظر عما تقوله الصفحة أو المتصفح. استخدم هذا عندما لا يعلن منشئ موقعك عن اللغة الصحيحة، أو عندما تريد لغة واحدة ثابتة لكل زائر.
- **اللغات المدعومة:** الإنجليزية، الهولندية، الألمانية، الفرنسية، الإسبانية، الإيطالية، البرتغالية، الرومانية، البولندية، العربية، الفنلندية، والفلبينية. هذه هي القائمة الخاصة بأزرار وتسميات الأداة.
- **تتم ترجمة رسائلك نيابة عنك.** في كل مرة تحفظ فيها، تتم ترجمة رسالة الترحيب وفقاعة الدعوة الاستباقية وأسئلة البدء إلى جميع اللغات الاثنتي عشرة المذكورة أعلاه. أنت تكتبها مرة واحدة فقط، بأي لغة تفضلها.
- **اكتب كل رسالة بلغة واحدة فقط.** إذا وضعت لغتين في نفس الحقل - سطر بالإنجليزية وسطر بالإيطالية، على سبيل المثال - فسيتم التعامل مع الأمر برمته كرسالة واحدة وتتم ترجمتها كما هي، لذا سينتهي الأمر بالزائر الإيطالي برؤية نفس الجملة مرتين. اكتبها مرة واحدة، بأي لغة تفضلها.
- **يرد الذكاء الاصطناعي بلغة الزائر.** بغض النظر عن اللغة التي يكتب بها الشخص، يجيب وكيلك بنفس اللغة، بغض النظر عن اللغة التي تظهر بها تسميات الأداة. إذا كنت تفضل أن يجيب دائماً بلغة ثابتة واحدة، فحدد ذلك في تعليمات وكيلك.

**نصيحة:** إذا كان موقع الويب الخاص بك لا يحدد سمة `lang` في وسم `<html>` الخاص به، فأضف واحدة. إنها أقوى إشارة لدينا لاختيار اللغة الصحيحة، خاصة للزوار الذين يتصفحون من الخارج.

#### جمع العملاء المحتملين والخصوصية

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

> **ترك زائر رقم هاتف وغادر موقعك — هل يمكنني المتابعة عبر واتساب؟** نعم. افتح محادثته واختر **المتابعة عبر واتساب** من قائمة النقاط الثلاث (يجب أن يكون واتساب ويب أو واتساب للأعمال متصلاً). تقوم <span data-t="appName">Your AI Connector</span> بإنشاء محادثة واتساب مرتبطة لنفس الشخص، وتنسخ اسمه وبريده الإلكتروني وتفاصيله، وينقل الذكاء الاصطناعي ما قاله على موقعك، حتى لا يضطر أحد إلى تكرار نفسه. تبقى محادثة الموقع في مكانها وتشير كلتا المحادثتين إلى بعضهما البعض تحت **المحادثات المرتبطة** في لوحة جهات الاتصال. راجع [واجهة المحادثة](../chats/chat-interface.md).

> **هل يمكن لوكيل الذكاء الاصطناعي عرض خيار الانتقال إلى واتساب بنفسه؟** نعم، ولا يحتاج إلى ميزة إضافية — سطر واحد في تعليمات الوكيل يكفي. أنشئ [رابطاً مختصراً](../settings/short-links.md) لرقم واتساب الخاص بك مع رسالة تعبئة مسبقة مثل "مرحباً، كنت أدردش على موقعكم وأرغب في المتابعة هنا"، ثم أخبر الوكيل متى يرسله، على سبيل المثال: "إذا كان الزائر بحاجة للمغادرة، أو يرغب في المتابعة لاحقاً، أو طلب واتساب، اعرض عليه المتابعة هناك وأرسل هذا الرابط: (رابطك المختصر)". الروابط في الأداة قابلة للنقر، لذا يصل الزائر إلى واتساب مع تحديد رقمك وكتابة الرسالة مسبقاً، وتفتح رسالته الأولى محادثة واتساب في صندوق الوارد الخاص بك. إذا ترك الزائر رقم الهاتف الذي يراسل منه (مع رمز الدولة) في نموذج الأداة، تقوم <span data-t="appName">Your AI Connector</span> بربط المحادثتين تلقائياً ويعرف الذكاء الاصطناعي على واتساب محادثة الموقع بالفعل، تماماً كما هو الحال مع **المتابعة عبر واتساب**. إذا لم يتم جمع رقم هاتف، فلن يتم ربط المحادثتين، لذا اجعل رسالة التعبئة المسبقة محددة بما يكفي ليعرف وكيل واتساب من أين أتى الشخص.
- **طلب الموافقة على سياسة الخصوصية:** يمكنك اختيارياً مطالبة الزوار بالموافقة على سياسة الخصوصية الخاصة بك قبل الدردشة، وتعيين الرابط الذي تشير إليه.

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

#### القنوات والتضمين

- **زر المرفقات:** يتيح للزوار إرسال الصور والملفات في الدردشة.
- **منتقي الرموز التعبيرية:** يضيف منتقي رموز تعبيرية بجوار مربع الرسالة.
- **روابط القنوات:** يمكنك اختيارياً تضمين روابط WhatsApp أو Instagram أو Messenger حتى يتمكن الزوار من مواصلة المحادثة على المنصة التي يفضلونها. لا يظهر هذا إلا بعد ربط رقم WhatsApp أو حساب Instagram أو Messenger.
- **أزرار الإجراءات:** صف من الاختصارات في الجزء العلوي من الدردشة ينقل الزائر إلى مكان ما بدلاً من الدخول في محادثة - انظر [أزرار الإجراءات](#action-buttons) أدناه.
- **القائمة البيضاء للنطاقات:** قيد المواقع الإلكترونية المسموح لها بتضمين الأداة الخاصة بك. أضف النطاقات التي قمت بتثبيت الأداة عليها (على سبيل المثال `example.com` أو `*.example.com`)؛ اتركها فارغة للسماح بأي نطاق.
- **توجيه هذه الدردشات إلى:** اختر الحملة أو الوكيل الذي يجب أن يتعامل مع الدردشات القادمة من الكود الذي توشك على نسخه. اتركها على **الإعداد الافتراضي للحساب** لاستخدام توجيه أداة الدردشة العادي الخاص بك. انظر [إرسال صفحات مختلفة إلى حملات مختلفة](#send-different-pages-to-different-campaigns) أدناه.
- **مقتطف التضمين:** اختر **فقاعة عائمة** أو **مضمنة** وانسخ كود التثبيت (انظر أدناه).
- **رابط تجريبي للعميل:** الصق أي عنوان موقع إلكتروني للحصول على رابط قابل للمشاركة يفتح ذلك الموقع مع تشغيل الأداة الخاصة بك فوقه - لا يوجد شيء ليتم تثبيته من جانبهم. انظر [عرض الأداة على موقع إلكتروني لشخص آخر](#show-the-widget-on-someone-elses-website) أدناه.

في أسفل اللوحة، يؤدي إجراء **حذف أداة الدردشة** إلى إزالة الأداة من موقعك على الفور — لا يمكن التراجع عن هذا، ولن يرى الزوار فقاعة الدردشة بعد الآن.

#### أزرار الإجراءات

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

أضف ما يصل إلى ستة أزرار. لكل منها **تسمية** (الكلمات الموجودة على الزر) و**وجهة**، وتعتمد الوجهة على الإجراء الذي تختاره:

| الإجراء | ما يحصل عليه الزائر | ما تقوم بملئه |
| --- | --- | --- |
| **اتصال** | يفتح تطبيق الاتصال الهاتفي لديهم مع جاهزية رقمك | رقم هاتفك، على سبيل المثال `+1 555 123 4567` |
| **رسالة نصية** | يفتح تطبيق المراسلة لديهم رسالة نصية جديدة إليك | رقم هاتفك |
| **WhatsApp** | يفتح WhatsApp محادثة معك | رقم WhatsApp الخاص بك، أو رابط `wa.me` تمتلكه بالفعل |
| **بريد إلكتروني** | يفتح تطبيق البريد لديهم رسالة بريد إلكتروني جديدة إليك | عنوان بريدك الإلكتروني |
| **الاتجاهات** | تفتح خرائط Google مع موقعك | عنوانك، أو رابط خرائط تمتلكه بالفعل |
| **رابط** | تفتح الصفحة في علامة تبويب جديدة | أي عنوان ويب كامل يبدأ بـ `https://` |

**هذه الأزرار لا تستخدم الرصيد.** النقر على أحدها لا يرسل رسالة ولا يبدأ محادثة - بل ينقل الزائر فقط إلى المكان الذي طلب الذهاب إليه. فقط المحادثة الفعلية مع وكيل الذكاء الاصطناعي الخاص بك هي التي تستهلك الرصيد، تماماً كما كان من قبل.

بعض الأمور التي تجدر معرفتها:

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



#### ما لا يمكنك تخصيصه

لوحة الإدارة (Manage panel) هي مجموعة الخيارات الكاملة. وبشكل خاص:

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

إذا كان أحد هذه الأمور يمثل عائقاً بالنسبة لك، فإن [التضمين المضمن](#embed-inline-on-a-page-advanced) يمنحك أكبر قدر من التحكم: حيث توضع الأداة في حاوية على صفحتك الخاصة، والتي يمكنك تحديد حجمها وموضعها بنفسك.


### تعليمات التثبيت

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

1. افتح ملف HTML الخاص بموقعك الإلكتروني في محرر نصوص.
2. ابحث عن وسم الإغلاق `</body>` — عادة ما يكون في نهاية الملف تماماً.
3. الصق سطر الكود هذا قبل وسم `</body>` مباشرة، لضمان تحميل بقية صفحتك أولاً:

{% code overflow="wrap" %}
```html
<script src="https://api.youraiconnector.com/v1/chat-widget/CONFIG_ID"></script>
```
{% endcode %}

4. استبدل `CONFIG_ID` بمعرف الإعدادات الفريد الخاص بك، والذي يظهر في قسم **القنوات والتضمين** (Channels & Embed) في لوحة الإدارة. هذا المعرف خاص بحسابك ويربط الأداة بنظام المراسلة الخاص بك.

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

{% code overflow="wrap" %}
```html
<script>
window.addEventListener('load', function () {
  var s = document.createElement('script');
  s.src = 'https://api.youraiconnector.com/v1/chat-widget/CONFIG_ID';
  s.async = true;
  document.body.appendChild(s);
});
</script>
```
{% endcode %}

وإذا كنت ترغب في تأخير فقاعة الدعوة الصغيرة بدلاً من تحميل الأداة نفسها، فيمكنك استخدام خيار تأخير **فقاعة النافذة المنبثقة الاستباقية (Proactive popup bubble)** في قسم السلوك (Behavior) أعلاه — دون الحاجة إلى أي كود.

إليك مثال كامل لما يجب أن يبدو عليه ملف HTML الخاص بك بعد تنفيذ أداة الدردشة:

{% code overflow="wrap" %}
```html
<!DOCTYPE html>
<html>
<head>
    <title>My Website</title>
</head>
<body>
    <!-- Your existing website content would be here -->

    <!-- Chat Widget Integration -->
    <script src="https://api.youraiconnector.com/v1/chat-widget/CONFIG_ID"></script>
</body>
</html>
```
{% endcode %}

### التضمين المضمن في الصفحة (متقدم)

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

يبدو الأمر كالتالي:

{% code overflow="wrap" %}
```html
<div data-chat-widget="CONFIG_ID" style="width:100%;height:600px;"></div>
<script src="https://api.youraiconnector.com/v1/chat-widget/embed.js" async></script>
```
{% endcode %}

يُعد `<div>` هو نقطة التثبيت — حيث يتم عرض لوحة الدردشة بداخلها وتملأ أبعادها. يمكنك تنسيق div بالطريقة التي تفضلها (امنحها ارتفاعاً ثابتاً، أو ضعها داخل حاوية مرنة flex، أو ضعها في خلية شبكة grid، وما إلى ذلك) وستتبعها لوحة الدردشة.

تحتاج فقط إلى وسم `<script>` **واحد** في الصفحة، حتى لو كنت تقوم بتضمين عناصر واجهة مستخدم (widgets) متعددة للدردشة. يقوم البرنامج النصي بمسح الصفحة بحثاً عن كل `<div data-chat-widget="…">` وتثبيت لوحة دردشة في كل منها.

متى تختار التضمين المضمن (inline) مقابل العائم (floating):

- **الفقاعة العائمة** مناسبة لزر "هل تحتاج إلى مساعدة؟" المتاح دائماً في جميع أنحاء الموقع.
- **التضمين المضمن** مناسب عندما يجب أن تكون الدردشة في مكان محدد — صفحة دعم، أو شريط جانبي لقاعدة المعرفة، أو علامة تبويب مساعدة داخل التطبيق — لتبدو كجزء أصيل من تلك الصفحة.

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

### عرض الأداة على موقع إلكتروني خاص بشخص آخر

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

1. افتح لوحة الإدارة وانتقل إلى **القنوات والتضمين**.
2. في **رابط العرض التوضيحي للعميل**، اكتب عنوان الموقع الإلكتروني (على سبيل المثال `www.theircompany.com`).
3. انقر فوق **نسخ** لنسخ الرابط، أو **فتح** لرؤيته بنفسك أولاً.
4. أرسل الرابط إلى أي شخص تريد عرضه عليه.

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

بعض الأمور التي تجدر معرفتها:

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

{% hint style="info" %}
يستخدم رابط العرض التوضيحي دائماً التوجيه الافتراضي لحسابك، بغض النظر عن الإعداد المختار في **توجيه هذه الدردشات إلى**. إذا كنت تريد أن يتم التعامل مع دردشات العرض التوضيحي بواسطة وكيل معين، فقم بتعيين ذلك الوكيل كافتراضي لأداة الدردشة الخاصة بك أولاً.
{% endhint %}

### إرسال صفحات مختلفة إلى حملات مختلفة

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

هناك طريقتان للحصول على الكود:

- **من الحملة أو الوكيل.** في صفحة **الحملات** (Campaigns)، افتح القائمة **⋮** الخاصة بحملة ما واختر **إضافة إلى الموقع الإلكتروني** (Add to website). في صفحة **الوكلاء** (Agents)، انقر على الزر **&lt;/&gt;** الموجود في الصف، أو افتح الوكيل وانتقل إلى علامة التبويب **نقاط الدخول** (Entry points) الخاصة به. في كلتا الحالتين، ستحصل على مقتطف جاهز للصق وموجه بالفعل إلى تلك الحملة أو الوكيل.

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

  يظهر خيار **Add to website** فقط في الحملات المباشرة والمُعدة للتعامل مع الدردشات الواردة. لا يمكن لحملة مسودة استقبال الزوار بعد، لذا يظل الخيار مخفياً حتى تقوم بنشرها. وفي صفحة الوكلاء، يظهر هذا الخيار للوكلاء النشطين فقط. فالوكيل المتوقف مؤقتاً قد يستقبل الدردشة لكنه لن يرد عليها، لذا يظل الخيار مخفياً حتى تقوم بتفعيله مرة أخرى. لا توجد قناة محددة يجب إعدادها للوكيل، حيث يمكن للوكيل الرد على الدردشة من أي قناة.
- **من إعدادات الأداة.** في **Settings → Channels → Manage** ضمن أداة الدردشة الخاصة بك، قم بتعيين **Route these chats to** وانسخ المقتطف الموجود بالأسفل. سيؤدي تغيير القائمة المنسدلة إلى إعادة كتابة المقتطف.

يحمل المقتطف العائم الوجهة في العنوان:

{% code overflow="wrap" %}
```html
<script src="https://api.youraiconnector.com/v1/chat-widget/CONFIG_ID?campaign=CAMPAIGN_ID"></script>
```
{% endcode %}

يحمل المقتطف المضمن الوجهة في `<div>` بدلاً من ذلك، بحيث يمكن لصفحة واحدة استيعاب عدة محادثات تذهب إلى أماكن مختلفة:

{% code overflow="wrap" %}
```html
<div data-chat-widget="CONFIG_ID" data-campaign="CAMPAIGN_ID" style="width:100%;height:600px;"></div>
<script src="https://api.youraiconnector.com/v1/chat-widget/embed.js" async></script>
```
{% endcode %}

بالنسبة للوكيل، تتغير الصياغة إلى `?agent=AGENT_ID` أو `data-agent="AGENT_ID"`.

بعض الأمور التي تجدر معرفتها:

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

### أخبر الأداة بهوية الزائر (متقدم)

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

أضف كتلة إعدادات صغيرة **قبل** نص الأداة البرمجي:

{% code overflow="wrap" %}
```html
<script>
  window.chatWidgetSettings = {
    visitor: {
      id: "12345",
      name: "Maria",
      email: "maria@example.com",
      phone: "+391234567890"
    },
    data: {
      plan: "Professional",
      customer_since: "2024",
      last_order: "A-2291"
    }
  };
</script>
<script src="https://api.youraiconnector.com/v1/chat-widget/CONFIG_ID"></script>
```
{% endcode %}

يجب أن تقوم صفحتك بملء هذه القيم من جهة الخادم، بناءً على الشخص الذي قام بتسجيل الدخول.

يحدث أمران:

- **يتم تخطي نموذج "قبل أن نبدأ...".** مع توفير الاسم والبريد الإلكتروني، ينتقل الزائر مباشرة إلى المحادثة، ويتم حفظ هذه التفاصيل في جهة الاتصال الخاصة به تماماً كما لو كان قد كتبها بنفسه.
- **يتم تمرير كل شيء تحت `data` إلى ذكائك الاصطناعي.** أي شيء تضعه هناك — الخطة، رقم الطلب، تاريخ التجديد، رصيد الائتمان، عدد المقاعد المتاحة لديهم — يصبح جزءاً مما يعرفه الذكاء الاصطناعي عن ذلك الشخص، بحيث يمكنه الإجابة على سؤال "متى يتم تجديد خطتي؟" دون أن يطلب منهم شرح هويتهم أولاً. استخدم أسماء الحقول التي تراها مناسبة؛ حيث ستظهر في جهة الاتصال تحت "الحقول المخصصة" (Custom Fields). يمكنك إرسال ما يصل إلى 20 قيمة، يتم تحديثها مع كل رسالة، لذا إذا تغيرت الخطة في منتصف المحادثة، سيرى الذكاء الاصطناعي القيمة الجديدة.

بالنسبة للتضمينات المضمنة (inline embeds)، يمكنك وضع نفس المعلومات على `<div>` بدلاً من ذلك، وهو أمر مفيد عندما تحتوي صفحة واحدة على عدة محادثات:

{% code overflow="wrap" %}
```html
<div data-chat-widget="CONFIG_ID"
     data-visitor-name="Maria"
     data-visitor-email="maria@example.com"
     data-visitor-data='{"plan":"Professional"}'
     style="width:100%;height:600px;"></div>
<script src="https://api.youraiconnector.com/v1/chat-widget/embed.js" async></script>
```
{% endcode %}

إذا كان موقعك لا يعرف هوية الزائر إلا بعد تحميل الصفحة — على سبيل المثال، في تطبيق الصفحة الواحدة (single-page app) حيث يتم تسجيل الدخول دون إعادة تحميل الصفحة — فاستدعِ هذا الأمر كلما توفرت لديك التفاصيل، وستقوم الأداة بتحديث نفسها:

{% code overflow="wrap" %}
```html
<script>
  window.chatWidget.setVisitor({
    visitor: { id: "12345", name: "Maria", email: "maria@example.com" },
    data: { plan: "Professional" }
  });
</script>
```
{% endcode %}

بعض الأمور التي تجدر معرفتها:

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

### تغيير إعدادات الأداة من خلال الكود الخاص بك (API)

يمكن تغيير كل شيء في لوحة **الإدارة** (Manage) الخاصة بالأداة عبر [REST API](../api/reference.md)، وهو أمر مفيد إذا كنت تدير العديد من المواقع الإلكترونية أو ترغب في إيقاف تشغيل زر المرفقات تلقائيًا لأحد العملاء. أرسل `PATCH` إلى `https://api.youraiconnector.com/v1/chat-widget-configs/CONFIG_ID` مع مفتاح API الخاص بك والحقول التي تريد تغييرها فقط - على سبيل المثال، `{"show_upload_button": false}` يخفي زر المرفقات، و`{"show_emoji_button": false}` يخفي منتقي الرموز التعبيرية، و`{"launcher_icon": "chat-dots"}` يستبدل أيقونة المشغل. `CONFIG_ID` هو نفس المعرف الموجود في نص التضمين الخاص بك. القائمة الكاملة للحقول المقبولة (الاسم، رسالة الترحيب، الألوان، أيقونة المشغل، النطاقات المسموح بها، نموذج معلومات الزائر، إشعار الخصوصية، السمة، الزاوية، ونمط الخط) موجودة في [مرجع API](../api/reference.md) تحت قسم **أداة الدردشة** (Chat Widget). تلتقط المواقع الإلكترونية التغيير في المرة التالية التي يتم فيها تحميل الصفحة.

### ما الذي يمكن توقعه بعد التثبيت

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


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


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

### اختبار التنفيذ الخاص بك

بعد إضافة الأداة إلى موقعك، اختبر عملها:

1. افتح موقعك الإلكتروني في متصفح.
2. انقر على زر الدردشة لفتح الأداة.
3. أرسل رسالة تجريبية وتأكد من تلقيك رداً.
4. كرر العملية على جهاز أو متصفح مختلف للتأكد من أنها تعمل في كل مكان.


إذا لم تظهر أداة الدردشة على موقعك، تحقق مما يلي:

1. تأكد من استبدال `CONFIG_ID` بمعرف الإعدادات الفعلي الخاص بك.
2. تأكد من وضع وسم البرنامج النصي قبل وسم الإغلاق `</body>`.
3. تحقق من الكود بحثاً عن أي أخطاء مطبعية.

### خلف جدار حماية مؤسسي

إذا كانت الأداة تُحمل للجمهور ولكن ليس للموظفين على شبكة المكتب، فمن المؤكد تقريباً أن الشبكة تحظر النطاق الذي تُحمل منه. اطلب من فريق تكنولوجيا المعلومات لديك السماح بالاتصال عبر بروتوكول HTTPS العادي على المنفذ 443:

- **النطاق الموجود في مقتطف التضمين الخاص بك** — العنوان الموجود في سطر `<script src="...">` الذي نسخته من لوحة الإدارة.
- **`api.youraiconnector.com`** — ترسل الأداة رسائلها إلى هنا أيضاً.

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