اتصال چت‌بات به نرم‌افزارهای خودتان با «ابزار شخصی» (API)
با «ابزار شخصی» آیوا، چت‌بات را به API نرم‌افزارهای خودتان وصل کنید تا وضعیت سفارش، موجودی انبار یا ثبت درخواست را زنده جواب بدهد؛ با نمونه کامل و نکات امنیتی.
مهم‌ترین اطلاعات هر کسب‌وکار معمولاً در نرم‌افزارهای خودش است: نرم‌افزار حسابداری، سامانه انبار، پنل پیگیری سفارش یا سامانه‌ای که برنامه‌نویس شرکت ساخته است. چت‌باتی که فقط از روی فایل‌ها آموزش دیده، نمی‌تواند بگوید سفارش شماره ۵۸۲۱ ارسال شده یا نه، چون جواب این سؤال هر ساعت عوض می‌شود.
«ابزار شخصی» آیوا برای همین ساخته شده است. شما یک درخواست HTTP به API نرم‌افزار خودتان تعریف می‌کنید و توضیح می‌دهید چه زمانی به کار می‌آید. از آن به بعد، دستیار خودش تصمیم می‌گیرد کی از ابزار استفاده کند، مقدارهای لازم را از گفتگو برمی‌دارد، درخواست را می‌فرستد و از روی نتیجه به مشتری جواب می‌دهد.
این راهنما برای صاحبان کسب‌وکار و برنامه‌نویس‌هایشان نوشته شده است؛ اگر با API آشنا نیستید، آن را همراه برنامه‌نویس خود مرور کنید. «ابزار شخصی» از پلن آیوا هوشمند به بالا در دسترس است.
ابزار شخصی چطور کار می‌کند؟
فرض کنید به همکار تازه‌واردی شماره داخلی انبار را داده‌اید و گفته‌اید: «هر وقت کسی موجودی پرسید، از انبار بپرس.» ابزار شخصی همان شماره داخلی است و توضیح ابزار همان جمله راهنما. مسیر یک سؤال این‌طور است:
- مشتری می‌پرسد: «سفارش ۵۸۲۱ من کجاست؟»
- دستیار می‌بیند ابزاری با توضیح «پیگیری وضعیت سفارش» دارد و شماره سفارش را از پیام مشتری برمی‌دارد.
- آیوا درخواست را به API شما می‌فرستد.
- API جواب را، ترجیحاً به شکل JSON، برمی‌گرداند.
- دستیار از روی همین جواب، با زبان طبیعی به مشتری پاسخ می‌دهد.
ابزارهایی که تعریف می‌کنید، در همه کانال‌های همان دستیار در دسترس‌اند: ویجت سایت، بله، گفتینو و باسلام. اگر با مفهوم ایجنت‌ها آشنا هستید، ابزار شخصی همان چیزی است که دستیار را از «جواب دادن» به «انجام دادن کار» نزدیک می‌کند؛ این مفهوم را در از چت‌بات تا ایجنت به زبان ساده توضیح داده‌ایم.
با ابزار شخصی چه کارهایی می‌شود کرد؟
- پیگیری سفارش از سامانه خودتان: وقتی سفارش‌ها در نرم‌افزاری غیر از ووکامرس ثبت می‌شوند.
- بررسی موجودی در نرم‌افزار انبار: «از این مدل در شعبه مرکزی موجود است؟»
- ثبت درخواست: مثل درخواست تماس، درخواست گارانتی یا ثبت شکایت در سامانه شما.
- استعلام‌های کوتاه: مثل وضعیت یک درخواست پشتیبانی با کد پیگیری.
اگر فروشگاهتان روی ووکامرس است، لازم نیست این ابزارها را خودتان بسازید؛ آیوا اتصال آماده ووکامرس را دارد، آن هم در پلن آیوا هوشمند، که در چت‌بات هوشمند ووکامرس معرفی کرده‌ایم.
پیش‌نیازها
- پلن آیوا هوشمند یا آیوا ژرف؛ در پلن‌های پایین‌تر، فرم کارت API غیرفعال است و عبارت «در پلن آیوا هوشمند فعال است» را می‌بینید.
- یک API که از طریق اینترنت و با نشانی
http://یاhttps://در دسترس باشد. به دلایل امنیتی، ابزارها نمی‌توانند به نشانی‌های داخلی مثل localhost یا نشانی‌های شبکه خصوصی وصل شوند. - کلید دسترسی API، اگر نرم‌افزارتان آن را لازم دارد.
- جواب سریع؛ آیوا حدود ۲۰ ثانیه منتظر جواب API می‌ماند.
ساخت ابزار، فیلد به فیلد
در مرحله ششم ساخت دستیار («یکپارچه‌سازی»)، کارت «API» با توضیح «اتصال به APIهای دیگر» را انتخاب کنید. بخش «ابزار شخصی» این فیلدها را دارد:
| فیلد | چه چیزی وارد کنید |
|---|---|
| «نام ابزار» | فقط حروف کوچک انگلیسی، عدد و زیرخط، بدون فاصله و شروع‌شده با حرف؛ در هر دستیار یکتا، مثل get_order_status |
| «توضیحات» | ابزار چه می‌کند و دستیار کی باید از آن استفاده کند |
| «متد» | GET برای خواندن، POST و PUT برای فرستادن و تغییر، DELETE برای حذف |
| «آدرس وب» | نشانی کامل، با پارامترها داخل آکولاد، مثل https://api.example.com/orders/{order_id} |
| «هدر» | جفت‌های کلید و مقدار، مثل کلید دسترسی API |
| «Body» | جفت‌های کلید و مقدار که در POST، PUT و DELETE به شکل JSON فرستاده می‌شوند |
| «پارامتر» | برای هر پارامتر نام، نوع و توضیح |
چند نکته درباره این فیلدها:
- توضیحات مهم‌ترین فیلد است. دستیار فقط از روی همین متن تصمیم می‌گیرد کی از ابزار استفاده کند. روشن بنویسید ابزار چه برمی‌گرداند و در چه موقعیتی باید به کار برود.
- هر پارامتر توضیح لازم دارد. قالب و نمونه را بنویسید؛ مثلاً «شماره موبایل مشتری با قالب
09xxxxxxxxx». نوع پارامتر می‌تواندstring،number،boolean،objectیاarrayباشد. - پارامترهایی که در آدرس جایی ندارند، در درخواست
GETبه شکل پارامتر نشانی (query string) و درPOST،PUTوDELETEداخل بدنه JSON فرستاده می‌شوند. - هدرها رمزنگاری‌شده ذخیره می‌شوند. کلید دسترسی را در هدر بگذارید، نه داخل آدرس.
در پایان «افزودن ابزار» را بزنید.
نمونه کامل: پیگیری سفارش از سامانه خودتان
فرض کنید «فروشگاه نمونه» سفارش‌هایش را در سامانه‌ای اختصاصی ثبت می‌کند و برنامه‌نویسش یک API ساده برای خواندن وضعیت سفارش ساخته است. ابزار را این‌طور تعریف می‌کنیم:
- نام ابزار:
get_order_status - توضیحات: «وضعیت یک سفارش را برمی‌گرداند. وقتی مشتری وضعیت یا زمان رسیدن سفارشش را می‌پرسد، بعد از گرفتن شماره سفارش و شماره موبایل خریدار، از این ابزار استفاده کن.»
- متد:
GET - آدرس وب:
https://api.example.com/orders/{order_id} - هدر: کلید
Authorizationبا مقدارBearer YOUR-API-KEY - پارامترها:
order_idبا توضیح «شماره سفارشی که مشتری اعلام می‌کند» وmobileبا توضیح «شماره موبایل خریدار با قالب09xxxxxxxxx»
با این تعریف، وقتی مشتری شماره سفارش ۵۸۲۱ و موبایلش را بدهد، آیوا درخواستی مثل https://api.example.com/orders/5821?mobile=09120000000 می‌فرستد. API شما باید پیش از جواب دادن بررسی کند که موبایل با سفارش می‌خواند؛ این‌طور کسی با حدس زدن شماره سفارش، خرید دیگران را نمی‌بیند.
گفتگوی زیر نمونه‌ای ساختگی از نتیجه است:
- مشتری: سلام، سفارشم کی می‌رسد؟
- دستیار: لطفاً شماره سفارش و شماره موبایلی را که با آن خرید کرده‌اید بفرمایید.
- مشتری: سفارش ۵۸۲۱، موبایل ۰۹۱۲۰۰۰۰۰۰۰
- دستیار: سفارش ۵۸۲۱ شما امروز صبح به پست تحویل داده شده است و طبق اطلاعات سامانه، معمولاً طی دو تا سه روز کاری به دستتان می‌رسد.
آزمایش، فعال‌سازی و ویرایش
بعد از «افزودن ابزار»، ابزار در فهرست «ابزارهای تعریف شده» نمایش داده می‌شود. روی کارت هر ابزار این گزینه‌ها را دارید:
- تست ابزار: برای پارامترها مقدار نمونه وارد کنید و «اجرای ابزار» را بزنید. کد وضعیت و جوابی که API برگردانده، همان‌جا نمایش داده می‌شود.
- فعال: با این گزینه، ابزار را بدون حذف کردن از دسترس دستیار خارج می‌کنید یا دوباره به کار می‌اندازید.
- ویرایش و حذف.
بعد از تست موفق، در پیش‌نمایش گفتگو با جمله‌هایی که مشتری‌ها واقعاً می‌نویسند امتحان کنید. اگر دستیار از ابزار استفاده نکرد یا پارامتر را اشتباه برداشت، معمولاً راه‌حل روشن‌تر کردن توضیحات ابزار و پارامترهاست.
نکته‌های امنیتی و طراحی API
- کلید جداگانه با کمترین دسترسی بسازید. برای آیوا یک کلید API مخصوص بسازید که فقط به همان داده‌های لازم دسترسی دارد و هر وقت خواستید، بتوانید باطلش کنید.
- با ابزارهای خواندنی شروع کنید. برای ابزارهایی که چیزی را ثبت یا تغییر می‌دهند (
POST،PUT،DELETE)، ورودی‌ها را در سرور خودتان بررسی کنید و دامنه کارشان را محدود نگه دارید؛ یادتان باشد مقدار پارامترها از حرف‌های مشتری می‌آید. - هویت را بررسی کنید. برای هر اطلاعات شخصی، دو مشخصه بخواهید؛ مثل شماره سفارش و موبایل.
- فقط همان‌قدر که لازم است برگردانید. هر چیزی که API برمی‌گرداند، ممکن است در جواب به مشتری بیاید؛ پس نشانی کامل، اطلاعات پرداخت یا داده‌های داخلی را در خروجی نگذارید.
- نشانی نهایی را وارد کنید. آیوا تغییر مسیر (redirect) را دنبال نمی‌کند؛ نشانی‌ای را بدهید که مستقیم جواب می‌دهد.
نکته: اصول کلی‌تر حفاظت از داده‌ها در چت‌بات را در مقاله امنیت و حریم خصوصی در چت‌بات توضیح داده‌ایم؛ پیش از اتصال سامانه‌هایی که اطلاعات شخصی مشتری دارند، آن را بخوانید.
محدودیت‌ها
- دستیار فقط وقتی از ابزار استفاده می‌کند که سؤال مشتری به آن نیاز داشته باشد؛ ابزار شخصی کار زمان‌بندی‌شده یا پس‌زمینه انجام نمی‌دهد.
- آیوا مستقیم به پایگاه داده شما وصل نمی‌شود؛ راه اتصال، API است.
- متدهای قابل استفاده
GET،POST،PUTوDELETEهستند. - اگر جواب API به شکل JSON نباشد، فقط حدود ۲ هزار کاراکتر اول آن خوانده می‌شود.
- ابزارها فقط به نشانی‌های عمومی اینترنت وصل می‌شوند.
سؤالات متداول
بدون برنامه‌نویس هم می‌توانم ابزار شخصی بسازم؟
اگر نرم‌افزارتان API مستند دارد، می‌توانید فرم را خودتان از روی مستندات پر کنید و با «تست ابزار» نتیجه را ببینید. اگر نرم‌افزارتان API ندارد، برنامه‌نویس باید یک نقطه دسترسی ساده بسازد که داده لازم را برگرداند.
ابزار شخصی اعتبار بیشتری مصرف می‌کند؟
اعتبار هر جواب به مقدار متنی بستگی دارد که پردازش و تولید می‌شود. جوابی که از ابزار استفاده می‌کند، نتیجه API را هم پردازش می‌کند؛ پس ممکن است کمی بیشتر مصرف کند. جزئیات را در هزینه هر گفتگو در آیوا چطور حساب می‌شود؟ ببینید.
یک ابزار همه‌کاره بسازم یا چند ابزار جدا؟
برای هر کار مشخص یک ابزار جدا بسازید؛ مثلاً یکی برای وضعیت سفارش و یکی برای موجودی. ابزار کوچک با توضیح روشن، از ابزار همه‌کاره‌ای که توضیحش مبهم است، بهتر کار می‌کند.
جمع‌بندی
ابزار شخصی پلی است میان دستیار آیوا و داده‌هایی که فقط در نرم‌افزارهای خودتان پیدا می‌شوند. با یک API ساده، توضیح روشن و چند نکته امنیتی، دستیار می‌تواند وضعیت سفارش، موجودی یا درخواست‌های مشتری را همان لحظه بررسی کند. مراحل دیگر ساخت دستیار را هم در آموزش ساخت چت‌بات با آیوا ببینید.
برای شروع، ساخت دستیار را رایگان در آیوا شروع کنید؛ پایگاه دانش را در دوره آزمایشی آماده کنید و برای تعریف ابزار شخصی، پلن آیوا هوشمند را فعال کنید.