AI 客服接口用于把客户站点的访客咨询接入 GrowthOS。浏览器组件必须先请求客户站点自己的代理接口，代理服务再携带 site token 调用 Connector API。 
浏览器客服组件 -> 客户站点代理 -> GrowthOS Connector API

​
接口总览

能力方法路径说明
获取客服配置GET/chat/config读取客服开关、名称、头像、语种等配置
发送访客消息POST/chat/messages创建或延续会话，并返回 AI 回复
拉取会话消息GET/chat/messages获取指定会话的新消息
查询在线状态GET/chat/presence获取人工客服在线状态和轮询建议

​
通用请求头

Header必填说明
Authorization: Bearer <site_token>是站点服务端 token，不能暴露到浏览器
Content-Type: application/json写接口必填请求体格式
Idempotency-Key写接口建议消息发送失败重试时避免重复入库

​
获取客服配置

GET /api/connector/v1/chat/config?locale=zh-CN
Authorization: Bearer <site_token>

​
Query 参数

参数类型必填说明
localestring否当前页面语种，例如 zh-CN、en-US

​
响应示例

{
  "ok": true,
  "data": {
    "tenantId": "tenant_id",
    "siteId": "site_id",
    "config": {
      "enabled": true,
      "widgetEnabled": true,
      "assistantName": "AI 顾问",
      "welcomeMessage": "你好，我可以帮你了解产品和方案。",
      "avatarUrl": null,
      "locale": "zh-CN"
    },
    "locale": "zh-CN",
    "supportedLocales": ["zh-CN", "en-US"],
    "stale": false
  },
  "requestId": "request_id"
}

​
发送访客消息

POST /api/connector/v1/chat/messages
Authorization: Bearer <site_token>
Content-Type: application/json
Idempotency-Key: chat-v_123-001

​
Body 参数

字段类型必填说明
conversationIdstring / null否已有会话 ID；新会话可传 null 或不传
messagestring是访客消息，1-4000 字符
localestring否消息语种
sourcePagestring否当前页面路径
visitor.visitorIdstring建议访客稳定 ID
visitor.namestring否访客姓名
visitor.emailstring否邮箱
visitor.phonestring否电话
visitor.companystring否公司
visitor.wechatstring否微信
visitor.whatsappstring否WhatsApp
visitor.countrystring否国家或地区

​
请求示例

curl -X POST "$CONNECTOR_API_BASE/chat/messages" \
  -H "Authorization: Bearer YOUR_SITE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: chat-v_123-001" \
  -d '{
    "conversationId": null,
    "message": "你好，我想了解报价。",
    "locale": "zh-CN",
    "sourcePage": "/",
    "visitor": {
      "visitorId": "v_123"
    }
  }'

​
响应示例

{
  "ok": true,
  "data": {
    "conversationId": "conversation_id",
    "userMessageId": "user_message_id",
    "message": {
      "id": "assistant_message_id",
      "role": "assistant",
      "content": "你好，可以先简单说一下你的产品类型和目标市场吗？",
      "createdAt": "2026-06-01T08:00:00.000Z"
    },
    "provider": "openai",
    "usedFallback": false,
    "aiStatus": "ok",
    "aiStatusMessage": "",
    "locale": "zh-CN",
    "blocked": false,
    "lead": {
      "score": 20,
      "hasContact": false,
      "needsHandoff": false,
      "summary": "访客咨询报价"
    }
  },
  "requestId": "request_id"
}

​
关键响应字段

字段说明
conversationId会话 ID，后续发送消息和轮询消息都要携带
userMessageId本次访客消息 ID
messageAI 回复消息
aiStatusAI 状态，常见值：ok、provider_error、quota_insufficient、blocked
usedFallback是否使用兜底回复
lead线索分析结果，可能包含意向分和联系方式状态

​
拉取会话消息

GET /api/connector/v1/chat/messages?conversationId=conversation_id&after=message_id
Authorization: Bearer <site_token>
Query 参数类型必填说明
conversationIdstring是会话 ID
afterstring否只返回该消息之后的新消息
{
  "ok": true,
  "data": {
    "conversationId": "conversation_id",
    "messages": [
      {
        "id": "message_id",
        "role": "operator",
        "content": "你好，我来继续跟进。",
        "createdAt": "2026-06-01T08:01:00.000Z"
      }
    ],
    "nextAfter": "message_id"
  },
  "requestId": "request_id"
}

​
查询在线状态

GET /api/connector/v1/chat/presence?conversationId=conversation_id
Authorization: Bearer <site_token>

{
  "ok": true,
  "data": {
    "tenantId": "tenant_id",
    "siteId": "site_id",
    "operatorOnline": true,
    "operatorActiveSessions": 1,
    "operatorLastSeenAt": "2026-06-01T08:00:00.000Z",
    "shouldPollMessages": true,
    "suggestedPresenceIntervalMs": 15000,
    "suggestedMessageIntervalMs": 3000
  },
  "requestId": "request_id"
}

​
常见错误

HTTP错误码说明
400INVALID_REQUEST参数缺失或格式错误
401INVALID_TOKENtoken 无效
402INSUFFICIENT_QUOTASaaS 额度不足
409IDEMPOTENCY_CONFLICT同一个幂等键被不同请求体复用
429RATE_LIMITED请求过快，按 Retry-After 重试

​
实现注意事项

  • 浏览器不要持有 site token，只访问客户站点自己的代理接口。
  • 发送消息要带稳定的 Idempotency-Key，避免超时重试时生成重复回复。
  • AI 不可用时，应展示简短兜底话术，不要输出知识库原文或系统提示词。
  • 客户站点可以根据 suggestedMessageIntervalMs 控制消息轮询频率。