برمجة شات بوت للموقع: ربط الواجهة بالمساعد خطوة بخطوة

ما الذي تبرمجه عند إضافة شات بوت للموقع؟

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

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

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

جهّز المشروع واعتمد نطاق الموقع

مستندات التسجيل الحالية: قدّم بطاقة الهوية القومية لبلد تحمل جنسيته، وليس هوية بلد الإقامة. يُقبل جواز السفر المصري فقط للمصري المقيم خارج مصر إذا لم تكن بطاقته المصرية متاحة له. وتُقبل شهادة الميلاد المصرية فقط للمصري المقيم في مصر دون 15 سنة الذي لا يحمل بطاقة رقم قومي ولا جواز سفر. راجع متطلبات التسجيل الرسمية قبل التقديم.

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

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

الربط لا يعتمد على مفتاح API سري. وإذا ظهر معرّف المشروع pid في الإعداد، فهو معرّف عام وليس كلمة مرور. نفّذ إعداد المشروع وتحميل حزمة SDK الرسمية كما يوضح دليل التكامل؛ المثال التالي يفترض اكتمال هذه الخطوة مسبقًا.

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

استخدم إجراءً يبدأه المستخدم لفتح تسجيل الدخول، ثم تحقّق من الحالة قبل إرسال السؤال. تستقبل الدالة GammalTech.ai.ask رسالة المستخدم وخيارات التعليمات، وتعيد الإجابة كنص. لا تتعامل مع الناتج على أنه كائن يحتاج إلى حقل غير موثق.

الكود المعروض تعليمي، ويُنفَّذ بعد تحميل SDK وإتمام إعداد المشروع. لا توجد محادثة عاملة داخل هذه المقالة. عدّل المعلومات المعتمدة لتناسب موقعك قبل نقل المثال إلى مشروعك.

<!-- مثال تعليمي: حمّل SDK وأكمل إعداد المشروع وفق الدليل أولًا. -->
<button id="login" type="button">تسجيل الدخول</button>
<form id="chat-form">
  <label for="question">سؤالك عن الموقع</label>
  <input id="question" maxlength="1000" required>
  <button id="send" type="submit">إرسال</button>
</form>
<p id="reply" role="status" aria-live="polite"></p>

<script>
const login = document.querySelector('#login');
const form = document.querySelector('#chat-form');
const question = document.querySelector('#question');
const send = document.querySelector('#send');
const reply = document.querySelector('#reply');
let pending = false;

login.addEventListener('click', async () => {
  login.disabled = true;
  try {
    await GammalTech.login();
    reply.textContent = 'اكتمل تسجيل الدخول.';
  } catch {
    reply.textContent = 'لم يكتمل تسجيل الدخول. يمكنك المحاولة مجددًا.';
  } finally {
    login.disabled = false;
  }
});

form.addEventListener('submit', async (event) => {
  event.preventDefault();
  if (pending) return;
  if (!GammalTech.isLoggedIn()) {
    reply.textContent = 'سجّل الدخول أولًا باستخدام الزر.';
    return;
  }
  const message = question.value.trim();
  if (!message) return;
  pending = true;
  send.disabled = true;
  reply.textContent = 'جارٍ إعداد الإجابة…';
  try {
    const answer = await GammalTech.ai.ask(message, {
      system_prompt: 'أجب بالعربية عن المعلومات المرفقة فقط. '
        + 'المعلومة المعتمدة: هذه صفحة تعريفية بخدمات تصميم المواقع. '
        + 'لا توجد أسعار أو مواعيد تنفيذ مرفقة. '
        + 'صرّح بنقص المعلومات ولا تطلب بيانات التواصل أو الهوية.',
      temperature: 0.2,
      max_tokens: 500
    });
    reply.textContent = answer;
  } catch {
    reply.textContent = 'تعذّر إكمال الطلب. حاول مرة أخرى لاحقًا.';
  } finally {
    pending = false;
    send.disabled = false;
  }
});
</script>

يمنع المتغير pending إرسال طلب ثانٍ من النموذج نفسه أثناء الانتظار، ويعيد زر الإرسال إلى حالته في finally سواء نجح الطلب أو فشل. هذا تحسين للواجهة، وليس نظامًا كاملًا لمنع إساءة الاستخدام أو للتحكم في الميزانية.

اعرض الرد كنص واحمِ المعلومات التي ترسلها

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

ضع في التعليمات معلومات عامة يحتاجها المساعد فعلًا. ما يوجد في الواجهة يمكن أن يكون ظاهرًا للمستخدم، لذلك لا تُدرج كلمات مرور أو رموز وصول أو تفاصيل داخلية سرية داخل system_prompt. والتعليمات وحدها ليست حاجز صلاحيات؛ ينبغي فرض أي صلاحيات حقيقية داخل الأنظمة التي تدير البيانات والإجراءات.

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

أضف سياق المحادثة عند الحاجة فقط

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

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

راجع كذلك طول تعليماتك وحدود الخيارات في الدليل. حد system_prompt هو 4000 محرف، وتظل جودة المعلومات وترتيبها أهم من حشد نص طويل. اختبر عبارات محلية مثل «وش تشمل الخدمة؟» مع صياغة فصيحة للسؤال نفسه للتأكد من فهم المقصود.

اختبر التسجيل والأخطاء واستهلاك الحصة

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

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

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

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

أسئلة شائعة عن برمجة شات بوت للموقع

هل يلزم مفتاح API في JavaScript؟

يعتمد هذا الربط على نطاقات المواقع المعتمدة، ولا يحتاج إلى مفاتيح API. التزم بإعداد المشروع الوارد في الدليل، ولا تضف معاملات أو طرق تهيئة غير موثقة إلى المثال.

هل الكود يتابع الطلبات أو يعدّلها؟

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

هل يمكن استخدامه للزائر دون تسجيل الدخول؟

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