驱动你的工作区
用你自己的代码。

§ 00REST API 是什么

EasyLiveChat 在 /api/v1/* 暴露一个 REST API，让外部代码 —— 你自己的后端、CRM 集成、Zapier 或 n8n 流程、迁移脚本 —— 无需真人客服登录即可读写你的工作区。每次调用都使用控制台中生成、限定为你租户的 API 密钥进行身份验证。

如果你调用过 Stripe、Slack 或 GitHub API，这里的工作方式一样：Authorization 头中携带长期有效的密钥令牌，请求和响应使用 JSON，HTTP 状态码可预测。

API 密钥永远不会承载双因素或密码 —— 这就是它的本意。它是一种你嵌入到其他软件中的凭据，让那个软件代表你的租户行事，只能使用你授予它的权限范围。

§ 01套餐可用性

REST API 在所有付费套餐都可用，14 天试用期内同样开放。按调用收费不存在。

试用结束后，API 切换为只读模式 —— 写入返回 402，直到工作区升级为止。读取继续可用，保证你的历史导出不会中断。

§ 02身份验证

在以下位置创建密钥 https://app.livechattools.com/settings/api-keys. 选择集成实际所需的最小权限集合。你可以随时在同一页面撤销密钥 —— 立刻失效，且不影响客服的控制台或移动端登录。

在每次请求中传递密钥，作为 Bearer 令牌或通过 x-api-key：

Authorization: Bearer plk_<your-key>
# — or, equivalently —
x-api-key: plk_<your-key>

在把密钥接入任何系统之前先验证它是否工作 —— /me 会回显你的权限范围和租户：

curl https://api.livechattools.com/api/v1/me \
  -H "Authorization: Bearer plk_<your-key>"

原始密钥仅在创建时显示一次。丢了？撤销它并新建一个 —— 没有办法找回原值。

§ 03权限范围

每次请求都会检查权限范围。仅含 :read 范围的密钥永远不会意外改动数据 —— 适合只读仪表盘、BI 导出或分析管道。

最小权限原则 —— 每个集成使用独立密钥。报表流水线上泄露的只读密钥造成的损失，远小于整个技术栈共享的一把「万能」密钥。

§ 04接口端点

所有路径都以 /api/v1 为根。响应为 JSON。时间为 ISO 8601 UTC。

GET /api/v1/me

回显密钥身份和租户信息。无需任何权限范围 —— 适合连通性测试。

curl https://api.livechattools.com/api/v1/me \
  -H "Authorization: Bearer plk_<key>"

{
  "apiKeyId": "ck...",
  "scopes": ["conversations:read","messages:write"],
  "tenant": { "id": "...", "name": "Acme", "slug": "acme", "planTier": "GROWTH" }
}

GET /api/v1/conversations

按最新优先列出对话。所有过滤条件均为可选。

• ?status= OPEN · SNOOZED · CLOSED
• ?channel= WIDGET · WHATSAPP · TELEGRAM · MESSENGER · INSTAGRAM
• ?limit= 1–200，默认 50
• ?cursor= 上一页最后一行的 id

curl "https://api.livechattools.com/api/v1/conversations?status=OPEN&limit=50" \
  -H "Authorization: Bearer plk_<key>"

{
  "data": [
    { "id":"...", "sourceChannel":"WHATSAPP", "status":"OPEN",
      "lastMessagePreview":"hi there", "lastMessageAt":"..." }
  ],
  "nextCursor": "..."
}

GET /api/v1/conversations/:id

获取一个对话，附带其联系人。

GET /api/v1/conversations/:id/messages

对话的分页消息历史，最新优先。

curl "https://api.livechattools.com/api/v1/conversations/<id>/messages?limit=50" \
  -H "Authorization: Bearer plk_<key>"

POST /api/v1/conversations/:id/messages

在对话中发送外发消息。会按真人客服回复的方式分发到对应渠道（小部件、WhatsApp、Telegram、Messenger、Instagram）。

curl -X POST "https://api.livechattools.com/api/v1/conversations/<id>/messages" \
  -H "Authorization: Bearer plk_<key>" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Your order has shipped." }'

# → 201 Created
{ "message": { "id":"...", "senderType":"AGENT", "body":"Your order has shipped.", "createdAt":"..." } }

senderAgentId 是可选的 —— 如果省略，消息会归属到工作区中第一个活跃的 OWNER 或 ADMIN。当你希望某个特定的机器人账号出现在对话中时，请显式传 id。

PATCH /api/v1/conversations/:id

更新对话状态（OPEN · SNOOZED · CLOSED）或其指派客服。传 assignedAgentId: null 表示取消指派。

curl -X PATCH "https://api.livechattools.com/api/v1/conversations/<id>" \
  -H "Authorization: Bearer plk_<key>" \
  -H "Content-Type: application/json" \
  -d '{ "status": "CLOSED" }'

GET /api/v1/contacts

列出工作区中的联系人。?q= 匹配姓名、邮箱或电话。

curl "https://api.livechattools.com/api/v1/contacts?q=acme" \
  -H "Authorization: Bearer plk_<key>"

§ 05分页

所有列表端点都使用游标分页。响应结构为：

{
  "data": [ /* up to ?limit= rows */ ],
  "nextCursor": "<id of last row>"   // or null when there are no more
}

要获取下一页，将 nextCursor 作为 ?cursor= 传给下一次请求。当 nextCursor 为 null 时，已到末尾。

§ 06错误

错误总会返回带有错误码以及（在有帮助时）人类可读消息的 JSON 主体。HTTP 状态码反映含义：

§ 07Webhook（伴侣）

REST API 适合按你的节奏拉取和推送。要在 EasyLiveChat 这边发生事情时收到推送 —— 新客户消息、对话关闭、客服加入 —— 请在「设置 → Webhooks」中配置出站 Webhook。

通过 POST /api/v1/conversations/:id/messages 发送的消息也会触发 message.created Webhook，因此如果你既有发送方又有监听方的集成，会看到自己写入的内容通过 Webhook 通道反弹回来。

§ 08速率限制

每个租户每条路径每分钟最多 240 次请求，所有密钥共享。触达上限时返回 429 并附带 Retry-After 头。

如果你的集成确实需要更高上限（批量导入、群发消息），请发邮件给客服 —— 我们会为你的租户提高额度。