访客事件接口用于把客户站点的行为数据同步到 GrowthOS。事件不会直接触发 AI 回复，但会作为会话上下文、线索判断和运营分析的数据来源。 浏览器端不要直连 GrowthOS 云端接口。推荐调用链路： 
浏览器组件 -> 客户站点代理 -> GrowthOS Connector API

​
接口总览

能力方法路径调用方
上报事件批次POST/events客户站点代理

​
通用请求头

Header必填说明
Authorization: Bearer <site_token>是站点服务端 token，不要暴露给浏览器
Content-Type: application/json是请求体格式
Idempotency-Key建议同一批事件重试时保持一致，长度 8-160

​
POST /events

一次最多上报 50 条事件。适合页面浏览、客服打开/关闭、按钮点击、表单提交等行为。 
POST /api/connector/v1/events
Authorization: Bearer <site_token>
Content-Type: application/json
Idempotency-Key: events-v_123-001

​
Body 参数

字段类型必填说明
eventsarray是事件数组，1-50 条
events[].eventTypestring是事件类型，例如 page_view
events[].visitorIdstring建议访客稳定 ID，同一访客应长期一致
events[].customerIdstring否客户站点自己的用户 ID
events[].channelstring否渠道，例如 web、chat
events[].pathstring否页面路径，例如 /products
events[].urlstring否完整 URL
events[].titlestring否页面标题
events[].referrerstring否来源页面
events[].eventDataobject否扩展数据，例如按钮名称、表单类型、会话 ID
events[].createdAtstring否ISO 时间；不传时使用服务端接收时间

​
推荐事件类型

事件说明建议字段
page_view页面访问visitorId、path、url、title
chat_opened打开客服窗口visitorId、path、eventData.conversationId
chat_closed关闭客服窗口visitorId、eventData.conversationId
cta_clicked点击关键按钮visitorId、path、eventData.label
lead_submitted提交联系方式或询盘visitorId、eventData.formType

​
请求示例

curl -X POST "$CONNECTOR_API_BASE/events" \
  -H "Authorization: Bearer YOUR_SITE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: events-v_123-001" \
  -d '{
    "events": [
      {
        "eventType": "page_view",
        "visitorId": "v_123",
        "channel": "web",
        "path": "/products",
        "url": "https://customer.example/products",
        "title": "Products",
        "createdAt": "2026-06-01T08:00:00.000Z"
      },
      {
        "eventType": "cta_clicked",
        "visitorId": "v_123",
        "path": "/products",
        "eventData": {
          "label": "Get Quote",
          "position": "hero"
        }
      }
    ]
  }'

​
成功响应

{
  "ok": true,
  "data": {
    "accepted": 2,
    "rejected": 0,
    "tracking": "enabled"
  },
  "requestId": "request_id"
}

​
响应字段

字段说明
accepted成功接收的事件数量
rejected被拒收的事件数量
tracking当前站点事件追踪状态，可能是 enabled 或 disabled

​
常见错误

HTTP错误码说明处理建议
400INVALID_REQUEST事件为空、超过 50 条或字段格式错误修正请求体后重试
401INVALID_TOKENtoken 无效检查站点 token
409IDEMPOTENCY_CONFLICT同一个幂等键被不同请求体复用为新请求生成新的幂等键
429RATE_LIMITED请求过快按 Retry-After 退避重试

​
实现要点

  • visitorId 是串联会话、事件和线索的关键字段，建议保存在客户站点的一方 cookie 或本地存储中。
  • 客服相关事件建议把 conversationId 放到 eventData，便于 GrowthOS 关联行为路径。
  • 事件接口可以批量上报，也可以低频实时上报；高流量站点建议本地聚合后批量提交。
  • 表单、电话、邮箱等敏感字段只在业务确实需要时上报。
  • 网络失败可以重试，但同一批事件要复用同一个 Idempotency-Key。