مستندات ویجت گفت‌وگو

راهنمای کامل نصب، انتخاب روش بارگذاری، ارسال اطلاعات لید و شخصی‌سازی ویجت ایلاچت با JavaScript.

ویجت ایلاچت پنجره گفت‌وگویی است که چت‌بات هوش مصنوعی و اپراتورهای شما را مستقیماً در وب‌سایت در دسترس بازدیدکننده قرار می‌دهد. برای نصب اولیه فقط کافی است کد اختصاصی ویجت را از پنل ایلاچت کپی و یک بار در صفحات سایت قرار دهید؛ برای شخصی‌سازی‌های پیشرفته نیز API سمت کاربر در اختیار شماست.

این صفحه نصب ویجت در سایت‌های غیروَردپرسی را توضیح می‌دهد. اگر از وردپرس استفاده می‌کنید، نصب از طریق افزونه رسمی ایلاچت ساده‌تر است و ویجت را بدون درج دستی کد اضافه می‌کند.

دریافت کد ویجت از پنل ایلاچت

وارد پنل ایلاچت شوید و چت‌بات موردنظر را انتخاب کنید.
وارد «تنظیمات» شوید.
بخش «استفاده و انتشار» را باز کنید.
گزینه «ویجت سایت» را انتخاب کنید.
یکی از سه نوع کد را متناسب با نیاز سایت انتخاب و کپی کنید.

کدی که از پنل کپی می‌کنید شامل توکن عمومی و اختصاصی همان ویجت است. نمونه‌های این مستندات عمداً توکن واقعی ندارند؛ بنابراین برای نصب نهایی، کد پنل خودتان را استفاده کنید و نمونه‌ها را بدون جایگزین‌کردن YOUR_WIDGET_TOKEN منتشر نکنید.

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

قراردادن کد در سایت

کد انتخابی را در قالب اصلی سایت، درست پیش از تگ بسته </body> قرار دهید تا در تمام صفحه‌های موردنظر بارگذاری شود:

<!doctype html>
<html lang="fa" dir="rtl">
  <head>
    <!-- head content -->
  </head>
  <body>
    <!-- page content -->

    <!-- کد ویجت ایلاچت را اینجا قرار دهید. -->
  </body>
</html>

در سایت‌هایی که قالب یا چیدمان مشترک دارند، اسکریپت را فقط در همان قالب اصلی قرار دهید. در برنامه‌های تک‌صفحه‌ای نیز کد باید یک بار در چیدمان ریشه اجرا شود، نه در هر تغییر مسیر داخلی.

پس از انتشار تغییرات، کش سایت و CDN را پاک کنید، صفحه را در پنجره ناشناس باز کنید و این موارد را بیازمایید:

آیکن ویجت نمایش داده شود؛
پنجره گفت‌وگو باز و بسته شود؛
یک پیام آزمایشی ارسال و پاسخ دریافت شود؛
نمایش در موبایل و دسکتاپ با محتوای سایت تداخل نداشته باشد.

انتخاب نوع کد ویجت

سه کد، فایل یکسان ویجت را بارگذاری می‌کنند؛ تفاوت آن‌ها فقط در زمان شروع بارگذاری است. در هر صفحه فقط یکی از این سه روش را استفاده کنید.

نوع کد	زمان بارگذاری	مزیت اصلی	ملاحظه
پیش‌فرض	پس از کامل‌شدن بارگذاری صفحه	تعادل مناسب بین تجربه کاربر و عملکرد؛ پیشنهاد برای بیشتر سایت‌ها	آیکن پس از رویداد `load` ظاهر می‌شود.
نمایش سریع	بلافاصله هنگام رسیدن مرورگر به کد	سریع‌ترین نمایش ممکن ویجت	دانلود ویجت می‌تواند هم‌زمان با منابع اولیه سایت انجام شود.
مناسب PageSpeed	پس از اولین تعامل کاربر	کمترین اثر روی سنجه‌های بارگذاری اولیه	تا پیش از تعامل، ویجت دانلود و نمایش داده نمی‌شود.

کد پیش‌فرض

