公开 API

这些是嵌入式小组件自身调用的端点。它们是公开的——无需用户登录——并通过您的站点密钥进行身份验证。您可以直接使用它们来构建自定义聊天界面。

身份验证

将站点密钥作为请求头发送。请求还会根据您的域名允许列表进行检查，因此泄露的密钥无法从其他站点使用。

X-Site-Key: your-site-key

获取小组件配置

GET /public/widget-config

返回外观设置。小组件加载时会调用此接口。

{
  "widgetPosition": "bottom_right",
  "widgetPrimaryColor": "#075CE5",
  "widgetFontFamily": "inherit",
  "widgetLogoUrl": null,
  "widgetAssistantName": "Minaya",
  "widgetWelcomeMessage": "Hi, I am Minaya your AI assistant...",
  "widgetHeaderTextColor": "#FFFFFF",
  "widgetBotBubbleColor": "#F1F1F3",
  "widgetBotTextColor": "#18181B",
  "widgetUserTextColor": "#FFFFFF",
  "widgetOpenByDefault": false,
  "widgetPathMode": "all",
  "widgetPathRules": [],
  "widgetCustomCss": null
}

widgetAssistantName 由服务端解析——始终为字符串，绝不为 null。

widgetPathMode 与 widgetPathRules 指定小组件应在何处显示（all、include 或 exclude，配合 /blog/* 之类的路径模式）。内置小组件会应用它们；自定义客户端也应如此。

缓存

读取类端点在服务端缓存，并在底层设置变更的那一刻清除，因此保存后的更改在下一次请求即生效。响应带有 X-Cache 头（HIT 或 MISS）；发送 Cache-Control: no-cache 可为单次请求绕过缓存。

发送消息

POST /public/chat

{
  "message": "Do you ship to Canada?",
  "sessionId": "optional-existing-session",
  "visitorIdentifier": "optional-stable-visitor-id",
  "stream": false,
  "origin": "https://example.com",
  "country": "CA"
}

省略 sessionId 即可开启新对话；响应会返回一个供后续消息复用的sessionId。

{ "sessionId": "…", "reply": "Yes — 3 to 5 business days…", "messageId": "…" }

当 stream: true 时，回复以服务器发送事件（SSE）的形式到达，每个事件携带一个content 增量，最后以 done 事件结束。

获取历史记录

GET /public/chat/history/:sessionId

返回某个会话中的消息，范围限定在您的商户内，因此一个站点的小组件永远无法读取另一个站点的对话。用于访客重新打开小组件时恢复对话。

为消息评分

POST /public/chat/feedback

{ "messageId": "…", "feedback": "up" }

接受 up 或 down，且仅适用于助手消息。评分会显示在您的仪表盘分析中。

分析事件

POST /public/track-click
POST /public/track-page-view

在小组件被打开以及页面加载时触发。两者都接受可选的 sessionId、visitorIdentifier、origin 和 country。

速率限制与上限

聊天请求按站点密钥进行速率限制。
每个会话最多 50 条消息。
每条消息最多 500 个字符。
免费套餐商户有每日消息上限。
付费套餐有每月额度——入门版 2,000 条消息，专业版 10,000 条——按小组件所在的所有对话和所有域名合计，从续订到续订计算。
使用 Minaya 的 AI 时，执行操作的回复（记录潜在客户或调用 MCP 工具）从额度中计为 3 条消息。使用您自己的密钥时，每条回复都计为 1 条。
付费套餐还有每日上限，为套餐日均量的三倍，用于防止失控循环在一天内耗尽整月额度。

超出限制时会返回说明情况的正常回复，而不是错误，因此自定义界面可以像处理其他消息一样展示它。

仪表盘 API

管理知识来源、外观和 MCP 服务器需要使用同一主机下经过身份验证的端点，详情记录在您部署环境中的 /api/docs OpenAPI 规范文档中。