AIVA Chatbot Widget API

Introduction

پس از بارگذاری فایل Widget یک شیء Global روی window ایجاد می‌شود که تمام متدهای کنترل Widget را در اختیار شما قرار می‌دهد.

window.AivaChatbotWidget

Installation

برای نصب Widget فقط کافی است اسکریپت زیر را قبل از بسته شدن تگ body قرار دهید.

<script src="https://your-domain.com/api/public/widget/chatbot-widget.js?apiEndpoint=https://your-domain.com/api/public&botUUID=YOUR_BOT_UUID"></script>

Quick Start

پس از بارگذاری Widget شیء زیر در مرورگر در دسترس خواهد بود.

window.AivaChatbotWidget

Available Methods

open()

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

window.AivaChatbotWidget.open();

close()

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

window.AivaChatbotWidget.close();

toggle()

وضعیت Widget را تغییر می‌دهد.

window.AivaChatbotWidget.toggle();

Control Widget With HTML Buttons

نمونه کنترل Widget با استفاده از دکمه‌های HTML.

<button id="openBtn">Open</button>
<button id="closeBtn">Close</button>
<button id="toggleBtn">Toggle</button>
<script>
document.getElementById("openBtn")
.addEventListener("click",()=>{
window.AivaChatbotWidget.open();
});
document.getElementById("closeBtn")
.addEventListener("click",()=>{
window.AivaChatbotWidget.close();
});
document.getElementById("toggleBtn")
.addEventListener("click",()=>{
window.AivaChatbotWidget.toggle();
});
</script>

updateConfig()

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

window.AivaChatbotWidget.updateConfig({
    primaryColor:"#2f80ed",
    accentColor:"#1e40af",
    botName:"پشتیبانی آنلاین",
    widgetPosition:"bottom_left"
});

جایگاه ویجت (Widget Placement)

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

چپ / راست

مقدار widgetPosition را روی "bottom_left" یا "bottom_right" قرار دهید. این کار را می‌توانید از پنل تنظیمات ربات هم انجام دهید.

window.AivaChatbotWidget.updateConfig({
  widgetPosition: "bottom_left" // یا "bottom_right"
});

بالاتر / پایین‌تر (فاصله از پایین صفحه)

فاصله پیش‌فرض ویجت از پایین صفحه 20px است. برای تغییر ارتفاع، در سایت خود CSS زیر را اضافه کنید و مقدار bottom را تغییر دهید. عدد بزرگ‌تر = ویجت بالاتر. برای جلوگیری از تداخل با استایل‌های سایت، سلکتور را با #aiva-chatbot-root محدود کنید.

<style>
  #aiva-chatbot-root .chatbot-container {
    bottom: 80px !important; /* مثلاً 60px، 80px یا 100px */
  }
</style>

نمونه کامل

<!-- سمت راست و کمی بالاتر از حالت پیش‌فرض -->
<style>
  #aiva-chatbot-root .chatbot-container {
    bottom: 80px !important;
  }
</style>
<script>
  window.AivaChatbotWidget.updateConfig({
    widgetPosition: "bottom_right"
  });
</script>

destroy()

Widget را به طور کامل از صفحه حذف می‌کند و تمام Event Listenerها نیز آزاد می‌شوند.

window.AivaChatbotWidget.destroy();

مدیریت هویت کاربر (User Identity)

به‌صورت پیش‌فرض، Widget برای هر مرورگر یا دستگاه یک شناسه یکتا (User ID) به‌شکل ناشناس (Anonymous) می‌سازد و هویت کاربر را بر اساس همان مرورگر تشخیص می‌دهد. با کمک متدهای زیر می‌توانید کاربری که در وب‌سایت شما لاگین کرده است را به AIVA معرفی کنید تا:

• اطلاعات کاربر (نام، ایمیل، موبایل) در بخش مشخصات هر گفتگو نمایش داده شود.
• تاریخچه گفتگوی کاربر در هر مرورگر و دستگاهی یکپارچه حفظ شود و از ایجاد گفتگوی تکراری برای یک کاربر جلوگیری شود.

هر متد به‌صورت اختیاری یک تابع callback می‌پذیرد که نتیجه را به این شکل بازمی‌گرداند:

{
  success: true,          // موفق یا ناموفق بودن عملیات
  userId: "crm_1001",     // شناسه فعلی کاربر
  error: undefined        // در صورت خطا، متن خطا
}

setUser()