این روش منتظر کامل‌شدن صفحه می‌ماند و سپس فایل ویجت را با defer اضافه می‌کند. برای اغلب وب‌سایت‌ها این گزینه انتخاب مناسبی است.

<script id="ILACHATWIDGETSCRIPT">
  (function () {
    function loadIlaWidget() {
      const script = document.createElement('script');
      script.src = 'https://widget.ila.chat/chat-widget.umd.js.gz';
      script.defer = true;
      script.setAttribute('data-bot-widget-token', 'YOUR_WIDGET_TOKEN');
      document.body.appendChild(script);
    }

    if (document.readyState === 'complete') {
      loadIlaWidget();
    } else {
      window.addEventListener('load', loadIlaWidget);
    }
  })();
</script>

کد نمایش سریع

این روش بدون انتظار برای رویداد load، دانلود فایل ویجت را به‌صورت ناهمگام شروع می‌کند. اگر نمایش هرچه سریع‌تر آیکن گفت‌وگو از امتیاز عملکرد اولیه مهم‌تر است، این حالت را انتخاب کنید.

<script id="ILACHATWIDGETSCRIPT">
  (function () {
    const script = document.createElement('script');
    script.src = 'https://widget.ila.chat/chat-widget.umd.js.gz';
    script.async = true;
    script.setAttribute('data-bot-widget-token', 'YOUR_WIDGET_TOKEN');
    document.body.appendChild(script);
  })();
</script>

کد مناسب PageSpeed

این روش تا اولین تعامل کاربر صبر می‌کند. فشردن کلید، لمس، حرکت لمسی یا حرکت نشانگر روی صفحه باعث بارگذاری ویجت می‌شود. پرچم isIlaChatAdded از افزودن چندباره فایل جلوگیری می‌کند.

<script id="ILACHATWIDGETSCRIPT">
  (function () {
    ['keydown', 'touchmove', 'touchstart', 'mouseover'].forEach(function (eventType) {
      window.addEventListener(eventType, function () {
        if (!window.isIlaChatAdded) {
          window.isIlaChatAdded = true;

          const script = document.createElement('script');
          script.src = 'https://widget.ila.chat/chat-widget.umd.js.gz';
          script.async = true;
          script.setAttribute('data-bot-widget-token', 'YOUR_WIDGET_TOKEN');
          document.body.appendChild(script);
        }
      });
    });
  })();
</script>

این حالت می‌تواند امتیاز PageSpeed را بهتر حفظ کند، اما بازدیدکننده‌ای که هنوز با صفحه تعامل نکرده است ویجت را نمی‌بیند. برای صفحه‌ای که پشتیبانی فوری بخش اصلی تجربه آن است، کد پیش‌فرض یا نمایش سریع معمولاً مناسب‌تر است.

شخصی‌سازی از پنل ایلاچت

بخش بزرگی از تنظیمات بدون کدنویسی و همراه پیش‌نمایش زنده در پنل ایلاچت انجام می‌شود:

زبان پاسخ، تشخیص خودکار زبان کاربر، لحن و طول پاسخ؛
نمایش Markdown، استفاده از ایموجی و افکت تایپ پاسخ؛
انتقال گفت‌وگو به اپراتور انسانی یا نمایش راه‌های ارتباطی؛
جمع‌آوری نام، ایمیل و شماره تماس لید؛
تصویر یا آیکن ویجت، محل نمایش، ابعاد و فاصله در موبایل و دسکتاپ؛
پیام خوش‌آمدگویی و اولین پیام؛
رنگ‌بندی، حالت روشن و تیره و هماهنگی خودکار با تنظیم سیستم کاربر؛
محدودکردن نمایش ویجت به دامنه‌های مجاز؛
محدودیت تعداد پیام در یک بازه زمانی برای کنترل هرزنامه و مصرف غیرعادی.

پیش از نوشتن کد سفارشی، بررسی کنید آیا نیاز شما از همین تنظیمات قابل انجام است. تنظیمات پنل برای نگهداری بلندمدت ساده‌ترند و بدون انتشار دوباره سایت قابل تغییر خواهند بود.

تنظیمات پاسخ‌گویی

