API 连接

将您的外部 API 连接到 enuchat，让 AI 和规则能够从您的系统获取实时数据。

工作原理

API 连接让您将 enuchat 与自己的后端系统集成 — 预订引擎、CRM、订单管理、库存等。当访客提问时，enuchat 可以调用您的 API 获取真实数据并将其包含在回复中。

流程

配置连接 — 您 API 的基础 URL 和认证方式
添加 endpoint — 带路径模板和响应映射的具体 API 调用
创建规则 — 带 CALL_API 动作的 AI 或静态规则
访客提问 — 规则触发，调用您的 API，将响应映射到会话变量
AI 使用真实数据回复 — 会话变量可供 AI 生成准确的回答

示例：酒店房间可用性

访客："205 号房下周有空吗？"

AI 规则匹配："当访客询问房间可用性时"

CALL_API 动作：GET https://api.hotel.com/rooms/205/availability

响应映射：room_available = true, price = "€120/晚"

AI 回复："205 号房下周可用，价格为 €120/晚。需要预订吗？"

设置连接

前往操作面板中的设置 → API 连接。

1. 创建连接

一个连接代表一个外部 API。您需要：

字段	说明	示例
名称	此连接的标签	酒店预订 API
基础 URL	API 的根 URL	`https://api.hotel.com/v1`
认证类型	认证方式	Bearer Token、OAuth2 等

2. 认证类型

无认证

适用于不需要认证的公开 API。

API Key

作为请求头或查询参数发送静态密钥。

字段	说明
Key	您的 API 密钥值
Header Name	使用的请求头（默认：`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)

自动获取访问令牌并缓存至过期。最适合 Salesforce、Google 等现代 API 或自定义 OAuth 服务器。

字段	说明
Token URL	OAuth 令牌 endpoint（例如 `https://auth.example.com/oauth/token`）
Client ID	您的 OAuth 客户端 ID
Client Secret	您的 OAuth 客户端密钥
Scope	空格分隔的权限范围（例如 `read write`）

enuchat 自动处理令牌生命周期 — 首次调用时获取，缓存至过期，需要时自动刷新。

安全提示：所有凭据在存储前使用 libsodium 加密。API 响应中从不暴露解密后的凭据 — 操作面板中仅显示脱敏值。

配置 Endpoint

每个连接可以有多个 endpoint — 您想要调用的具体 API 接口。

字段	说明	示例
名称	此 endpoint 的标签	查询可用性
方法	HTTP 方法	GET、POST、PUT、DELETE
路径	URL 路径（附加到基础 URL）。使用 `{'{'}variable}` 表示动态值	`/rooms/{'{'}roomId}/availability`
查询参数	URL 参数的键值对。值支持 `{'{'}variable}`	`date={'{'}checkIn}`
请求体模板	POST/PUT 的 JSON 请求体。支持 `{'{'}variable}` 插值	`{'{'}"guest": "{'{'}name}"}`
响应映射	使用点号表示法将 JSON 响应字段映射到会话变量	`data.available → room_available`
描述	为 AI 提供的上下文（此 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"

映射的变量作为会话变量存储在对话上，可供 AI 生成回复时使用。

与规则配合使用

API 调用由规则中的 CALL_API 动作触发。您可以将其与其他动作组合使用。

方案：订单状态查询

连接：订单管理 API — https://api.shop.com/v2 — Bearer Token

Endpoint：GET /orders/{'{'}orderId} → 映射 data.status → order_status, data.eta → delivery_eta

规则（AI 类型）："当访客询问订单状态或配送时"

动作：

CALL_API → 订单状态 endpoint
REPLY_AI → AI 使用 order_status 和 delivery_eta 回复

结果：访客："我的订单 #4521 到哪了？" — AI："您的订单 #4521 正在配送中，预计周四到达。"

方案：实时价格查询

连接：价格 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

动作：

CALL_API → 价格 endpoint
REPLY_TEXT → "The current price is {'{'}current_price} {'{'}price_currency}."

测试

在将连接和 endpoint 用于规则之前，请务必先测试：

测试连接 — 验证认证是否正常（对于 OAuth2：获取令牌）
测试 Endpoint — 使用示例变量发起真实 API 调用并查看响应
测试规则（模拟运行） — 在规则页面测试规则是否匹配以及将执行哪些动作

提示：先测试连接，再测试每个 endpoint，最后测试完整的规则。这样您可以在每个层级隔离问题。

安全

静态加密 — 所有凭据在存储前使用 libsodium 加密
从不暴露 — API 响应从不包含解密后的凭据，仅显示脱敏值
SSRF 防护 — enuchat 阻止对 localhost、私有 IP 和内部主机名的调用
超时 — 外部 API 调用有 5 秒超时限制，防止挂起
OAuth2 令牌缓存 — 访问令牌安全缓存并自动刷新
租户隔离 — 连接仅限于您的租户，其他人无法访问

准备好连接您的 API 了吗？

立即开始将您的系统与 enuchat 集成。

免费开始使用