Nhấn Enter.
Nhận dữ liệu của bạn.

Bắt đầu nhanh

Ba bước từ số 0 đến câu trả lời đầu tiên. Mọi yêu cầu được gắn với một tiện ích và được xác thực bằng mã thông báo mang.

1. Phát hành mã thông báoTrang tổng quan → Mã thông báo API: tên, thời hạn sử dụng tùy chọn và phạm vi bạn cần. Mã thông báo thuộc về chính xác một tiện ích. Mã thông báo văn bản thuần túy được hiển thị một lần; Smartbtn chỉ lưu trữ hàm băm một chiều, do đó không thể khôi phục mã thông báo bị mất mà chỉ có thể thu hồi và phát hành lại.
2. Bật API tiện íchTrong cài đặt tiện ích, hãy bật «Cho phép API tiện ích (JS và REST)». Việc phát hành mã thông báo không giúp bạn chuyển đổi công tắc này.
3. Gửi yêu cầu đầu tiênMã thông báo chỉ đi vào tiêu đề Ủy quyền — không bao giờ đi vào URL.

# liệt kê các cuộc trò chuyện của tiện ích
curl -H "Authorization: Bearer $SMARTBTN_TOKEN" \
     https://smartbtn.me/api/v1/chats

// 200 OK · phân trang con trỏ
{
  "data": [ { "id": 48211, "status": "open", "last_message_at": "2026-10-17T09:41:12+03:00" }, … ],
  "next_cursor": "eyJpZCI6NDgyMTB9"   // null — ở trang cuối cùng
}

Xác thực

Ba con đường, tùy ai gọi ai. Quyền truy cập bị từ chối theo mặc định: không có phạm vi - không có lệnh gọi.

Công tắc người ta quên

«Cho phép API tiện ích (JS và REST)» trong cài đặt tiện ích sẽ mở cả API REST và API JS tiện ích. Việc phát hành mã thông báo không kích hoạt nó. Bạn có thể chỉnh sửa phạm vi của khóa hiện có trong trang tổng quan (mã thông báo API → khóa → Chỉnh sửa phạm vi) mà không cần phát hành lại — quá trình tích hợp vẫn tiếp tục hoạt động.

cài đặt trước

Phạm vi

53 phạm vi tuyến đường, cộng với một tuyến có điều kiện và một tuyến dành riêng. Yêu cầu chỉ thành công nếu mã thông báo giữ phạm vi tuyến đường (hoặc một giải pháp thay thế được liệt kê).

Điểm cuối

Toàn bộ bề mặt công khai trong một danh sách. Lọc theo tài nguyên, tìm kiếm theo đường dẫn, nhấp vào một hàng để sao chép một lọn tóc đã sẵn sàng.

Các đường dẫn có liên quan đến https://smartbtn.me/api. Viết cần có Content‑Type: application/json và X‑Smartbtn‑Idempotency‑Key. Nhóm compat là lớp tương thích dành cho các nhóm chuyển từ nền tảng trò chuyện khác.

Webhook

JSON POST đã ký vào URL của bạn bất cứ khi nào xảy ra sự kiện đã đăng ký. Quản lý đăng ký qua /v1/webhook‑subscriptions hoặc trong trang tổng quan.

{
  "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"
  }
}

Tiêu đề phân phối

Xác minh chữ ký

HMAC‑SHA256 của phần nội dung thô (byte đã nhận, trước khi phân tích cú pháp JSON) cùng với bí mật điểm cuối của bạn; so sánh trong thời gian không đổi. Bí mật được hiển thị một lần khi đăng ký được tạo; xoay nó bằng POST /v1/webhook‑subscriptions/{id}/rotate‑secret.

// Node.js · ví dụ, bí mật là một phần giữ chỗ
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; }

Thử lại và đặt hàng

• Tối đa 4 lần thử (lần gửi đầu tiên cộng với 3 lần thử lại), thời gian chờ min(60, 2^attempt × 5) s — khoảng 10, 20, 40 giây.
• Không phải 2xx hoặc thời gian chờ được tính là một lần thử không thành công. Việc gửi không thành công có thể được gửi lại bằng POST /v1/webhook‑subscriptions/{id}/redeliver — cùng một khóa tạm thời, id gửi mới.
• Việc giao hàng được thực hiện ít nhất một lần và không được đặt hàng. Tải trọng tối thiểu - id, không phải bản ghi đầy đủ; tìm nạp thông tin chi tiết thông qua API REST.

JS API

Chuyển thẳng những gì bạn đã biết về khách truy cập tới đại lý. Cuộc gọi chỉ được chấp nhận từ miền được đặt trong cài đặt tiện ích.

smartbtn_widget_api.setContactInfo(info)