زبان پاسخ می‌تواند فارسی، انگلیسی، عربی، ترکی یا متناسب با پیام کاربر باشد. حالت متناسب با پیام کاربر برای سایت‌های چندزبانه مناسب است.
لحن پاسخ را از میان رسمی، حرفه‌ای، دوستانه و غیررسمی انتخاب کنید.
طول پیام کوتاه، متوسط یا بلند است. این تنظیم ترجیح پاسخ‌گویی است و طول دقیق پاسخ به محتوای سؤال نیز بستگی دارد.
گزینه «زبان انگلیسی و چپ‌چین» رابط ویجت را انگلیسی و جهت آن را LTR می‌کند؛ این گزینه با زبان پاسخ چت‌بات تفاوت دارد.
در پلن‌های دارای دسترسی، «نوتیفیکیشن کاربران» اعلان پیام جدید را فعال می‌کند. مرورگر همچنان باید مجوز اعلان را از خود کاربر دریافت کند.
در «دستورالعمل (Prompt)» می‌توانید نقش چت‌بات، قوانین پاسخ‌گویی، موارد ممنوع و شیوه برخورد با درخواست‌ها را مشخص کنید. حداکثر طول این متن ۱۲٬۰۰۰ کاراکتر است.

درخواست اپراتور انسانی و فیلتر پیام

برای ارجاع درخواست به اپراتور، «عبارت فعال‌سازی» را طوری بنویسید که زمان ارجاع روشن باشد؛ برای نمونه، درخواست صحبت با پشتیبان یا محدودیت ساعات کاری. «متن پیام» نیز پاسخی است که پس از تشخیص این درخواست برای کاربر فرستاده می‌شود. هرکدام از این دو متن حداکثر ۳۰۰ کاراکتر دارند و پاسخ از پیش تعیین‌شده سهم پاسخ‌های هوش مصنوعی اشتراک را مصرف نمی‌کند.

فیلتر پیام نیز برای عبارت‌های مشخص، پاسخ هوش مصنوعی را متوقف و متن ثابت شما را ارسال می‌کند. عبارت فعال‌سازی و پیام جایگزین هرکدام حداکثر ۳۰۰ کاراکتر هستند؛ برای مثال می‌توانید عبارت را این‌گونه تعریف کنید: «وقتی پیام شامل توهین، ناسزا یا الفاظ رکیک است».

بخش‌های قابل نمایش

«ارسال پیام صوتی» دکمه ضبط ویس را نمایش می‌دهد و به مجوز میکروفون کاربر نیاز دارد.
«ارسال فایل» انتخاب فایل، Paste و Drag & Drop را فعال می‌کند. در هر پیام حداکثر ۵ فایل و برای هر فایل حجمی کمتر از ۱۰ مگابایت پذیرفته می‌شود.
«پنل ایموجی» انتخاب ایموجی در کادر پیام را فعال می‌کند.
«حذف کپی‌رایت ایلاچت» فقط در پلن دارای دسترسی قابل فعال‌سازی است.

متن «Powered By ILACHAT» محافظت شده است. ترجمه سفارشی نمی‌تواند آن را حذف، خالی یا بازنویسی کند؛ برای حذف کامل، فقط از گزینه مجاز پنل و پلن دارای دسترسی استفاده کنید.

ظاهر، متن‌ها و رنگ‌ها

برای آیکن ویجت می‌توانید آیکون ایلاچت یا آیکون گفت‌وگو را انتخاب کنید. آپلود تصویر اختصاصی و انتخاب آیکون‌های بیشتر بسته به پلن است. تصویر اختصاصی باید PNG، JPG/JPEG، WebP یا GIF معتبر، کوچک‌تر از ۲ مگابایت و حداکثر ۵۱۲×۵۱۲ پیکسل باشد. رنگ پس‌زمینه آیکن و، در حالت آیکون برداری، رنگ خود آیکون نیز قابل تغییر است.

