API پیام‌رسان در مرورگر

پیام‌رسان با همان یک خط کد کار می‌کند؛ این‌ها برای وقتی است که سایتتان بخواهد با آن حرف بزند: از دکمهٔ خودتان بازش کنید، کاربر واردشده را معرفی کنید، یا بدانید کِی پیام نخوانده دارد.

ویژگی‌های تگ

<script src="https://goya24.com/widget.js"
  data-key="d24_pk_..."
  data-locale="fa"
  data-alignment="right"
  data-horizontal-padding="24"
  data-vertical-padding="24"
  defer></script>

• data-key — کلید عمومی فضای کاری، از «تنظیمات → نصب».
• data-locale — زبان رابط پیام‌رسان: fa یا en. بدون آن، از lang صفحه خوانده می‌شود.
• data-alignment — left یا right. بدون آن، همان گوشه‌ای که در «تنظیمات → پیام‌رسان» انتخاب کرده‌اید. فاصله از لبه‌ها با data-horizontal-padding و data-vertical-padding به پیکسل، دست‌کم ۲۰. بدون data-vertical-padding، فاصله از پایین همانی است که در «تنظیمات → پیام‌رسان» گذاشته‌اید، جدا برای دسکتاپ و موبایل. اگر پایین سایتتان منوی ثابتی هست، ساده‌ترین راه همین تنظیم است.
• data-launcher — با مقدار none حباب پیش‌فرض برداشته می‌شود؛ برای سایتی که دکمهٔ خودش را دارد و پنل را با window.goya24.open() باز می‌کند. آن‌وقت پیام‌رسان بسته هیچ جایی از صفحه نمی‌گیرد و زیر پنل باز هم حبابی نیست؛ بقیهٔ پیام‌رسان همان است که بود.
• data-suggestions — پرسش‌های پیشنهادی صفحهٔ اول پیام‌رسان. با مقدار none هیچ پرسشی نمایش داده نمی‌شود. با یک آرایهٔ JSON، پرسش‌های خودتان جای فهرست «تنظیمات → پیام‌رسان» می‌نشیند. بخش «پرسش‌های پیشنهادی از طرف سایت» را ببینید.
• data-user — کاربر واردشده به‌شکل JSON: id، hash، email، name، phone، plan. با id و hash (امضای سرور شما) هویت اثبات‌شده حساب می‌شود؛ بدون آن‌ها فقط یک ادعاست.

جا و حباب، بعد از لود

پیام‌رسان یک بار لود می‌شود و در سایت تک‌صفحه‌ای همراه کاربر از صفحه‌ای به صفحهٔ دیگر می‌رود. با update() هر وقت خواستید جایش را عوض کنید یا حباب را بردارید و برگردانید. پیام‌رسان دوباره لود نمی‌شود و گفت‌وگوی باز سر جایش می‌ماند.

// در صفحهٔ اپ حباب نباشد، در بقیهٔ صفحه‌ها باشد
window.goya24.update({ launcher: false });
window.goya24.update({ launcher: true });

// در یک صفحه سمت چپ، بالاتر از نوار سبد خرید
window.goya24.update({ alignment: "left", padding: { y: 96 } });

// بر اساس دستگاه
const phone = window.matchMedia("(max-width: 640px)");
const place = () => window.goya24.update({ padding: { y: phone.matches ? 88 : 20 } });
phone.addEventListener("change", place);
place();

// برگشت به تنظیمات پنل
window.goya24.update({ alignment: null, padding: null });

• launcher — true یا false، مثل data-launcher.
• alignment — left یا right.
• padding — { x, y } به پیکسل، دست‌کم ۲۰.
• suggestions — آرایه‌ای از پرسش‌ها، یا false برای هیچ پرسشی. مثل data-suggestions.
• کلیدی که نفرستید همان که بود می‌ماند. null یعنی برگشت به «تنظیمات → پیام‌رسان»، و اگر آنجا چیزی انتخاب نشده، به پیش‌فرض: پایین، سمت راست.
• قبل از آماده شدن پیام‌رسان هم می‌شود صدایش زد؛ پیام‌رسان از اول با همان جا بالا می‌آید.

پرسش‌های پیشنهادی از طرف سایت

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

<!-- بدون پرسش پیشنهادی -->
<script src="https://goya24.com/widget.js" data-key="d24_pk_..."
  data-suggestions="none" defer></script>

<!-- پرسش‌های خود سایت -->
<script src="https://goya24.com/widget.js" data-key="d24_pk_..."
  data-suggestions='["ارسال به شهرستان چند روز طول می‌کشد؟", "گارانتی دارد؟"]' defer></script>

در سایت تک‌صفحه‌ای، پرسش‌ها را با هر صفحه عوض کنید. پیام‌رسان دوباره لود نمی‌شود و اگر صفحهٔ اولش باز باشد، فهرست همان لحظه عوض می‌شود.

