公开 API

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

身份验证

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

X-Site-Key: your-site-key

获取小组件配置

GET /public/widget-config

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

{
  "widgetPosition": "bottom_right",
  "widgetPrimaryColor": "#14B8A6",
  "widgetFontFamily": "inherit",
  "widgetLogoUrl": null,
  "widgetAssistantName": "Minaya",
  "widgetWelcomeMessage": "Hi, I am Minaya your AI assistant...",
  "widgetHeaderTextColor": "#FFFFFF",
  "widgetBotBubbleColor": "#F1F1F3",
  "widgetBotTextColor": "#18181B",
  "widgetUserTextColor": "#FFFFFF",
  "widgetOpenByDefault": false,
  "widgetCustomCss": null
}

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

发送消息

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 条消息。
每条消息最多 2,000 个字符。
免费套餐商户有每日消息上限。

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

仪表盘 API

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