Chat API 参考

身份验证

每个请求都使用您的工作区 API 密钥进行身份验证，通过 X-API-Key 请求头（或 api_key 参数）发送。密钥形如 ck_live_...。请像对待密码一样对待该密钥 - 持有它的任何人都可以发送计入您工作区账单的消息。您可以随时从 设置 -> API 访问 轮换密钥；旧密钥会立即失效。

发送消息

POST https://chatixy.com/api/v1/chat

curl https://chatixy.com/api/v1/chat \
  -H "X-API-Key: ck_live_YOUR_KEY" \
  -F "message=How do I reset my password?"

参数：

• message（字符串）- 访客消息。除非附加了 files，否则必填。
• ticket_id（字符串，可选）- 继续现有对话。省略则开始新对话。
• visitor_email / visitor_name（字符串，可选）- 将联系信息附加到工单。
• files（multipart，可选）- 访客附件。需要支持文件上传的计划。

响应

消息一经存储，该调用即返回 202 Accepted；AI 回复将异步生成。

{
  "status": { "code": 202, "message": "Message received and being processed" },
  "data": {
    "ticket_id": 1234,
    "ticket_number": "T-1234",
    "id": "<visitor_hash>",
    "processing": true
  }
}

在下次调用时将 data.ticket_id 作为 ticket_id 传回，以保持对话继续。要接收 AI 回复，请通过 WebSocket（ActionCable）订阅以 data.id 为键的频道 - 这与嵌入式挂件使用的访客哈希相同。

读取会话

使用同一个 X-API-Key 拉取工单及其消息。每个读取端点都限定在您的工作区内，并在商务版套餐中提供。

• GET /api/v1/chat/tickets - 列出工单，最新的排在前面。查询参数：status、limit（最大 100）、offset。返回 tickets 和 pagination。
• GET /api/v1/chat/tickets/:id - 单个工单。
• GET /api/v1/chat/tickets/:id/messages - 按顺序获取工单的消息，每条都包含 role、content 和 attachments。

curl https://chatixy.com/api/v1/chat/tickets \
  -H "X-API-Key: ck_live_YOUR_KEY"

速率限制与配额

请求按每个密钥（及每个 IP）大约每分钟 20 次进行限流。每条生成的回复还会消耗您计划的每月消息额度；一旦用尽，端点将返回 200 及 data.limit_reached: true，而不会生成回复。

错误

• 401 - 未提供 API 密钥。
• 404 - 密钥与任何工作区都不匹配（例如轮换之后）。
• 403 plan_upgrade_required - 工作区未使用商务版计划。
• 403 - 订阅未激活，或请求来自挂件设置不允许的域名。
• 422 - 缺少消息（且未附加任何文件）。