راهنمای ویجت چت وب‌سایت

۱. نصب

کد زیر را درست قبل از تگ بستنِ </body> در همه صفحات سایت خود قرار دهید. ویجت چت به صورت خودکار نمایش داده می‌شود.

<script src="https://avalagent.com/widget.js" data-business-id="YOUR_BUSINESS_ID" defer></script>

مقدار data-business-id شناسهٔ کسب‌وکار شماست. آن را از داشبورد، بخش «کانال‌ها ← چت وب‌سایت» بردارید (همان‌جا کد آماده هم نمایش داده می‌شود).

۲. شناسایی بازدیدکنندگان

اگر کاربر در سایت شما وارد شده است، می‌توانید اطلاعاتش را به ویجت بدهید تا در اینباکس پیام‌ها با نام و ایمیل یا شماره موبایل دیده شود. این کار با تعریف window.smflowSettings انجام می‌شود.

• ایمیل یا موبایل: حداقل یکی لازم است. برای کسب‌وکارهای ایرانی که کاربران را با شماره موبایل می‌شناسند، فقط phone کافی است.
• بدون hash → کاربر با برچسب «تأییدنشده» ثبت می‌شود (هر کسی می‌تواند هر ایمیل/موبایلی ادعا کند، پس به این برچسب اعتماد نکنید).
• با افزودن hash → کاربر «تأییدشده» می‌شود (هویتش از نظر سرور معتبر است).

ترتیب مهم است: اسکریپت smflowSettings باید قبل از اسکریپت ویجت قرار بگیرد.

<!-- این اسکریپت باید قبل از اسکریپت ویجت قرار بگیرد -->
<script>
  window.smflowSettings = {
    // ایمیل یا شماره موبایل — حداقل یکی لازم است. اگر کاربران شما با موبایل
    // شناخته می‌شوند (بازار ایران)، فقط phone را بدهید.
    email: 'CURRENT_USER_EMAIL', // اختیاری
    phone: 'CURRENT_USER_PHONE', // اختیاری
    name:  'CURRENT_USER_NAME',
    // hash اختیاری است؛ با افزودن آن کاربر «تأییدشده» می‌شود.
    hash:  'COMPUTED_ON_YOUR_SERVER',
  }
</script>
<script src="https://avalagent.com/widget.js" data-business-id="YOUR_BUSINESS_ID" defer></script>

مقدار hash برابر است با HMAC-SHA256(identifier, widget_secret) به صورت hex با حروف کوچک، که در آن identifier برابر است با ایمیل در صورت وجود، وگرنه شماره موبایل. اگر هم ایمیل و هم موبایل می‌فرستید، حتماً hash را روی ایمیل بسازید — در غیر این صورت تأیید انجام نمی‌شود. این مقدار باید روی سرور شما ساخته شود — راز ویجت را هرگز در مرورگر قرار ندهید. راز ویجت در داشبورد، بخش تنظیمات کانال چت وب‌سایت با عنوان «راز ویجت» در دسترس است.

// Node.js — hash را روی سرور خود بسازید، هرگز راز ویجت را در مرورگر قرار ندهید.
const crypto = require('crypto')

const WIDGET_SECRET = process.env.WIDGET_SECRET // از داشبورد اول ایجنت

// قانون مهم: اگر ایمیل دارید، hash را روی «ایمیل» بسازید؛ فقط در نبودِ ایمیل،
// روی «شماره موبایل». سرور هم دقیقاً با همین ترتیب بررسی می‌کند.
const email = '[email protected]' // یا ''
const phone = '989120000000'     // یا ''
const identifier = email || phone

const hash = crypto
  .createHmac('sha256', WIDGET_SECRET)
  .update(identifier) // همان رشته‌ای که در smflowSettings می‌فرستید
  .digest('hex') // خروجی: hex با حروف کوچک

۳. تم