محل قرارگیری آیکن راست یا چپ است؛ مقدار 1 برای اندازه عادی است و نسبت اندازه معتبر بین 0.1 تا 5 قرار دارد.
فاصله افقی و فاصله از پایین در موبایل و دسکتاپ جداگانه تنظیم می‌شوند؛ مقدار معتبر هرکدام بین صفر تا ۱۰۰۰ پیکسل است.
انیمیشن جلب توجه را از میان چهار حالت انتخاب کنید یا آن را روی «هیچ‌کدام» بگذارید. تأخیر انیمیشن بر حسب ثانیه و از صفر است.
نمایش پاپ‌آپ خوش‌آمدگویی و پیام جدید برای موبایل و دسکتاپ جداگانه کنترل می‌شود. نمایش آن در موبایل را طوری آزمایش کنید که محتوای مهم صفحه را نپوشاند.
توضیح کوتاه زیر نام چت‌بات حداکثر ۱۰۰ کاراکتر و پیام اول یا خوش‌آمدگویی حداکثر ۳۰۰ کاراکتر است؛ پیام خوش‌آمدگویی از چند خط نیز پشتیبانی می‌کند.
حداکثر ۱۰ پرسش آماده، هرکدام تا ۲۰۰ کاراکتر، قابل ثبت است. پرسش‌ها را با Enter اضافه و با Drag & Drop مرتب یا حذف کنید؛ پرسش تکراری اضافه نمی‌شود.

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

در پلن دارای دسترسی، CSS اختصاصی را از بخش «استایل اختصاصی» وارد کنید. تغییر کلاس‌های داخلی ممکن است با به‌روزرسانی رابط نیازمند بازبینی شود؛ برای تغییرات ساده رنگی، تنظیمات رنگ پنل یا متغیرهای رسمی API پایدارترند.

دامنه‌های مجاز و محدودیت پیام

در «دامنه‌های مجاز» تعیین می‌کنید ویجت از چه سایت‌هایی اجازه استفاده دارد. لیست خالی یعنی همه دامنه‌ها مجازند و حداکثر ۵ دامنه یکتا قابل ثبت است. فقط نام دامنه، مانند example.com یا shop.example.com، را وارد کنید؛ پروتکل، مسیر و اسلش معتبر نیستند. نسخه‌های www و بدون www را نیز در صورت استفاده جداگانه ثبت کنید.

با فعال‌کردن محدودیت تعداد پیام، حداکثر پیام مجاز، بازه زمانی بر حسب ثانیه و پیام نمایش‌داده‌شده هنگام محدودیت را وارد کنید. پیام محدودیت حداکثر ۳۵۰ کاراکتر است و می‌تواند شامل {seconds} برای زمان باقی‌مانده و {available_time} برای ساعت پایان محدودیت باشد:

لطفاً {seconds} ثانیه صبر کنید. امکان ارسال مجدد در ساعت {available_time} فعال می‌شود.

افزودن اطلاعات لید

با تعریف متغیر سراسری ilachat_lead_data می‌توانید اطلاعات کاربر شناخته‌شده را پیش از بارگذاری ویجت در اختیار آن قرار دهید. این اسکریپت باید قبل از کد بارگذاری ویجت قرار بگیرد.

<script id="ilachat-widget-js-extra">
  window.ilachat_lead_data = {
    user_id: '42',
    email: 'user@example.com',
    mobile: '09120000000',
    name: 'کاربر نمونه'
  };
</script>

کلید	کاربرد	توصیه
`user_id`	شناسه کاربر در سامانه شما	آن را به رشته تبدیل کنید.
`email`	ایمیل کاربر	فقط ایمیل همان کاربر واردشده را ارسال کنید.
`mobile`	شماره همراه	قالب ثابتی برای شماره‌ها در نظر بگیرید.
`name`	نام نمایشی	مقدار را پیش از چاپ پاک‌سازی کنید.

نمونه کامل ترتیب صحیح:

<script id="ilachat-widget-js-extra">
  window.ilachat_lead_data = {
    user_id: '42',
    email: 'user@example.com',
    mobile: '09120000000',
    name: 'کاربر نمونه'
  };
</script>

<script id="ILACHATWIDGETSCRIPT">
  (function () {
    function loadIlaWidget() {
      const script = document.createElement('script');
      script.src = 'https://widget.ila.chat/chat-widget.umd.js.gz';
      script.defer = true;
      script.setAttribute('data-bot-widget-token', 'YOUR_WIDGET_TOKEN');
      document.body.appendChild(script);
    }

    if (document.readyState === 'complete') {
      loadIlaWidget();
    } else {
      window.addEventListener('load', loadIlaWidget);
    }
  })();
