داده متغیر

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

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

افزودن داده متغیر از پنل ایلاچت

1. وارد پنل ایلاچت شوید و چت‌بات موردنظر را انتخاب کنید.
2. از منوی «پایگاه دانش» وارد بخش داده‌ها شوید.
3. روی «افزودن داده» بزنید.
4. گزینه «داده متغیر» را انتخاب کنید.
5. نام، عبارت فعال‌سازی، متغیرها و تنظیمات API را وارد کنید.
6. اتصال را با مقدارهای آزمایشی بررسی و سپس ذخیره کنید.

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

کاربردهای رایج

پیگیری سفارش ووکامرس

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

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

تنظیمات اصلی

نام داده

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

پیگیری سفارش

عبارت فعال‌سازی

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

نمونه مناسب:

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

نمونه نامناسب:

سفارش

عبارت دقیق باعث می‌شود API فقط در موقعیت مناسب فراخوانی شود و چت‌بات برای سؤال‌های عمومی، درخواست غیرضروری به سرویس شما نفرستد.

تعریف متغیرها

متغیرها اطلاعاتی هستند که برای اجرای درخواست لازم‌اند؛ مانند شماره سفارش، شماره موبایل، کد ملی یا شناسه کاربر. حداکثر ۵ متغیر برای هر داده متغیر قابل تعریف است.

نمونه متغیر شماره سفارش:

کلید متغیر

کلید برای قراردادن مقدار در URL، هدر یا بدنه درخواست استفاده می‌شود. برای استفاده از متغیر، کلید را داخل {} قرار دهید:

{order_id}

قوانین کلید:

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

نمونه‌های صحیح: order_id، phone_number، customerId و _user_code.

نمونه‌های نادرست: order-id، order id، 123order و شماره_سفارش.

نام، نوع و توضیحات متغیر

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

شماره سفارش ثبت‌شده توسط کاربر که ممکن است به‌صورت عدد یا همراه با عبارت شماره سفارش بیان شود.

دو نوع متغیر پشتیبانی می‌شود:

برای شماره موبایل، کد ملی و شماره سفارش معمولاً string مناسب‌تر است؛ چون ممکن است با صفر شروع شوند.

اجباری‌بودن، پرسش از کاربر و مقدار پیش‌فرض

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

گزینه «از کاربر پرسیده نشود» زمانی مناسب است که مقدار پیش‌تر در مکالمه دریافت شده باشد، در شرایط خاصی قابل استخراج باشد یا نبودن آن مانع اجرای API نباشد. اگر متغیر در URL یا بخش ضروری درخواست استفاده می‌شود، این گزینه را فعال نکنید.

مقدار پیش‌فرض برای تست و زمانی استفاده می‌شود که مقدار متغیر وارد نشده باشد. برای اجرای قابل‌اطمینان در مکالمه، متغیرهایی را که API حتماً به آن‌ها نیاز دارد اجباری کنید.

آدرس و روش درخواست API

آدرس API باید با http:// یا https:// شروع شود. متغیرها هنگام اجرا با مقدار واقعی جایگزین می‌شوند.

https://api.example.com/orders/{order_id}

نمونه استفاده از Query String:

https://api.example.com/orders?order_id={order_id}&phone={phone_number}

مقدار متغیرها خودکار URL Encode نمی‌شوند. API و مقدار ورودی را طوری طراحی کنید که URL نهایی معتبر باقی بماند.

دو متد درخواست پشتیبانی می‌شود:

اگر از بدنه درخواست استفاده می‌کنید، POST را انتخاب کنید.

هدرهای درخواست

در هدر می‌توانید مقادیر موردنیاز API را وارد کنید. اطلاعات حساس مانند API Key یا توکن سرویس را در هدر نگه دارید، نه در پاسخ API.

بدنه درخواست

بدنه به‌صورت JSON و از ترکیب کلیدها و مقادیر تعریف‌شده ساخته می‌شود:

{
  "order_id": "{order_id}",
  "phone": "{phone_number}",
  "source": "ilachat"
}

متغیرها می‌توانند بخشی از یک مقدار نیز باشند:

{
  "tracking_text": "پیگیری سفارش {order_id}"
}