با استفاده از این متد می‌توانید اطلاعات کاربری که در وب‌سایت شما لاگین کرده است را به AIVA بفرستید تا در بخش مشخصات کاربر برای هر گفتگو نمایش داده شده و به آن‌ها دسترسی داشته باشید. رفتار این متد Upsert است؛ یعنی فقط فیلدهایی که ارسال می‌کنید به‌روزرسانی می‌شوند و بقیه فیلدها بدون تغییر باقی می‌مانند.

window.AivaChatbotWidget.setUser(
  {
    name: "علی رضایی",
    email: "ali@example.com",
    phone: "09121234567"
  },
  function (result) {
    console.log(result.success, result.error);
  }
);

getUser()

با فراخوانی این متد می‌توانید اطلاعات فعلی کاربر ذخیره‌شده در Widget را دریافت و در صورت نیاز در سایت خود ذخیره و استفاده نمایید. این متد یک شیء شامل اطلاعات کاربر بازمی‌گرداند.

const user = window.AivaChatbotWidget.getUser();

console.log(user);
// { name: "علی رضایی", email: "ali@example.com", phone: "09121234567" }

getUserId()

اگر نیاز دارید گفتگوهای یک کاربر را حتی با مرورگر یا دستگاه‌های مختلف، به‌صورت یکپارچه داشته باشید، ابتدا با استفاده از این متد شناسه یکتای کاربر (User ID) در AIVA را دریافت و در پایگاه داده سایت خود ذخیره کنید، سپس با کمک متد setUserId در زمان لازم می‌توانید آن را فراخوانی و اعمال کنید.

const userId = window.AivaChatbotWidget.getUserId();

// این شناسه را کنار رکورد کاربر لاگین‌کرده در دیتابیس خود ذخیره کنید
console.log(userId);

setUserId()

به‌طور کلی AIVA برای کاربر در هر مرورگر یا دستگاه، شناسه (ID) مجزایی ایجاد می‌کند و سنجش هویت کاربر را بر اساس مرورگری که در آن ابزارک گفتگو نمایش داده شده است انجام می‌دهد. در صورت داشتن شناسه یکتای کاربر در AIVA و اعمال این متد، مخاطب شما می‌تواند در هر مرورگر یا دستگاه، ادامه گفتگوی قبلی خود را با شما داشته باشد و از ایجاد گفتگوی جدید برای آن شخص جلوگیری شود.

window.AivaChatbotWidget.setUserId(
  "crm_1001",
  function (result) {
    if (result.success) {
      console.log("هویت کاربر اعمال شد:", result.userId);
    } else {
      console.error("خطا:", result.error);
    }
  }
);

unsetUserId()

در صورت اجرای این متد، شناسه فعلی کاربر از مرورگر حذف و سوابق پیام‌های کاربر نیز در ابزارک قابل نمایش نخواهد بود. پس از آن، Widget مجدداً کاربر را به‌عنوان یک کاربر ناشناس (Anonymous) مدیریت کرده و شناسه داخلی جدیدی برای او ایجاد می‌کند. معمولاً این متد را هنگام خروج کاربر از حساب کاربری (Logout) فراخوانی می‌کنید.

window.AivaChatbotWidget.unsetUserId(function (result) {
  console.log("کاربر ناشناس شد:", result.userId);
});

Full Identity Flow

نمونه کامل استفاده از متدهای هویت کاربر: هنگام لاگین کاربر در سایت، هویت او را به AIVA معرفی می‌کنیم و هنگام خروج آن را پاک می‌کنیم.

// هنگام لاگین کاربر در سایت شما
function onUserLogin(user) {
  // اگر قبلاً شناسه AIVA این کاربر را ذخیره کرده‌اید، همان را اعمال کنید
  if (user.aivaUserId) {
    window.AivaChatbotWidget.setUserId(user.aivaUserId);
  }

  // ارسال اطلاعات کاربر برای نمایش در پنل
  window.AivaChatbotWidget.setUser({
    name: user.fullName,
    email: user.email,
    phone: user.phone
  });
}

// هنگام خروج کاربر (Logout)
function onUserLogout() {
  window.AivaChatbotWidget.unsetUserId();
}

Example

نمونه استفاده از Widget

<button id="chat">
Open Chat
</button>
<script>
document.getElementById("chat")
.addEventListener("click",()=>{
if(
window.AivaChatbotWidget &&
typeof window.AivaChatbotWidget.open==="function"
){
window.AivaChatbotWidget.open();
}
});
</script>

Frequently Asked Questions