按 Enter 键。
获取您的数据。

快速入门

从零到第一个答案的三个步骤。每个请求都与一个小部件绑定，并使用不记名令牌进行身份验证。

1. 发行代币仪表板 → API 令牌：名称、可选的到期日和您需要的范围。一个令牌只属于一个小部件。纯文本令牌显示一次； Smartbtn 仅存储单向哈希，因此丢失的令牌无法恢复 - 只能撤销并重新发行。
2. 打开小部件 API在小部件设置中，打开“允许小部件 API（JS 和 REST）”。发行代币并不会为您打开这个开关。
3. 发送第一个请求令牌仅进入 Authorization 标头，而不会进入 URL。

# 列出小部件的聊天记录
curl -H "Authorization: Bearer $SMARTBTN_TOKEN" \
     https://smartbtn.me/api/v1/chats

// 200 OK · 光标分页
{
  "data": [ { "id": 48211, "status": "open", "last_message_at": "2026-10-17T09:41:12+03:00" }, … ],
  "next_cursor": "eyJpZCI6NDgyMTB9"   // null — 在最后一页
}

认证

三种路径，取决于谁打电话给谁。默认情况下拒绝访问：无范围 — 无调用。

人们忘记的开关

小部件设置中的“允许小部件 API（JS 和 REST）”会同时打开 REST API 和小部件 JS API。发行令牌并不会启用它。可以在仪表板中编辑现有密钥的范围（API 令牌 → 密钥 → 编辑范围）无需重新颁发 — 集成继续运行。

预设

范围

53 个路由范围，加上 1 个条件范围和 1 个保留范围。仅当令牌包含路由范围（或列出的替代方案）时，请求才会成功。

端点

整个公共表面都在一个列表中。按资源过滤，按路径搜索，单击一行复制准备好的卷曲。

路径相对于 https://smartbtn.me/api。写入需要 Content‑Type: application/json 和 X‑Smartbtn‑Idempotency‑Key。 compat 组是一个兼容层，供从其他聊天平台迁移的团队使用。

网络钩子

每当订阅事件发生时，都会将签名的 JSON POST 发送到您的 URL。通过 /v1/webhook‑subscriptions 或在仪表板中管理订阅。

{
  "id": "evt_01JAB3K9Q7",
  "type": "ticket.created",
  "data": {
    "button_guid": "b_3f9c2e",
    "ticket_number": 10482,
    "chat_id": 48211,
    "client_id": 9134,
    "reason": "human_request",
    "priority": "high",
    "sla_hours": 4,
    "source": "chat",
    "created_at": "2026-10-17T10:15:00+03:00"
  }
}

交付标头

签名验证

原始正文（JSON 解析之前收到的字节）的 HMAC‑SHA256 以及您的端点密钥；在恒定时间内进行比较。创建订阅时，秘密会显示一次；使用 POST /v1/webhook‑subscriptions/{id}/rotate‑secret 旋转它。

// Node.js · 例如，秘密是一个占位符
import crypto from 'node:crypto';