</script>

داده لید در مرورگر بازدیدکننده قابل مشاهده است. رمز عبور، توکن دسترسی، اطلاعات پرداخت، یادداشت داخلی یا هر داده‌ای که کاربر مجاز به دیدن آن نیست در این متغیر قرار ندهید. هنگام تولید این شیء در سمت سرور، از روش استاندارد تبدیل داده به JSON استفاده کنید و مقدار خام کاربر را مستقیماً داخل JavaScript نچسبانید.

استفاده از API جاوااسکریپت

شیء window.ILACHAT پس از آماده‌شدن ویجت ساخته می‌شود. فراخوانی متدها پیش از آن ممکن است با خطا روبه‌رو شود؛ بنابراین کد راه‌اندازی را داخل شنونده ILACHAT_WidgetReady قرار دهید.

<script>
  window.addEventListener('ILACHAT_WidgetReady', function (event) {
    console.log('ویجت آماده است.');

    window.ILACHAT.setWidgetLanguage('fa');
    window.ILACHAT.setWidgetDirection('rtl');
  });
</script>

جزئیات رویداد شامل bot_token است، اما در بیشتر یکپارچه‌سازی‌ها به خواندن یا ثبت آن نیازی ندارید. شنونده رویداد را پیش از کد نصب ویجت قرار دهید؛ در روش PageSpeed، رویداد پس از اولین تعامل و بارگذاری ویجت اجرا می‌شود.

کنترل پنجره گفت‌وگو

متد	کاربرد	خروجی
`window.ILACHAT.openWidget()`	بازکردن پنجره گفت‌وگو	ندارد
`window.ILACHAT.closeWidget()`	بستن پنجره گفت‌وگو	ندارد
`window.ILACHAT.toggleWidget()`	تغییر وضعیت؛ باز را می‌بندد و بسته را باز می‌کند	ندارد
`window.ILACHAT.getWidgetStatus()`	خواندن وضعیت فعلی	`open` یا `close`

window.ILACHAT.openWidget();
window.ILACHAT.closeWidget();
window.ILACHAT.toggleWidget();

const status = window.ILACHAT.getWidgetStatus();
console.log('Widget status:', status);

دکمه اختصاصی برای بازکردن گفت‌وگو

اگر می‌خواهید گفت‌وگو از دکمه‌ای در سربرگ، صفحه قیمت‌گذاری یا بخش پشتیبانی باز شود، اتصال رویداد کلیک را پس از آماده‌شدن ویجت انجام دهید:

<button id="openChat" type="button">گفت‌وگو با پشتیبانی</button>

<script>
  window.addEventListener('ILACHAT_WidgetReady', function () {
    const openButton = document.getElementById('openChat');

    openButton.addEventListener('click', function () {
      window.ILACHAT.openWidget();
    });
  });
</script>

رویدادهای ویجت

رویداد `ILACHAT_WidgetReady`

پس از راه‌اندازی کامل ویجت و آماده‌شدن متدهای window.ILACHAT اجرا می‌شود.

فیلد `event.detail`	نوع	توضیح
`bot_token`	`string`	شناسه ویجتی که آماده شده است

رویداد `ILACHAT_WidgetStatusChange`

هر بار که پنجره گفت‌وگو باز یا بسته شود اجرا می‌شود.

فیلد `event.detail`	نوع	توضیح
`bot_token`	`string`	شناسه ویجت
`status`	`open` یا `closed`	وضعیت جدید پنجره گفت‌وگو

<script>
  window.addEventListener('ILACHAT_WidgetStatusChange', function (event) {
    const status = event.detail.status;
    const supportButton = document.getElementById('supportBtn');

    if (!supportButton) {
      return;
    }

    supportButton.hidden = status === 'open';
  });
</script>

ارسال وضعیت به Google Tag Manager

