مستندات آیفریم گفت‌وگو

راهنمای نصب، تعیین اندازه، ارسال اطلاعات لید و تنظیم آیفریم گفت‌وگوی ایلاچت در وب‌سایت.

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

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

دریافت کد آیفریم از پنل ایلاچت

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

کد پایه به‌شکل زیر است. مقدارهای YOUR_IFRAME_TOKEN در کدی که از پنل کپی می‌کنید با توکن واقعی همان چت‌بات پر شده‌اند:

<iframe
  src="https://iframe.ila.chat/YOUR_IFRAME_TOKEN?ILACHATTOKEN=YOUR_IFRAME_TOKEN"
  width="100%"
  height="100%"
  frameborder="0"
  allow="microphone;">
</iframe>

هر دو مقدار توکن در مسیر و پارامتر ILACHATTOKEN باید بدون تغییر باقی بمانند. کد را به متن قابل کلیک یا Markdown تبدیل نکنید؛ باید به‌صورت HTML واقعی در محل دلخواه صفحه قرار گیرد.

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

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

قراردادن آیفریم در صفحه

مقدار height="100%" فقط وقتی درست کار می‌کند که عنصر والد ارتفاع مشخص داشته باشد. نمونه زیر برای بیشتر صفحه‌های پشتیبانی و پنل‌های کاربری مناسب است:

<div class="ilachat-frame-wrapper">
  <iframe
    src="https://iframe.ila.chat/YOUR_IFRAME_TOKEN?ILACHATTOKEN=YOUR_IFRAME_TOKEN"
    title="گفت‌وگو با پشتیبانی"
    allow="microphone;"
    loading="eager">
  </iframe>
</div>

<style>
  .ilachat-frame-wrapper {
    width: 100%;
    height: min(760px, calc(100dvh - 120px));
    min-height: 520px;
  }

  .ilachat-frame-wrapper iframe {
    display: block;
    width: 100%;
    height: 100%;
    border: 0;
  }

  @media (max-width: 640px) {
    .ilachat-frame-wrapper {
      height: calc(100dvh - 72px);
      min-height: 420px;
    }
  }
</style>

مقادیر 120px و 72px را متناسب با ارتفاع هدر یا منوی سایت خود تنظیم کنید. 100dvh در موبایل با باز و بسته‌شدن نوار مرورگر رفتار مناسب‌تری از 100vh دارد.

ویژگی title برای دسترس‌پذیری توصیه می‌شود. allow="microphone;" برای ضبط پیام صوتی لازم است. اگر آیفریم پایین صفحه فقط هنگام نزدیک‌شدن کاربر باید بارگذاری شود، loading="lazy" را در نظر بگیرید؛ در صفحه‌ای که گفت‌وگو بخش اصلی تجربه است، eager تجربه سریع‌تری می‌دهد.

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

می‌توانید اطلاعات کاربر واردشده به سایت را همراه URL آیفریم ارسال کنید. پارامترهای پشتیبانی‌شده عبارت‌اند از:

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

نمونه ثابت:

<iframe
  src="https://iframe.ila.chat/YOUR_IFRAME_TOKEN?ILACHATTOKEN=YOUR_IFRAME_TOKEN&user_id=USER-123&name=Ali&email=user%40example.com&mobile=%2B989121234567"
  width="100%"
  height="650"
  title="گفت‌وگو با پشتیبانی"
  frameborder="0"
  allow="microphone;">
</iframe>

برای داده پویا، URL را با URLSearchParams بسازید تا نام، ایمیل و علامت + به‌درستی Encode شوند:

<iframe id="ilachat-frame" title="گفت‌وگو با پشتیبانی" allow="microphone;"></iframe>

<script>
  const token = 'YOUR_IFRAME_TOKEN';
  const params = new URLSearchParams({
    ILACHATTOKEN: token,
    user_id: 'USER-123',
    name: 'علی رضایی',
    email: 'user@example.com',
    mobile: '+989121234567'
  });

  document.getElementById('ilachat-frame').src =
    `https://iframe.ila.chat/${encodeURIComponent(token)}?${params.toString()}`;
</script>

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

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

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

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

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

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

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

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

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

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

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

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

تنظیمات ظاهری آیفریم

پیام خوش‌آمدگویی و پرسش‌های آماده

پیام اول و خوش‌آمدگویی در آغاز گفتگو نمایش داده می‌شود، چند خط را پشتیبانی می‌کند و حداکثر ۳۰۰ کاراکتر دارد.
حداکثر ۱۰ پرسش آماده، هرکدام تا ۲۰۰ کاراکتر، قابل ثبت است. پرسش‌ها را با Enter اضافه و با Drag & Drop مرتب یا حذف کنید؛ پرسش تکراری اضافه نمی‌شود.

رنگ و استایل اختصاصی

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