// هر جا router سایتتان عوض شدن صفحه را خبر می‌دهد
function suggestionsFor(path) {
  if (path.startsWith("/product/piano")) {
    return ["پیانو کوک‌شده تحویل داده می‌شود؟", "قسطی هم می‌شود خرید؟"];
  }
  if (path.startsWith("/checkout")) return false; // در صفحهٔ پرداخت پرسشی نباشد
  return null; // بقیهٔ صفحه‌ها: همان فهرست پنل
}

onRouteChange((path) => {
  window.goya24.update({ suggestions: suggestionsFor(path) });
});

• پرسش‌های سایت جای فهرست پنل می‌نشینند و به آن اضافه نمی‌شوند.
• اگر پرسش‌ها را در «تنظیمات → پیام‌رسان» خاموش کرده باشید، پرسش‌هایی که سایت می‌فرستد باز هم نمایش داده می‌شوند.
• حداکثر چهار پرسش، هر کدام حداکثر ۸۰ نویسه. پرسش خالی، تکراری یا بلندتر کنار گذاشته می‌شود و کنسول مرورگر دلیلش را می‌گوید.
• پرسش‌ها فقط در صفحهٔ اول پیام‌رسان نمایش داده می‌شوند، نه وسط گفت‌وگو.

دکمه‌ای که گفت‌وگو را با یک جمله شروع می‌کند

هر دکمه یا لینکی در سایت می‌تواند گویا را باز کند و یک جملهٔ آماده را از طرف کاربر بفرستد. مثلاً دکمهٔ «گفت‌وگو با یک متخصص موسیقی» در صفحهٔ پیانو. کاربر روی آن می‌زند، پیام‌رسان باز می‌شود، همین جمله فرستاده می‌شود و دستیار بر اساس مهارت‌هایش جواب می‌دهد. برای این کار کدنویسی لازم نیست. کافی است به دکمه یک ویژگی بدهید:

<a href="#" data-goya24-message="گفت‌وگو با یک متخصص موسیقی">
  گفت‌وگو با یک متخصص موسیقی
</a>

<!-- در همان گفت‌وگوی قبلی کاربر، نه یک گفت‌وگوی تازه -->
<button data-goya24-message="سفارشم کجاست؟" data-goya24-new-conversation="false">
  پیگیری سفارش
</button>

یا از کد خودتان:

window.goya24.open({ message: "گفت‌وگو با یک متخصص موسیقی" });

// در گفت‌وگوی فعلی کاربر
window.goya24.open({ message: "سفارشم کجاست؟", newConversation: false });

• هر کلیک یک گفت‌وگوی تازه شروع می‌کند، چون هر دکمه موضوع خودش را دارد. گفت‌وگوی قبلی کاربر در فهرست گفت‌وگوهایش می‌ماند. اگر می‌خواهید جمله به همان گفت‌وگوی قبلی برود، data-goya24-new-conversation="false" (یا newConversation: false) بگذارید.
• اگر در «تنظیمات → پیام‌رسان» خواسته‌اید کاربر اول نام و موبایلش را بدهد، فرم همان‌جا باز می‌شود و جمله بعد از پر کردن فرم خودش فرستاده می‌شود.
• دکمه‌ای که بعداً به صفحه اضافه شود (مثلاً با صفحه‌ساز) هم همین‌طور کار می‌کند.
• اگر کاربر قبل از بالا آمدن پیام‌رسان روی دکمه بزند، جمله نگه داشته می‌شود و همین که پیام‌رسان آماده شد فرستاده می‌شود.
• جمله حداکثر ۲۰۰۰ نویسه است.

متدها

window.goya24.open();      // باز کردن پنل از دکمهٔ خودتان
window.goya24.open({ message: "سلام" });  // باز کردن و فرستادن یک جمله، بخش بالا
window.goya24.close();
window.goya24.toggle();
window.goya24.update({ launcher: false });  // بخش بالا
window.goya24.identify({ name: "سارا", phone: "09123456789" });  // ادعا؛ هویت امضاشده با data-user
window.goya24.getState();  // { open, unread, ready }
window.goya24.destroy();   // برداشتن کامل، برای اپ‌های تک‌صفحه‌ای

رویدادها

// دکمهٔ باز و بستهٔ خودتان را با همین رویدادها جابه‌جا کنید
window.goya24.on("open", () => { openBtn.hidden = true; closeBtn.hidden = false; });
window.goya24.on("close", () => { openBtn.hidden = false; closeBtn.hidden = true; });

const off = window.goya24.on("unread", (count) => {
  document.title = count ? `(${count}) پشتیبانی` : "پشتیبانی";
});
// ready · open · close · unread · error
off(); // یا window.goya24.off("unread", handler)