<script>
  window.addEventListener('ILACHAT_WidgetStatusChange', function (event) {
    window.dataLayer = window.dataLayer || [];
    window.dataLayer.push({
      event: 'ilachat_widget_status',
      status: event.detail.status
    });
  });
</script>

در Google Tag Manager می‌توانید یک رویداد سفارشی با نام ilachat_widget_status بسازید و مقدار status را برای تحلیل باز و بسته‌شدن ویجت استفاده کنید. برای رعایت حریم خصوصی، توکن ویجت یا اطلاعات لید را به ابزارهای تحلیلی ارسال نکنید.

ترجمه، زبان و جهت متن

متد setWidgetTranslations() ترجمه‌های دلخواه را با ترجمه‌های موجود ادغام می‌کند؛ یعنی فقط کلیدهای ارسالی تغییر می‌کنند و مقدارهای دیگر پاک نمی‌شوند. زبان‌های داخلی fa، id، ar و tr هستند؛ en متن اصلی و fallback است. در صورت نیاز می‌توانید کد زبان معتبر دیگری مانند de یا fr-CA نیز تعریف کنید.

window.ILACHAT.setWidgetTranslations({
  fa: {
    Message: 'پیام',
    Reply: 'پاسخ به',
    'Load more': 'موارد بیشتر',
    'Type your message here...': 'پیام خود را اینجا بنویسید...'
  }
});

کلید ترجمه باید دقیقاً با متن اصلی یکسان باشد. همه متن‌های قابل مشاهده، از جمله پیام اول، توضیح ویجت، پرسش‌های آماده، پیام‌ها، لینک‌ها، عنوان و توضیح فرم، فیلدها، Placeholderها، گزینه‌ها، دکمه‌ها، خطاها و پیام موفقیت قابل ترجمه‌اند. برای متن‌های تنظیم‌شده در پنل نیز خود همان متن را به‌عنوان کلید بنویسید. مقدار خالی "" برای متن‌های عادی مجاز است، اما دو کلید Powered By و ILACHAT محافظت‌شده‌اند و با API ترجمه سفارشی تغییر نمی‌کنند.

برای تغییر یک متن، فقط همان کلید را ارسال کنید:

window.ILACHAT.setWidgetTranslations({
  fa: {
    Message: 'پیام'
  }
});

پس از تعریف ترجمه، زبان فعال و جهت چیدمان را مشخص کنید:

window.ILACHAT.setWidgetLanguage('fa');
window.ILACHAT.setWidgetDirection('rtl');

مقدار جهت باید rtl یا ltr باشد. پیش از انتخاب یک زبان مطمئن شوید ترجمه‌های آن در ویجت وجود دارد.

رنگ و CSS پویا

متد setWidgetTheme() رنگ‌های پویا را برای حالت‌های روشن و تاریک تنظیم می‌کند. نام‌های chatBoxLightColors و chatBoxDarkColors نیز به‌جای light و dark پذیرفته می‌شوند. فقط کلیدهای CSS که با -- شروع شوند اعمال می‌شوند و مقدار null یک Override را حذف می‌کند.

window.ILACHAT.setWidgetTheme({
  light: {
    '--messages-bg-color': '#ffffff',
    '--user-message-bg-color': '#0066ff'
  },
  dark: {
    '--messages-bg-color': '#111111',
    '--user-message-bg-color': '#4d8dff'
  }
});

متغیر	کاربرد
`--messages-bg-color`	پس‌زمینه گفت‌وگو
`--header-bg-color` / `--header-color`	پس‌زمینه و متن هدر
`--bot-message-bg-color` / `--bot-message-color`	پیام چت‌بات
`--user-message-bg-color` / `--user-message-color`	پیام کاربر
`--agent-message-bg-color` / `--agent-message-color`	پیام اپراتور
`--name-color` / `--meta-color`	نام فرستنده و تاریخ یا ساعت
`--input-bg-color` / `--input-color`	کادر تایپ
`--submit-bg-color` / `--submit-color`	دکمه ارسال
`--button-bg-color` / `--button-color`	دکمه‌های شیشه‌ای
`--widget-icon-bg-color` / `--widget-icon-color`	آیکون ویجت