function verify(rawBody, header, secret) {
  const expected = 'sha256=v1:' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(expected), b = Buffer.from(header || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// PHP
$expected = 'sha256=v1:' . hash_hmac('sha256', file_get_contents('php://input'), $secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_SMARTBTN_SIGNATURE'] ?? '')) { http_response_code(401); exit; }

重试并订购

• 最多 4 次尝试（第一次发送加上 3 次重试），回退 min(60, 2^attempt × 5) 秒 — 大约 10、20、40 秒。
• 非 2xx 或超时算作失败的尝试。失败的交付可以使用 POST /v1/webhook‑subscriptions/{id}/redeliver 重新发送 - 相同的幂等密钥、新的交付 ID。
• 交付至少一次并且未订购。有效负载是最小的——ID，而不是完整的记录；通过 REST API 获取详细信息。

JS API

将您对访客的已知信息直接传递给代理。仅接受来自小部件设置中设置的域的呼叫。

smartbtn_widget_api.setContactInfo(info)

设置访客的联系数据。代理将其视为访客填写了介绍表格。姓名、电话和电子邮件在 Smartbtn 中发挥着特殊作用 - 因此是一个单独的方法。

Smartbtn_api.setClientInfo({
  name: “亚历克斯·摩根”,
  email: "email@example.com",
  phone: "+17584987855",
  description: "Description text"
});

smartbtn_widget_api.setCustomData(fields)

代理应用程序右侧信息面板的任何额外数据。您可以随意调用它——在打开的对话框中，面板会实时更新。字段按数组顺序显示。

Smartbtn_api.setClientCustomData([
  { title: "Order", content: "#10482 · 3 items", link: "https://shop.example/orders/10482" },
  { title: "Actions", content: "Open customer profile", link: "https://crm.example/c/9134" }
]);

smartbtn_widget_api.setSkin(skin, opts) · open() · close()

动态切换小部件主题，无需重新加载页面（classic、minimal、capsule、liquid）或以编程方式控制聊天窗口。对于永久的每个项目自定义，请将相同的字段传递给 PATCH /v1/widget/settings。

// JS API · 实时切换页面皮肤
smartbtn_widget_api.setSkin("minimal");
smartbtn_widget_api.setSkin("capsule", { capsuleTitle: "Smartbtn AI", capsuleSubtitle: “约 1 秒内回复” });

// REST API · PATCH /v1/widget/settings (范围 widget:write)
{
  "skin": "minimal",
  "widget_header_align": "center",
  "widget_show_operator_avatars": false,
  "widget_show_tabs_bar": false,
  "chat_bg": "#FAF8F5",
  "capsule_title": "Smartbtn AI",
  "capsule_subtitle": “24/7 在线”
}

Support‑agent API

自动化支持代理负责工单队列和客户聊天：进行聊天，作为人工支持操作员进行回答，关闭工单。关闭直到小部件所有者将其打开。

curl -X POST https://smartbtn.me/api/v1/support/chats/48211/reply \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Smartbtn-Idempotency-Key: $(uuidgen)" \
  -d '{"text":"完成，访问已恢复。"}'

人工智能应用程序接口

仪表板的人工智能部分所做的一切：助手、您自己的提供商密钥、知识库、带回滚的自学、愿望、问题、需求信号和应用程序内的助手。

速率限制

每个令牌有两个计数器：读取和写入是分开计算的，因此轮询永远不会消耗写入预算。

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 12
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0

{ "status": 429, "title": "Too Many Requests", "reason": "rate_limited" }

/v1/ai/assistant/tickets/status 和 /v1/ai/assistant/account‑link 有自己的计数器；支持代理 API 可以覆盖每个小部件。

错误

每个错误都是 RFC‑7807 application/problem+json：机器可读的状态和原因，人类可读的细节。

HTTP/1.1 403 · Content-Type: application/problem+json
{
  "type": "https://smartbtn.me/problems/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Token lacks scope chats:write.",
  "required_scopes": [
    "chats:write"
  ],
  "hint": "Dashboard → API tokens → key → Edit scopes"
}

主体名称 required_scopes 以及授予它们的位置。无需重新颁发密钥。

幂等性

网络失败。密钥使重试写入变得安全：相同的操作永远不会应用两次。

• 每次 POST / PATCH / PUT / DELETE 时发送 X‑Smartbtn‑Idempotency‑Key：新操作的新 UUID，重试相同操作的相同密钥。
• OpenAPI 中标记为 x‑idempotency: required 的操作：无密钥 → 400，密钥在 24 小时内重复使用 → 409（不是缓存的成功）。
• 不确定它通过了吗？首先阅读状态。切勿自动更改密钥；尊重重试后。
• 来自上游提供商的 502 释放密钥 - 使用相同的密钥重试。

KEY=$(uuidgen)
curl -X PATCH https://smartbtn.me/api/v1/widget/settings \
  -H "Authorization: Bearer $SMARTBTN_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Smartbtn-Idempotency-Key: $KEY" \
  -d '{"language":"ru"}'
# 网络错误？使用相同的 $KEY 重复

Changelog

2026 年公共 API 和 Webhook 的更改。以下所有内容都是附加的，并保留在 v1 中。

WordPress 插件

WordPress 网站上的小部件无需触及主题代码。

代码示例

列出自上次投票以来的所有聊天活动 - 跟随光标一直到末尾。

# 第一页
curl -G https://smartbtn.me/api/v1/chats \
  -H "Authorization: Bearer $SMARTBTN_TOKEN" \
  --data-urlencode "updated_since=2026-10-17T09:00:00+03:00"

# next — 响应中的 next_cursor
curl -G https://smartbtn.me/api/v1/chats \
  -H "Authorization: Bearer $SMARTBTN_TOKEN" \
  --data-urlencode "cursor=eyJpZCI6NDgyMDd9"