اتصالات API

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

چگونه کار می‌کند

اتصالات API به شما اجازه می‌دهند enuchat را با سیستم‌های backend خود ادغام کنید — موتورهای رزرو، CRMها، مدیریت سفارش، موجودی و موارد دیگر. وقتی بازدیدکننده‌ای سؤالی می‌پرسد، enuchat می‌تواند API شما را برای دریافت داده‌های واقعی فراخوانی کند و آن‌ها را در پاسخ بگنجاند.

جریان

  1. یک اتصال پیکربندی کنید — URL پایه و احراز هویت API شما
  2. endpointها را اضافه کنید — فراخوانی‌های API خاص با قالب‌های مسیر و نگاشت پاسخ
  3. یک قانون ایجاد کنید — یک قانون هوش مصنوعی یا استاتیک با یک اقدام CALL_API
  4. بازدیدکننده سؤال می‌کند — قانون فعال می‌شود، API شما را فراخوانی می‌کند، پاسخ را به متغیرهای نشست نگاشت می‌کند
  5. هوش مصنوعی با داده‌های واقعی پاسخ می‌دهد — متغیرهای نشست برای هوش مصنوعی برای تولید پاسخ دقیق در دسترس هستند

مثال: در دسترس بودن اتاق هتل

بازدیدکننده: "آیا اتاق ۲۰۵ هفته بعد در دسترس است؟"

قانون هوش مصنوعی مطابقت دارد: "وقتی بازدیدکننده درباره در دسترس بودن اتاق می‌پرسد"

اقدام CALL_API: GET https://api.hotel.com/rooms/205/availability

پاسخ نگاشت شده: room_available = true، price = "€۱۲۰/شب"

هوش مصنوعی پاسخ می‌دهد: "اتاق ۲۰۵ هفته بعد به قیمت €۱۲۰/شب در دسترس است. می‌خواهید آن را رزرو کنید؟"

راه‌اندازی یک اتصال

به تنظیمات → اتصالات API در داشبورد خود بروید.

۱. ایجاد یک اتصال

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

فیلدتوضیحاتمثال
نامیک برچسب برای این اتصالAPI رزرو هتل
URL پایهURL ریشه APIhttps://api.hotel.com/v1
نوع احراز هویتچگونه احراز هویت کنیمBearer Token, OAuth2 و غیره

۲. انواع احراز هویت

None

برای APIهای عمومی که به احراز هویت نیاز ندارند.

API Key

یک کلید استاتیک را به عنوان هدر یا پارامتر کوئری ارسال می‌کند.

فیلدتوضیحات
کلیدمقدار کلید API شما
نام هدرهدر برای استفاده (پیش‌فرض: X-Api-Key)

کلید به این شکل ارسال می‌شود: X-Api-Key: your_key_here

Bearer Token

یک توکن استاتیک را در هدر Authorization ارسال می‌کند.

به این شکل ارسال می‌شود: Authorization: Bearer your_token_here

Basic Auth

نام کاربری و رمز عبور را با کدگذاری base64 ارسال می‌کند.

به این شکل ارسال می‌شود: Authorization: Basic dXNlcjpwYXNz

OAuth 2.0 (Client Credentials)

یک توکن دسترسی را به طور خودکار دریافت می‌کند و تا انقضا کش می‌کند. بهترین برای APIهای مدرن مانند Salesforce، Google یا سرورهای OAuth سفارشی.

فیلدتوضیحات
URL توکنendpoint توکن OAuth (مثلاً https://auth.example.com/oauth/token)
Client IDOAuth client ID شما
Client SecretOAuth client secret شما
Scopescopeهای جدا شده با فاصله (مثلاً read write)

enuchat چرخه عمر توکن را به طور خودکار مدیریت می‌کند — در فراخوانی اول دریافت می‌کند، تا انقضا کش می‌کند، در صورت نیاز رفرش می‌کند.

امنیت: همه اعتبارنامه‌ها در حالت استراحت با استفاده از libsodium رمزگذاری می‌شوند. آن‌ها هرگز در پاسخ‌های API افشا نمی‌شوند — فقط مقادیر ماسک شده در داشبورد نمایش داده می‌شوند.

پیکربندی Endpointها

هر اتصال می‌تواند چندین endpoint داشته باشد — فراخوانی‌های API خاصی که می‌خواهید انجام دهید.

فیلدتوضیحاتمثال
نامبرچسب برای این endpointبررسی در دسترس بودن
متدمتد HTTPGET, POST, PUT, DELETE
مسیرمسیر URL (به URL پایه اضافه شده). از {'{'}variable} برای مقادیر پویا استفاده کنید/rooms/{'{'}roomId}/availability
پارامترهای کوئریپارامترهای URL به عنوان جفت کلید-مقدار. مقادیر از {'{'}variable} پشتیبانی می‌کنندdate={'{'}checkIn}
قالب بدنهبدنه JSON برای POST/PUT. از درج {'{'}variable} پشتیبانی می‌کند{'{'}"guest": "{'{'}name}"}
نگاشت پاسخفیلدهای پاسخ JSON را با استفاده از نشانه‌گذاری نقطه به متغیرهای نشست نگاشت کنیدdata.available → room_available
توضیحاتزمینه برای هوش مصنوعی (این endpoint چه داده‌ای را برمی‌گرداند)در دسترس بودن اتاق و قیمت‌گذاری را برمی‌گرداند

