الويدجت بسطر واحد

زر محادثة يظهر في زاوية موقعك، يحادث زوارك كتابةً وصوتاً بعقل وكيلك وصوته. لا يحتاج خادماً، ولا يصل أي مفتاح إلى المتصفح.

التفعيل في ثلاث خطوات

انشر الوكيل من صفحته في Studio. يعمل الويدجت على المراجعة المنشورة فقط.
فعّل «السماح بالتضمين بسطر واحد» من صفحة الوكيل، قسم «شكل الرد»، ثم احفظ وانشر المراجعة.
سجّل نطاق موقعك في Studio ← الدمج ← «النطاقات المسموح لها»، بالعنوان الكامل مثل https://www.example.com. لا يعمل الويدجت على أي نطاق غيره.

بعدها تجد سطر التضمين جاهزاً بمعرّف وكيلك في Studio ← الدمج. الصقه قبل </body>:

HTML

<script
  src="https://app.surad-ai.com/widget/v1.js"
  data-embed="emb_…"
  data-title="مساعد المتجر"
  data-greeting="أهلاً! كيف أقدر أساعدك؟"
  data-color="#0f766e"
  async></script>

الخيارات

الحقل	النوع	الوصف
`data-embed`*	string	معرّف التضمين العام لوكيلك (يبدأ بـ emb_). موقَّع، فلا يمكن تخمينه أو تزويره، ولا يمنح شيئاً وحده.
`data-title`	string	عنوان نافذة المحادثة. الافتراضي: «المساعد».
`data-greeting`	string	أول رسالة يراها الزائر.
`data-color`	#hex	لون الزر والرسائل، ليتسق مع موقعك.
`data-position`	left \| right	زاوية الزر. الافتراضي: left (مناسب للمواقع العربية).
`data-voice`	off	يخفي زر الميكروفون. الافتراضي: ظاهر.
`data-token-url`	path	بديل data-embed: مسار في خادمك يعيد رمز الجلسة (انظر أدناه).

المحادثة الصوتية

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

يتبع الصوت إعداد «شكل الرد» للوكيل: إن كان «نص فقط» يصل الرد مكتوباً دون صوت. وللمحادثة الصوتية اختر طول الرد «قصير»: الرد أسرع وأسهل على السمع.

يطلب المتصفح إذن الميكروفون في أول مرة. يعمل الصوت على المواقع الآمنة (HTTPS) فقط، كما تشترط المتصفحات.

الأمان وحدود الاستخدام

يُصدر صُرَد لكل زائر رمز جلسة صالحاً 10 دقائق ومربوطاً بنطاق موقعك، ويجدده الويدجت تلقائياً.
لا يعمل التضمين إلا لوكيل فعّلته بنفسك، وعلى نطاق سجّلته. أوقفه متى شئت بإلغاء التفعيل ثم النشر.
لحماية رصيدك: 20 جلسة كحد أقصى لكل زائر كل 10 دقائق، و600 جلسة في الساعة لكل وكيل. عند تجاوزها يرى الزائر رسالة «حاول بعد لحظات».

إن أردت أن تقرر بنفسك من يحق له الحديث مع الوكيل (مثلاً: المستخدمون المسجلون فقط)، فاجعل خادمك يصدر رمز الجلسة، واستخدم data-token-url بدل data-embed. يرسل الويدجت POST إلى هذا المسار من نطاق موقعك نفسه (مع ملفات تعريف الارتباط)، وينتظر {"token": "…"}.

Node.js (Express)

// خادمك: يصدر رمز جلسة لزائر موقعك. المفتاح لا يغادر الخادم.
app.post('/surad/token', async (req, res) => {
  const response = await fetch(
    'https://app.surad-ai.com/api/v1/workspaces/' + process.env.SURAD_WORKSPACE_ID + '/widget/session-tokens',
    {
      method: 'POST',
      headers: {
        Authorization: 'Bearer ' + process.env.SURAD_API_KEY,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        agent_id: process.env.SURAD_AGENT_ID,
        origin: 'https://www.example.com', // نطاق موقعك كما سجّلته
        ttl_seconds: 900,
      }),
    },
  )
  if (!response.ok) return res.status(502).end()
  const { token } = await response.json()
  res.json({ token })
})

HTML

<script src="https://app.surad-ai.com/widget/v1.js" data-token-url="/surad/token" async></script>

إن لم يظهر الزر أو لم يعمل

لا يظهر الزر

افتح أدوات المطور في المتصفح (Console). إن رأيت [SURAD] add data-embed… فالسطر ينقصه المعرّف. وتأكد أن الصفحة تحمّل https://app.surad-ai.com/widget/v1.js بنجاح.

«هذا الموقع غير مصرّح له باستخدام المساعد»

نطاق الصفحة لا يطابق نطاقاً مسجلاً حرفياً. https://example.com وhttps://www.example.com نطاقان مختلفان، فسجّل ما يظهر في شريط العنوان بالضبط.

«لا يوجد وكيل منشور لهذا الارتباط»

الوكيل غير منشور، أو لم يُفعَّل له التضمين في المراجعة المنشورة. فعّله ثم انشر.

الميكروفون لا يعمل

رفض الزائر الإذن، أو الصفحة ليست HTTPS. وتبقى الكتابة متاحة في الحالتين.