در پلن دارای دسترسی، CSS اختصاصی را از بخش «استایل اختصاصی» وارد کنید. استایل سایت والد به محتوای داخل آیفریم اعمال نمی‌شود و استایل آیفریم نیز روی سایت والد اثر ندارد؛ بنابراین CSS اندازه و قاب بیرونی را در سایت خود، و CSS ظاهر چت را در پنل قرار دهید. تغییر کلاس‌های داخلی ممکن است با به‌روزرسانی رابط نیازمند بازبینی شود.

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

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

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

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

زبان، ترجمه و محدودیت Cross-Origin

برای استفاده معمول، زبان رابط، متن‌های رابط، پیام خوش‌آمدگویی، پرسش‌های آماده و متن‌های فرم را از پنل تنظیم کنید. آدرس iframe.ila.chat با دامنه سایت شما متفاوت است؛ بنابراین مرورگر به‌دلیل Same-Origin Policy اجازه نمی‌دهد JavaScript صفحه والد مستقیماً به iframe.contentWindow.ILACHAT یا عناصر داخل آیفریم دسترسی پیدا کند.

برای پیاده‌سازی استاندارد:

تنظیمات ظاهری، زبان و متن‌ها را در پنل انجام دهید.
اطلاعات اولیه کاربر را با پارامترهای URL همین صفحه ارسال کنید.
برای تشخیص پایان بارگذاری قاب از رویداد load خود عنصر iframe استفاده کنید.

document.getElementById('ilachat-frame').addEventListener('load', function () {
  console.log('ILACHAT iframe loaded');
});

تلاش برای فراخوانی مستقیم توابع داخل آیفریم از صفحه والد معمولاً با خطای Cross-Origin متوقف می‌شود. از Proxyکردن یا تغییر دامنه آیفریم بدون هماهنگی با ایلاچت استفاده نکنید؛ این کار می‌تواند ذخیره گفتگو، مجوز میکروفون و ارتباط زنده را مختل کند.

CSP و مجوز میکروفون

اگر سایت شما از Content Security Policy استفاده می‌کند، ممکن است لازم باشد https://iframe.ila.chat را در frame-src مجاز کنید. سیاست دقیق باید با تنظیمات امنیتی سایت خودتان هماهنگ شود. نمونه ساده:

Content-Security-Policy: frame-src https://iframe.ila.chat;

اگر سایت از هدر Permissions-Policy استفاده می‌کند، میکروفون باید برای دامنه آیفریم مجاز باشد. ویژگی allow="microphone;" روی iframe نیز باید باقی بماند. سایت و آیفریم هر دو باید با HTTPS باز شوند و کاربر باید مجوز مرورگر را تأیید کند.

ویژگی sandbox را بدون بررسی اضافه نکنید؛ محدودکردن Script، Form، Storage یا Origin می‌تواند گفت‌وگو را از کار بیندازد.

عیب‌یابی

آیفریم سفید، خالی یا مسدود است

توکن مسیر و مقدار ILACHATTOKEN را با کد پنل مقایسه کنید.
دامنه فعلی را با فهرست دامنه‌های مجاز تطبیق دهید.
Console و Network را برای خطای CSP، Ad Blocker یا قطع دسترسی به https://iframe.ila.chat بررسی کنید.
اگر sandbox اضافه کرده‌اید، موقتاً آن را حذف و دوباره آزمایش کنید.

ارتفاع آیفریم صفر یا خیلی کوتاه است

برای والد آیفریم height یا min-height مشخص کنید.
فقط height="100%" کافی نیست اگر ارتفاع والد auto باشد.
در Flex یا Grid مطمئن شوید والد امکان رشد دارد و با overflow: hidden ناخواسته بریده نشده است.

میکروفون کار نمی‌کند

گزینه ارسال ویس در پنل فعال باشد.
allow="microphone;" روی iframe وجود داشته باشد.
سایت با HTTPS باز شود و مجوز میکروفون در مرورگر مسدود نشده باشد.
هدر Permissions-Policy سایت میزبان، میکروفون را برای آیفریم منع نکرده باشد.

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

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

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

آیفریم روی دامنه اصلی و همه زیردامنه‌های لازم باز می‌شود.
ارتفاع آن در موبایل، تبلت و دسکتاپ مناسب است.
title و allow="microphone;" تنظیم شده‌اند.
ارسال پیام، فایل و ویس آزمایش شده است.
فرم‌های اجباری و اختیاری، پیام موفقیت و وب‌هوک بررسی شده‌اند.
اطلاعات اولیه کاربر درست Encode می‌شوند و داده حساس در URL نیست.
محدودیت تعداد پیام با مقدار واقعی و پیامی قابل فهم تنظیم شده است.
حالت روشن، تاریک، فارسی و RTL و در صورت نیاز انگلیسی و LTR بررسی شده‌اند.
متن کپی‌رایت فقط با گزینه مجاز پنل و مطابق پلن مدیریت شده است.

آیفریم گفت‌وگو

در این صفحه