درج متغیر

از {'{'}variableName} در مسیرها، پارامترهای کوئری و قالب‌های بدنه استفاده کنید. متغیرها از موارد زیر می‌آیند:

  • متغیرهای نشست — توسط قوانین قبلی تنظیم شده‌اند (اقدام SET_VARIABLE)
  • پارامترهای اقدام — در اقدام قانون CALL_API هاردکد شده‌اند

نگاشت پاسخ

فیلدهای پاسخ JSON را با استفاده از نشانه‌گذاری نقطه به متغیرهای نشست نگاشت کنید:

// API returns:
{'{'}
  "data": {'{'}
    "available": true,
    "price": {'{'} "amount": 120, "currency": "EUR" }
  }
}

// Mapping:
data.available  →  room_available    // "true"
data.price.amount  →  room_price    // "120"
data.price.currency  →  room_currency  // "EUR"

متغیرهای نگاشت شده به عنوان متغیرهای نشست در گفتگو ذخیره می‌شوند و برای هوش مصنوعی برای تولید پاسخ‌ها در دسترس هستند.

استفاده با قوانین

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

دستورالعمل: جستجوی وضعیت سفارش

اتصال: API مدیریت سفارش — https://api.shop.com/v2 — Bearer Token

Endpoint: GET /orders/{'{'}orderId} → data.status را به order_status، data.eta را به delivery_eta نگاشت می‌کند

قانون (نوع هوش مصنوعی): "وقتی بازدیدکننده درباره وضعیت سفارش یا تحویل خود می‌پرسد"

اقدامات:

  1. CALL_API → endpoint وضعیت سفارش
  2. REPLY_AI → هوش مصنوعی از order_status و delivery_eta برای پاسخ استفاده می‌کند

نتیجه: بازدیدکننده: "سفارش #۴۵۲۱ من کجاست؟" — هوش مصنوعی: "سفارش #۴۵۲۱ شما در حال حاضر در حال ارسال است و باید تا پنجشنبه برسد."

دستورالعمل: قیمت‌گذاری بلادرنگ

اتصال: API قیمت‌گذاری — https://pricing.example.com — API Key

Endpoint: GET /products/{'{'}productId}/price → price را به current_price، currency را به price_currency نگاشت می‌کند

قانون (استاتیک): MESSAGE_MATCHES_REGEX: /\b(price|cost|how much)\b/i

اقدامات:

  1. CALL_API → endpoint قیمت‌گذاری
  2. REPLY_TEXT → "قیمت فعلی {'{'}current_price} {'{'}price_currency} است."

آزمایش

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

  • آزمایش اتصال — تأیید می‌کند که احراز هویت کار می‌کند (برای OAuth2: یک توکن دریافت می‌کند)
  • آزمایش endpoint — یک فراخوانی API واقعی با متغیرهای نمونه انجام می‌دهد و پاسخ را نشان می‌دهد
  • آزمایش قانون (dry-run) — در صفحه قوانین، آزمایش کنید آیا یک قانون مطابقت پیدا می‌کند و چه اقداماتی اجرا می‌شوند

نکته: با آزمایش اتصال شروع کنید، سپس هر endpoint، سپس قانون کامل. به این روش می‌توانید مشکلات را در هر سطح جدا کنید.

امنیت

  • رمزگذاری در حالت استراحت — همه اعتبارنامه‌ها قبل از ذخیره با استفاده از libsodium رمزگذاری می‌شوند
  • هرگز افشا نمی‌شوند — پاسخ‌های API هرگز شامل اعتبارنامه‌های رمزگشایی شده نیستند، فقط مقادیر ماسک شده
  • محافظت SSRF — enuchat فراخوانی‌ها به localhost، IPهای خصوصی و نام‌های میزبان داخلی را مسدود می‌کند
  • تایم‌اوت — فراخوانی‌های API خارجی تایم‌اوت ۵ ثانیه‌ای دارند تا از معلق شدن جلوگیری شود
  • کش توکن OAuth2 — توکن‌های دسترسی به‌طور ایمن کش می‌شوند و به‌طور خودکار رفرش می‌شوند
  • جداسازی tenant — اتصالات به tenant شما محدود شده‌اند، برای دیگران غیرقابل دسترسی

آماده‌اید APIهای خود را متصل کنید؟

امروز شروع به ادغام سیستم‌های خود با enuchat کنید.

رایگان شروع کنید