Kết nối API

Kết nối API bên ngoài đến enuchat để AI và quy tắc có thể lấy dữ liệu thời gian thực từ hệ thống của bạn.

Cách Hoạt động

Kết nối API cho phép bạn tích hợp enuchat với hệ thống backend riêng — công cụ đặt chỗ, CRM, quản lý đơn hàng, tồn kho và hơn nữa. Khi khách đặt câu hỏi, enuchat có thể gọi API của bạn để lấy dữ liệu thực và đưa vào phản hồi.

Luồng

  1. Cấu hình kết nối — URL cơ sở và xác thực của API
  2. Thêm endpoint — các cuộc gọi API cụ thể với mẫu đường dẫn và ánh xạ phản hồi
  3. Tạo quy tắc — quy tắc AI hoặc tĩnh với hành động CALL_API
  4. Khách đặt câu hỏi — quy tắc kích hoạt, gọi API, ánh xạ phản hồi thành biến phiên
  5. AI phản hồi với dữ liệu thực — biến phiên có sẵn cho AI để tạo câu trả lời chính xác

Ví dụ: Tình trạng Phòng Khách sạn

Khách: "Phòng 205 có sẵn tuần tới không?"

Quy tắc AI khớp: "Khi khách hỏi về tình trạng phòng"

Hành động CALL_API: GET https://api.hotel.com/rooms/205/availability

Phản hồi ánh xạ: room_available = true, price = "€120/đêm"

AI phản hồi: "Phòng 205 có sẵn tuần tới với giá €120/đêm. Bạn có muốn đặt không?"

Thiết lập Kết nối

Đi đến Cài đặt → Kết nối API trong bảng điều khiển.

1. Tạo Kết nối

Kết nối đại diện cho một API bên ngoài. Bạn cần:

TrườngMô tảVí dụ
TênNhãn cho kết nối nàyAPI Đặt phòng Khách sạn
URL Cơ sởURL gốc của APIhttps://api.hotel.com/v1
Loại Xác thựcCách xác thựcBearer Token, OAuth2, v.v.

2. Các Loại Xác thực

Không

Cho các API công khai không yêu cầu xác thực.

Khoá API

Gửi khoá tĩnh như header hoặc tham số truy vấn.

TrườngMô tả
KhoáGiá trị khoá API của bạn
Tên HeaderHeader để dùng (mặc định: X-Api-Key)

Khoá được gửi như: X-Api-Key: your_key_here

Bearer Token

Gửi token tĩnh trong header Authorization.

Gửi như: Authorization: Bearer your_token_here

Basic Auth

Gửi tên người dùng và mật khẩu, mã hoá base64.

Gửi như: Authorization: Basic dXNlcjpwYXNz

OAuth 2.0 (Client Credentials)

Lấy token truy cập tự động và đệm cho đến khi hết hạn. Tốt nhất cho các API hiện đại như Salesforce, Google hoặc máy chủ OAuth tuỳ chỉnh.

TrườngMô tả
URL TokenEndpoint token OAuth (vd. https://auth.example.com/oauth/token)
Client IDClient ID OAuth của bạn
Client SecretClient Secret OAuth của bạn
ScopeCác phạm vi cách nhau bằng khoảng trắng (vd. read write)

enuchat xử lý vòng đời token tự động — lấy khi gọi đầu, đệm đến hết hạn, làm mới khi cần.

Bảo mật: Tất cả thông tin xác thực được mã hoá khi lưu dùng libsodium. Chúng không bao giờ được lộ trong phản hồi API — chỉ các giá trị được che được hiển thị trong bảng điều khiển.

Cấu hình Endpoint

Mỗi kết nối có thể có nhiều endpoint — các cuộc gọi API cụ thể bạn muốn thực hiện.

TrườngMô tảVí dụ
TênNhãn cho endpoint nàyKiểm tra tình trạng sẵn có
Phương thứcPhương thức HTTPGET, POST, PUT, DELETE
Đường dẫnĐường dẫn URL (nối với URL cơ sở). Dùng {'{'}variable} cho giá trị động/rooms/{'{'}roomId}/availability
Tham số Truy vấnTham số URL dưới dạng cặp khoá-giá trị. Giá trị hỗ trợ {'{'}variable}date={'{'}checkIn}
Mẫu ThânThân JSON cho POST/PUT. Hỗ trợ nội suy {'{'}variable}{'{'}"guest": "{'{'}name}"}
Ánh xạ Phản hồiÁnh xạ các trường phản hồi JSON sang biến phiên dùng ký hiệu dấu chấmdata.available → room_available
Mô tảNgữ cảnh cho AI (endpoint này trả về dữ liệu gì)Trả về tình trạng phòng và giá