Đặt dữ liệu liên hệ của khách truy cập. Nhân viên coi như thể khách truy cập đã điền vào mẫu giới thiệu. Tên, số điện thoại và email đóng một vai trò đặc biệt trong Smartbtn — do đó có một phương thức riêng biệt.

Smartbtn_api.setClientInfo({
  name: "Alex Morgan",
  email: "email@example.com",
  phone: "+17584987855",
  description: "Description text"
});

smartbtn_widget_api.setCustomData(fields)

Mọi dữ liệu bổ sung cho bảng thông tin ở bên phải ứng dụng tổng đài viên. Gọi nó bao nhiêu lần tùy thích — trong hộp thoại mở, bảng điều khiển sẽ cập nhật theo thời gian thực. Các trường được hiển thị theo thứ tự mảng.

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()

Chuyển đổi chủ đề tiện ích một cách nhanh chóng mà không cần tải lại trang (classic, minimal, capsule, liquid) hoặc điều khiển cửa sổ trò chuyện theo chương trình. Để tùy chỉnh vĩnh viễn cho mỗi dự án, hãy chuyển các trường tương tự tới PATCH /v1/widget/settings.

// JS API · chuyển đổi giao diện trên trang trong thời gian thực
smartbtn_widget_api.setSkin("minimal");
smartbtn_widget_api.setSkin("capsule", { capsuleTitle: "Smartbtn AI", capsuleSubtitle: "Trả lời sau ~1 giây" });

// REST API · PATCH /v1/widget/settings (phạm vi 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": "Trực tuyến 24/7"
}

Support‑agent API

Một nhân viên hỗ trợ tự động xử lý hàng đợi yêu cầu và cuộc trò chuyện của khách hàng: thực hiện trò chuyện, trả lời với tư cách là nhà điều hành hỗ trợ con người của bạn, đóng yêu cầu. Tắt cho đến khi chủ sở hữu widget bật nó lên.

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">Xong, quyền truy cập đã được khôi phục."}'

API AI

Mọi thứ mà phần AI của bảng điều khiển thực hiện: trợ lý, khóa nhà cung cấp của riêng bạn, cơ sở kiến ​​thức, tự học với khôi phục, mong muốn, vấn đề, tín hiệu nhu cầu và trợ lý bên trong ứng dụng của bạn.

Giới hạn tỷ lệ

Mỗi mã thông báo có hai bộ đếm: số lần đọc và ghi được tính riêng biệt, vì vậy việc bỏ phiếu không bao giờ ngốn ngân sách ghi.

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 và /v1/ai/assistant/account‑link có bộ đếm riêng; API tác nhân hỗ trợ có thể ghi đè theo từng tiện ích.

Lỗi

Mọi lỗi đều là RFC‑7807 application/problem+json: trạng thái và lý do mà máy có thể đọc được, chi tiết mà con người có thể đọc được.

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"
}

Tên nội dung bắt buộc_scopes và nơi cấp chúng. Không cần phải cấp lại chìa khóa.

sự bình thường

Mạng thất bại. Một khóa giúp việc ghi lại được an toàn: cùng một thao tác không bao giờ được áp dụng hai lần.

• Gửi X‑Smartbtn‑Idempotency‑Key trên mỗi POST / PATCH / PUT / DELETE: một UUID mới cho một thao tác mới, cùng một khóa để thử lại cùng một thao tác.
• Các hoạt động được đánh dấu x‑idempotency: bắt buộc trong OpenAPI: không có khóa → 400, khóa được sử dụng lại trong vòng 24 giờ → 409 (không phải là thành công được lưu vào bộ nhớ đệm).
• Không chắc chắn nó đã đi qua? Đọc trạng thái đầu tiên. Không bao giờ tự động thay đổi chìa khóa; tôn trọng Thử lại sau.
• Một 502 từ nhà cung cấp thượng nguồn sẽ giải phóng khóa — thử lại bằng chính khóa đó.

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"}'
# lỗi mạng à? lặp lại với cùng $KEY

Changelog

Những thay đổi đối với API công khai và webhooks vào năm 2026. Mọi thứ bên dưới đều mang tính bổ sung và vẫn ở v1.

Plugin WordPress

Tiện ích trên trang web WordPress mà không cần chạm vào mã chủ đề.

Mẫu mã

Liệt kê mọi cuộc trò chuyện có hoạt động kể từ cuộc thăm dò cuối cùng của bạn — theo con trỏ đến cuối.

# trang đầu tiên
curl -G https://smartbtn.me/api/v1/chats \
  -H "Authorization: Bearer $SMARTBTN_TOKEN" \
  --data-urlencode "updated_since=2026-10-17T09:00:00+03:00"

# tiếp theo - với next_cursor từ phản hồi
curl -G https://smartbtn.me/api/v1/chats \
  -H "Authorization: Bearer $SMARTBTN_TOKEN" \
  --data-urlencode "cursor=eyJpZCI6NDgyMDd9"