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

۱. نصب

کد زیر را درست قبل از تگ بستنِ </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). حالت خودکار به صورت خودکار از تنظیم رنگ سیستم‌عاملِ بازدیدکننده پیروی می‌کند. این گزینه از داشبورد تنظیم می‌شود (نیازی به کد نیست).

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

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

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

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

۶. مخفی کردن دکمه شناور

با خاموش کردن کلید «نمایش دکمهٔ شناور» در داشبورد، دکمهٔ گرد ویجت پنهان می‌شود.

توجه: در حال حاضر یک API عمومی برای باز کردن چت با کد (مثلاً از روی دکمهٔ دلخواه خودتان) وجود ندارد. اگر به تریگر سفارشی نیاز دارید، با پشتیبانی اول ایجنت در میان بگذارید.

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

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

example.com
shop.example.com