راهنمای توسعه‌دهنده · ویجت

گفت‌وگو را از صفحه خودتان کنترل کنید

نصب و دکمه پشتیبانی

کلید عمومی ویجت را از تنظیمات اتصال به سایت بردارید و اسکریپت را یک بار در صفحه بگذارید:

<script src="https://pixevel.chat/widget.js" data-key="pk_…" async></script>
<button type="button" data-pixevel-chat-open>
  <span>گفت‌وگو با پشتیبانی</span>
</button>

ویژگی data-pixevel-chat-open روی هر عنصر صفحه کار می‌کند؛ کلیک روی فرزندش هم پنل را باز می‌کند. دکمه‌هایی که بعداً به صفحه اضافه می‌شوند هم کار می‌کنند. این رفتار پس از آماده‌شدن برنامه ویجت فعال می‌شود؛ کلیک زودتر از آن ذخیره نمی‌شود. رفتار پیش‌فرض لینک‌ها تغییر نمی‌کند. برای کنترل با JavaScript، پس از اجراشدن اسکریپت از window.PixevelChat استفاده کنید.

کنترل پنل

PixevelChat.open();
PixevelChat.close();
PixevelChat.toggle();

toggle() پنل بسته را باز و پنل باز را می‌بندد. open() و close() تکراری رویداد تازه‌ای نمی‌فرستند. این دستورها پیش از آماده‌شدن برنامه هم کار می‌کنند؛ آخرین حالت خواسته‌شده اعمال می‌شود. روی مسیرهایی که کسب‌وکار ویجت را مخفی کرده یا پس از hide()، پنل باز نمی‌شود.

برای استفاده از دکمه خودتان و حذف دکمه شناور، data-hide-launcher="true" را روی اسکریپت بگذارید. hide() کل ویجت را پنهان و show() آن را دوباره نمایان می‌کند. با setOffset(84) فاصله از پایین را برای هر عرض صفحه تنظیم کنید؛ setOffset(null) به تنظیمات کسب‌وکار برمی‌گردد. مقدار فاصله باید بین صفر و ۱۶۰ پیکسل باشد.

تغییر موقت ظاهر

PixevelChat.setTheme({ primary: "#123456", colorScheme: "dark", radius: 16 });
PixevelChat.setTheme({ motion: 0 });

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

آماده کردن متن پیام

PixevelChat.prefill("سلام، درباره سفارش خودم پرسشی دارم.");
PixevelChat.open();

prefill(text) متن کادر پیام یا بدنه فرم تیکت را جایگزین می‌کند و پیام را نمی‌فرستد. بازدیدکننده می‌تواند آن را تغییر دهد و خودش ارسال کند. رشته خالی کادر را پاک می‌کند؛ مقدار غیررشته‌ای نادیده گرفته می‌شود و متن به ۵۰۰۰ نویسه محدود است. پنل بسته هم متن را برای نمایش بعدی می‌گیرد.

رویدادها و لغو اشتراک

const onMessage = ({ text, author, at }) => {
  console.log(text, author, at);
};
PixevelChat.on("message", onMessage);
const unsubscribe = PixevelChat.on("open", () => console.log("باز شد"));
PixevelChat.on("close", () => console.log("بسته شد"));

PixevelChat.off("message", onMessage);
unsubscribe();

• open و close: تغییر واقعی حالت پنل، بدون بدنه رویداد؛ کلیک و API هر دو آن‌ها را می‌فرستند.
• message: پیام تازه تأییدشده در گفت‌وگوی فعال، شامل پیام خود بازدیدکننده و پاسخ پشتیبانی. بازکردن تاریخچه، ویرایش پیام و قطعه‌های در حال نوشتن دوباره رویداد پیام نمی‌فرستند. بدنه فقط { text, author, at } دارد: author یکی از visitor, staff, bot, system و at زمان ISO است. شناسه داخلی، اطلاعات کارکنان و فایل‌ها در آن نیستند.
• unread: تعداد پاسخ‌های خوانده‌نشده؛ signin: شیء { returnUrl } هنگام درخواست ورود.

on(event, fn) تابع لغو اشتراک برمی‌گرداند. off(event, fn) همان تابع را حذف می‌کند؛ ثبت دوباره همان تابع برای همان رویداد اشتراک دوم نمی‌سازد. خطای یک شنونده مانع اجرای شنونده‌های دیگر نمی‌شود. دستورهای رویداد، setTheme و prefill پیش از آماده‌شدن برنامه به ترتیب صف می‌شوند؛ خود کلیک روی ویژگی HTML صف نمی‌شود. این API فقط پس از اجراشدن اسکریپت موجود است؛ چون اسکریپت async است، کد وابسته را در رویداد load آن اجرا کنید.

این API مرورگر کلید خصوصی نمی‌خواهد. برای گفت‌وگوهای مشتری روی سرور خودتان از API تیکت‌ها و برای رویدادهای سرور از وب‌هوک‌ها استفاده کنید.