اگر پلن شما اجازه می‌دهد، addWidgetCustomStyle() CSS جدید را به استایل سفارشی موجود اضافه می‌کند. برای تغییرات رنگی ساده از setWidgetTheme() استفاده کنید.

window.ILACHAT.addWidgetCustomStyle(`
  .chat__header { border-bottom: 1px solid rgba(0, 0, 0, .08); }
`);

موقعیت، فاصله و مقیاس

متد setWidgetPositions() موقعیت آیکن و پنجره، فاصله‌ها، مقیاس و نمایش آیکن شناور را تغییر می‌دهد:

window.ILACHAT.setWidgetPositions({
  position: 'right',
  xMarginSmall: 16,
  bottomMarginSmall: 16,
  xMarginLarge: 24,
  bottomMarginLarge: 24,
  widgetScale: 1,
  hideIcon: false
});

گزینه	نوع	نمونه	توضیح
`position`	`string`	`right`	جایگاه افقی؛ `left` یا `right`
`xMarginSmall`	`number`	`16`	فاصله افقی در نمایشگر کوچک، بر حسب پیکسل
`bottomMarginSmall`	`number`	`16`	فاصله از پایین در نمایشگر کوچک، بر حسب پیکسل
`xMarginLarge`	`number`	`24`	فاصله افقی در نمایشگر بزرگ، بر حسب پیکسل
`bottomMarginLarge`	`number`	`24`	فاصله از پایین در نمایشگر بزرگ، بر حسب پیکسل
`widgetScale`	`number`	`1`	ضریب مقیاس ویجت
`hideIcon`	`boolean`	`false`	مخفی‌کردن آیکن شناور ویجت

اگر hideIcon را true می‌کنید، حتماً یک دکمه جایگزین و قابل استفاده با صفحه‌کلید برای بازکردن گفت‌وگو قرار دهید.

چند ویجت در یک صفحه

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

const widget = window.ILACHAT['widget_YOUR_BOT_TOKEN'];

widget.setTranslations({ en: { 'Load more': 'Show more' } });
widget.setLanguage('en');
widget.setDirection('ltr');
widget.setTheme({ light: { '--messages-bg-color': '#ffffff' } });
widget.setPositions({ position: 'left' });
widget.open();
widget.close();
widget.toggleWidget();
console.log(widget.getStatus());

متد addCustomStyle() نیز فقط در پلن دارای دسترسی روی API توکن‌دار موجود است.

نمونه کامل شخصی‌سازی پس از آماده‌شدن ویجت

<button id="openChat" type="button">پشتیبانی آنلاین</button>

<script>
  window.addEventListener('ILACHAT_WidgetReady', function () {
    window.ILACHAT.setWidgetTranslations({
      fa: {
        'Load more': 'موارد بیشتر',
        Message: 'پیام',
        'Type your message here...': 'پیام خود را اینجا بنویسید...'
      }
    });

    window.ILACHAT.setWidgetLanguage('fa');
    window.ILACHAT.setWidgetDirection('rtl');

    window.ILACHAT.setWidgetPositions({
      position: 'right',
      xMarginSmall: 16,
      bottomMarginSmall: 16,
      xMarginLarge: 24,
      bottomMarginLarge: 24,
      widgetScale: 1,
      hideIcon: true
    });

    document.getElementById('openChat').addEventListener('click', function () {
      window.ILACHAT.openWidget();
    });
  });
</script>

این کد باید در همان صفحه‌ای باشد که کد اصلی ویجت بارگذاری می‌شود. ترتیب قرارگیری پیشنهادی عبارت است از: داده لید، شنونده‌ها و پیکربندی سفارشی، سپس کد بارگذاری ویجت.

نصب در سایت‌های دارای سیاست امنیت محتوا

اگر سایت شما از Content Security Policy استفاده می‌کند، ممکن است لازم باشد دامنه فایل ویجت را در script-src مجاز کنید. سیاست دقیق باید با تنظیمات امنیتی و منابع مورد استفاده سایت خودتان هماهنگ شود. نمونه ساده:

Content-Security-Policy: script-src 'self' https://widget.ila.chat; connect-src 'self' https://widget.ila.chat;