مقادیر بدنه به‌صورت رشته ارسال می‌شوند، حتی اگر نوع متغیر number باشد.

پاسخ API

پاسخ API ساختار اجباری خاصی ندارد و می‌تواند JSON یا متن ساده باشد. چت‌بات محتوای پاسخ را می‌خواند و بر اساس آن به کاربر جواب می‌دهد.

برای نتیجه قابل‌اعتماد:

• HTTP Status موفق 200 برگردانید.
• پاسخ را با UTF-8 و کمتر از ۵۰ هزار کاراکتر ارسال کنید.
• فقط اطلاعات لازم برای پاسخ‌گویی به کاربر را برگردانید.
• از HTML، فایل، خطاهای فنی و اطلاعات اضافی خودداری کنید.

نمونه پاسخ JSON:

{
  "found": true,
  "order_id": "45821",
  "status": "ارسال شده",
  "tracking_code": "1234567890",
  "delivery_date": "1405/06/10"
}

نمونه پاسخ متنی:

سفارش 45821 ارسال شده است. کد رهگیری: 1234567890

برای داده متغیر، وجود ساختار status: success الزامی نیست. پاسخ مستقیم و ساده معمولاً نتیجه واضح‌تری ایجاد می‌کند، اما اگر API شما از ساختار status و data استفاده می‌کند همان ساختار نیز قابل استفاده است.

پیدا نشدن اطلاعات و خطا

وقتی نتیجه پیدا نشد، پیام روشن و قابل‌فهم برگردانید:

{
  "found": false,
  "message": "سفارشی با این شماره پیدا نشد."
}

برای خطای موقت سرویس نیز پیام کوتاه و قابل‌فهم برگردانید و از نمایش Query دیتابیس، Stack Trace یا اطلاعات امنیتی خودداری کنید:

{
  "error": true,
  "message": "در حال حاضر امکان دریافت وضعیت سفارش وجود ندارد."
}

نمونه کامل پیگیری سفارش

در این نمونه، کاربر شماره سفارش و شماره همراه را وارد می‌کند و API نتیجه را در قالب JSON برمی‌گرداند.

آدرس API:

https://api.example.com/orders/track

روش: POST

هدرها:

Content-Type: application/json
Accept: application/json
Authorization: Bearer YOUR_API_TOKEN

بدنه درخواست:

{
  "order_id": "{order_id}",
  "phone": "{phone_number}"
}

نمونه پاسخ:

{
  "found": true,
  "status": "در حال ارسال",
  "estimated_delivery": "1405/06/10"
}

تست اتصال

پیش از ذخیره یا فعال‌سازی نهایی، از گزینه «تست داده متغیر» استفاده کنید:

1. برای متغیرها مقدار آزمایشی وارد کنید.
2. روی «اجرای تست» بزنید.
3. HTTP Status و متن پاسخ را بررسی کنید.
4. مطمئن شوید تمام متغیرها درست جایگزین شده‌اند.
5. بررسی کنید پاسخ اطلاعات روشن و قابل‌استفاده برمی‌گرداند.

در محیط تست، آدرس‌های شبکه داخلی و localhost قابل استفاده نیستند. آدرس باید عمومی، با HTTP یا HTTPS و روی پورت استاندارد 80 یا 443 در دسترس باشد. Redirect دنبال نمی‌شود، زمان اجرای تست حداکثر ۳۰ ثانیه است و حداکثر ۵۰ هزار کاراکتر از پاسخ نمایش داده می‌شود. IP ارسال‌کننده تست نیز ممکن است با IP اجرای اصلی متفاوت باشد.

نکات نهایی

• عبارت فعال‌سازی را دقیق و محدود بنویسید.
• برای اطلاعات ضروری، گزینه «اجباری باشد» را فعال کنید.
• شماره موبایل، کد ملی و شناسه‌ها را از نوع string تعریف کنید.
• متغیرها را با قالب {variable_key} استفاده کنید.
• برای ارسال بدنه JSON از POST استفاده کنید.
• پاسخ API را کوتاه، واضح و بدون اطلاعات غیرضروری نگه دارید.
• اطلاعات محرمانه مانند توکن را در هدر درخواست قرار دهید و پیش از فعال‌سازی اتصال را با مقدارهای واقعی آزمایش کنید.