Nội suy Biến

Dùng {'{'}variableName} trong đường dẫn, tham số truy vấn và mẫu thân. Biến đến từ:

  • Biến phiên — được đặt bởi quy tắc trước đó (hành động SET_VARIABLE)
  • Tham số hành động — cứng trong hành động quy tắc CALL_API

Ánh xạ Phản hồi

Ánh xạ các trường phản hồi JSON sang biến phiên dùng ký hiệu dấu chấm:

// API trả về:
{'{'}
  "data": {'{'}
    "available": true,
    "price": {'{'} "amount": 120, "currency": "EUR" }
  }
}

// Ánh xạ:
data.available  →  room_available    // "true"
data.price.amount  →  room_price    // "120"
data.price.currency  →  room_currency  // "EUR"

Các biến được ánh xạ được lưu dưới dạng biến phiên trên cuộc trò chuyện và có sẵn cho AI để tạo phản hồi.

Dùng với Quy tắc

Các cuộc gọi API được kích hoạt bởi hành động CALL_API trong quy tắc. Bạn có thể kết hợp chúng với các hành động khác.

Công thức: Tra cứu Trạng thái Đơn hàng

Kết nối: API Quản lý Đơn hàng — https://api.shop.com/v2 — Bearer Token

Endpoint: GET /orders/{'{'}orderId} → ánh xạ data.status → order_status, data.eta → delivery_eta

Quy tắc (loại AI): "Khi khách hỏi về trạng thái đơn hàng hoặc giao hàng"

Hành động:

  1. CALL_API → endpoint Trạng thái Đơn hàng
  2. REPLY_AI → AI dùng order_status và delivery_eta để phản hồi

Kết quả: Khách: "Đơn #4521 của tôi ở đâu?" — AI: "Đơn #4521 của bạn hiện đang được giao và sẽ đến vào Thứ Năm."

Công thức: Giá Thời gian Thực

Kết nối: API Giá — https://pricing.example.com — Khoá API

Endpoint: GET /products/{'{'}productId}/price → ánh xạ price → current_price, currency → price_currency

Quy tắc (tĩnh): MESSAGE_MATCHES_REGEX: /\b(price|cost|how much)\b/i

Hành động:

  1. CALL_API → endpoint Giá
  2. REPLY_TEXT → "Giá hiện tại là {'{'}current_price} {'{'}price_currency}."

Kiểm thử

Luôn kiểm thử kết nối và endpoint trước khi dùng chúng trong quy tắc:

  • Kiểm thử Kết nối — xác minh xác thực hoạt động (cho OAuth2: lấy token)
  • Kiểm thử Endpoint — thực hiện cuộc gọi API thực với biến mẫu và hiển thị phản hồi
  • Kiểm thử Quy tắc (dry-run) — trên trang Quy tắc, kiểm tra xem quy tắc có khớp không và hành động nào sẽ thực thi

Mẹo: Bắt đầu bằng kiểm thử kết nối, sau đó mỗi endpoint, rồi quy tắc hoàn chỉnh. Cách này bạn có thể cô lập vấn đề ở mỗi cấp.

Bảo mật

  • Mã hoá khi lưu — tất cả thông tin xác thực được mã hoá dùng libsodium trước khi lưu
  • Không bao giờ lộ — phản hồi API không bao giờ bao gồm thông tin xác thực đã giải mã, chỉ giá trị được che
  • Bảo vệ SSRF — enuchat chặn cuộc gọi đến localhost, IP riêng và tên máy chủ nội bộ
  • Thời gian chờ — cuộc gọi API bên ngoài có thời gian chờ 5 giây để tránh treo
  • Đệm token OAuth2 — token truy cập được đệm an toàn và làm mới tự động
  • Cô lập tenant — kết nối được phạm vi đến tenant của bạn, không thể truy cập bởi người khác

Sẵn sàng kết nối API?

Bắt đầu tích hợp hệ thống với enuchat ngay hôm nay.

Bắt đầu Miễn phí