سیاست موجود را بدون بررسی جایگزین نکنید؛ فقط دامنه موردنیاز را به دستور فعلی اضافه کنید و نتیجه را در مرورگر آزمایش نمایید.

عیب‌یابی

ویجت نمایش داده نمی‌شود

مطمئن شوید کد را کامل و فقط یک بار، پیش از </body> قرار داده‌اید.
بررسی کنید مقدار توکن از کد اختصاصی پنل ایلاچت آمده باشد.
در حالت مناسب PageSpeed، ابتدا با صفحه تعامل کنید تا بارگذاری آغاز شود.
کش سایت، افزونه بهینه‌سازی و CDN را پاک کنید.
خطاهای Console و درخواست فایل https://widget.ila.chat/chat-widget.umd.js.gz را در ابزار توسعه مرورگر بررسی کنید.
اگر نمایش به دامنه‌های مشخص محدود شده، دامنه فعلی را در پنل مجاز کنید.
سیاست امنیت محتوا، مسدودکننده‌های مرورگر و مجازبودن بارگذاری اسکریپت و ارتباط شبکه‌ای با https://widget.ila.chat را بررسی کنید.

ilachat_lead_data باید پیش از کد اصلی ویجت تعریف شود.
نام متغیر و کلیدهای user_id، email، mobile و name را دقیق بررسی کنید.
قابلیت جمع‌آوری لید باید در تنظیمات ایلاچت فعال باشد.
پس از خروج کاربر از حساب، داده کاربر قبلی را در برنامه‌های تک‌صفحه‌ای نگه ندارید.

میکروفون، فایل یا اعلان کار نمی‌کند

سایت باید با HTTPS باز شود.
قابلیت مربوطه باید در پنل فعال باشد.
مجوز میکروفون یا اعلان در مرورگر نباید مسدود شده باشد.
محدودیت تعداد و حجم فایل را بررسی کنید.

تغییرات پنل دیده نمی‌شوند

ابتدا «ذخیره تغییرات» را بزنید.
صفحه سایت را کامل Refresh کنید و در صورت نیاز کش یا CDN را پاک کنید.
مطمئن شوید همان توکن چت‌باتی را آزمایش می‌کنید که تنظیماتش را تغییر داده‌اید.
حالت روشن و تاریک سیستم را جداگانه بررسی کنید؛ رنگ هر حالت مستقل ذخیره می‌شود.

نکات نهایی

کد اختصاصی پنل خودتان را مبنا قرار دهید و توکن نمونه استفاده نکنید.
در هر صفحه فقط یک بار و با یکی از سه روش، فایل ویجت را بارگذاری کنید.
برای بیشتر سایت‌ها از کد پیش‌فرض شروع کنید و فقط بر اساس نیاز واقعی به نمایش سریع یا PageSpeed تغییر دهید.
تنظیمات و متدها را پس از ILACHAT_WidgetReady اجرا کنید.
هنگام مخفی‌کردن آیکن شناور، دکمه جایگزین قابل‌دسترس فراهم کنید.
داده لید و رویدادهای تحلیلی را به حداقل اطلاعات ضروری محدود کنید.
نصب را پس از هر تغییر در موبایل، دسکتاپ و یک پنجره ناشناس آزمایش کنید.

چک‌لیست پیش از انتشار

نصب را روی دامنه اصلی و همه زیردامنه‌های مورد استفاده آزمایش کنید.
ارسال و دریافت پیام در موبایل و دسکتاپ درست باشد و جایگاه ویجت مزاحم Cookie Banner، دکمه خرید یا منوی موبایل نباشد.
فرم‌های اجباری و اختیاری، پیام موفقیت و وب‌هوک را آزمایش کنید.
میکروفون، آپلود فایل و اعلان را فقط در صورت نیاز فعال کنید.
محدودیت تعداد پیام را با مقدار واقعی و پیامی قابل فهم تنظیم کنید.
حالت روشن، تاریک، فارسی و RTL و در صورت نیاز انگلیسی و LTR را بررسی کنید.
متن کپی‌رایت را فقط با گزینه مجاز پنل و مطابق پلن مدیریت کنید.

ویجت گفت‌وگو