API 参考

所有 API 请求通过 X-Api-Key 请求头中发送的 API 密钥进行认证。

获取您的 API 密钥

1. 前往操作面板中的设置 → API 密钥
2. 点击创建 API 密钥并为其命名
3. 立即复制密钥 — 它只显示一次
4. 安全存储（环境变量、密钥管理器）

发起请求

在每个请求中包含密钥：

curl -H "X-Api-Key: tak_your_key_here" \
     https://api.enuchat.com/api/v1/tenant-api/widgets

所有响应均为 JSON。成功响应包含 data 字段。错误响应包含带有 code 和 message 的 error 字段。

安全提示：API 密钥在数据库中以哈希（SHA-256）形式存储。我们从不存储原始密钥。请像对待密码一样对待您的密钥 — 不要提交到代码中或公开分享。

GET /widgets

列出您账户的所有小部件。

响应

{'{'}
  "data": [
{'{'}
      "id": "019d19c6-7e0b-...",
      "name": "Main Website Chat",
      "isActive": true,
      "aiEnabled": true,
      "translationEnabled": true,
      "primaryColor": "#2563eb",
      "position": "bottom-right"
    }
  ]
}

GET /conversations

列出对话，按最新消息排序。

查询参数

示例

curl -H "X-Api-Key: tak_..." \
     "https://api.enuchat.com/api/v1/tenant-api/conversations?status=open&limit=10"

响应

{'{'}
  "data": [
{'{'}
      "id": "019d6724-000e-...",
      "widgetId": "019d19c6-7e0b-...",
      "visitorId": "v-abc123",
      "visitorName": "John",
      "visitorEmail": "john{'@'}example.com",
      "visitorLanguage": "en",
      "status": "open",
      "assignedTo": null,
      "lastMessageAt": "2026-04-11T14:30:00+00:00",
      "startedAt": "2026-04-11T14:25:00+00:00"
    }
  ]
}

GET /conversations/{'{'}id}

获取对话及其所有消息。

查询参数

响应

{'{'}
  "data": {'{'}
    "id": "019d6724-000e-...",
    "visitorLanguage": "en",
    "status": "open",
    "messages": [
{'{'}
        "id": "019d6724-1234-...",
        "role": "visitor",
        "content": "Hello, how much does it cost?",
        "contentLanguage": "en",
        "translatedContent": "Cześć, ile to kosztuje?",
        "translatedLanguage": "pl",
        "isAutoReply": false,
        "createdAt": "2026-04-11T14:25:30+00:00"
      },
{'{'}
        "id": "019d6724-5678-...",
        "role": "ai",
        "content": "Our plans start at €19/month...",
        "isAutoReply": true,
        "createdAt": "2026-04-11T14:25:32+00:00"
      }
    ]
  }
}

POST /conversations/{'{'}id}/messages

向对话发送消息。消息将通过聊天小部件实时传递给访客。

请求体

{'{'}
  "content": "Thanks for reaching out! We'll process your request.",
  "role": "system"
}

响应 (201 Created)

{'{'}
  "data": {'{'}
    "id": "019d6725-abcd-...",
    "role": "system",
    "content": "Thanks for reaching out!",
    "createdAt": "2026-04-11T14:35:00+00:00"
  }
}

PATCH /conversations/{'{'}id}

更新对话的状态或分配。

请求体

{'{'}
  "status": "closed"
}

GET /billing/balance

获取您当前的套餐和余额。

响应

{'{'}
  "data": {'{'}
    "plan": "pro",
    "creditBalance": 4500000,
    "totalCreditsAdded": 10000000
  }
}

CRM 集成

轮询新对话并将访客数据（姓名、邮箱、语言）同步到您的 CRM。使用对话 ID 作为外部引用。

自动跟进

对话关闭后，通过 API 发送跟进消息："感谢您的咨询！还有什么我们可以帮助的吗？"

webhook 替代方案

在传出 webhook 可用之前，定期轮询对话 endpoint 以检测新消息或状态变更。

批量操作

关闭所有超过 7 天的对话，根据外部逻辑分配对话给客服，或导出对话历史用于数据分析。