سه حالت دارد: تیره (dark)، روشن (light) و خودکار (auto). حالت خودکار به صورت خودکار از تنظیم رنگ سیستم‌عاملِ بازدیدکننده پیروی می‌کند. این گزینه از داشبورد تنظیم می‌شود (نیازی به کد نیست).

۴. موقعیت دکمه

دکمهٔ شناور می‌تواند در گوشهٔ راست یا چپ قرار بگیرد. در صفحات راست‌به‌چپ به‌صورت خودکار آینه می‌شود. روی موبایل همیشه در گوشهٔ پایین است. این گزینه از داشبورد تنظیم می‌شود.

۵. رنگ برند، پیام خوش‌آمد و سوالات سریع

• رنگ برند: رنگ اصلی دکمه و حباب چت — از داشبورد.
• پیام خوش‌آمد: پیامی که هنگام باز شدن چت نمایش داده می‌شود — از داشبورد.
• سوالات سریع: دکمه‌های پیشنهادی برای شروع گفتگو — از داشبورد.

۶. دکمهٔ دلخواه خودتان

دکمهٔ گرد شناوری که ما اضافه می‌کنیم فقط حالت پیش‌فرض است. شما می‌توانید آن را پنهان کنید و چت را از هر دکمه یا لینکی در سایت خودتان باز کنید — هر جا و با هر طراحی‌ای که به سایتتان می‌خورد.

ساده‌ترین راه، بدون یک خط جاوااسکریپت: فقط ویژگی data-avalagent-open را به هر عنصری اضافه کنید.

<!-- هر عنصری: دکمه، لینک، آیکون، آیتم منو -->
<button data-avalagent-open>گفتگو با ما</button>

<!-- اگر دکمهٔ شناور خودمان را نمی‌خواهید، آن را خاموش کنید -->
<script src="https://avalagent.com/widget.js"
        data-business-id="YOUR_BUSINESS_ID"
        data-hide-launcher="true" defer></script>

این ویژگی روی عناصری که بعداً هم ساخته می‌شوند (React، Vue، هر فریم‌ورکی) کار می‌کند.

اگر ترجیح می‌دهید با کد صدا بزنید، این متدها روی window.AvalAgent در دسترس‌اند:

// اگر اسکریپت ویجت هنوز بارگذاری نشده باشد، window.AvalAgent
// وجود ندارد. به‌جای چک کردن مداوم، به این رویداد گوش بدهید:
window.addEventListener('avalagent:ready', function () {
  AvalAgent.open()          // باز کردن چت
  AvalAgent.close()         // بستن چت
  AvalAgent.toggle()        // باز/بسته
  AvalAgent.isOpen()        // true / false
  AvalAgent.hideLauncher()  // پنهان کردن دکمهٔ گرد ما
  AvalAgent.showLauncher()  // برگرداندن آن
})

چون اسکریپت ویجت با defer بارگذاری می‌شود، ممکن است کد شما زودتر از آن اجرا شود. برای همین رویداد avalagent:ready وجود دارد؛ به‌جای این‌که مدام چک کنید آماده شده یا نه، به آن گوش بدهید.

پنهان کردن دکمهٔ ما: اگر همیشه می‌خواهید پنهان باشد، کلید «نمایش دکمهٔ شناور» را در داشبورد خاموش کنید. اگر فقط در بعضی صفحه‌ها یا در بعضی حالت‌ها می‌خواهید پنهان شود، از data-hide-launcher="true" روی تگ اسکریپت یا از AvalAgent.hideLauncher() استفاده کنید.

۷. دامنه‌های مجاز

می‌توانید مشخص کنید ویجت فقط روی چه سایت‌هایی کار کند. هر دامنه را در یک خط بنویسید، بدون http://. زیر‌دامنه‌ها به‌صورت خودکار مجاز هستند. اگر خالی بماند، ویجت همه‌جا کار می‌کند. این محدودیت روی سرور اعمال می‌شود؛ یعنی درخواست از دامنه‌های دیگر رد می‌شود. این گزینه از داشبورد تنظیم می‌شود.

example.com
shop.example.com