Press Enter.
Get your data.

Quickstart

Three steps from zero to the first answer. Every request is tied to one widget and authenticated with a bearer token.

1. Issue a tokenDashboard → API tokens: a name, an optional expiry and the scopes you need. A token belongs to exactly one widget. The plain‑text token is shown once; Smartbtn stores only a one‑way hash, so a lost token cannot be recovered — only revoked and re‑issued.
2. Turn on the widget APIIn the widget settings, turn on «Allow widget API (JS and REST)». Issuing a token does not flip this switch for you.
3. Send the first requestThe token goes only into the Authorization header — never into the URL.

# list the widget's chats
curl -H "Authorization: Bearer $SMARTBTN_TOKEN" \
     https://smartbtn.me/api/v1/chats

// 200 OK · cursor pagination
{
  "data": [ { "id": 48211, "status": "open", "last_message_at": "2026-10-17T09:41:12+03:00" }, … ],
  "next_cursor": "eyJpZCI6NDgyMTB9"   // null — on the last page
}

Authentication

Three paths, depending on who calls whom. Access is deny‑by‑default: no scope — no call.

The switch people forget

«Allow widget API (JS and REST)» in the widget settings opens both the REST API and the widget JS API. Issuing a token does not enable it. The scopes of an existing key can be edited in the dashboard (API tokens → key → Edit scopes) without re‑issuing it — integrations keep working.

Presets

Scopes

53 route scopes, plus one conditional and one reserved. A request succeeds only if the token holds the route scope (or a listed alternative).

Endpoints

The whole public surface in one list. Filter by resource, search by path, click a row to copy a ready curl.

Paths are relative to https://smartbtn.me/api. Writes need Content‑Type: application/json and X‑Smartbtn‑Idempotency‑Key. The compat group is a compatibility layer for teams moving from another chat platform.

Webhooks

A signed JSON POST to your URL whenever a subscribed event happens. Manage subscriptions via /v1/webhook‑subscriptions or in the dashboard.

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

Delivery headers

Signature verification

HMAC‑SHA256 of the raw body (bytes as received, before JSON parsing) with your endpoint secret; compare in constant time. The secret is shown once, when the subscription is created; rotate it with POST /v1/webhook‑subscriptions/{id}/rotate‑secret.

// Node.js · example, the secret is a placeholder
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; }

Retries and order

• Up to 4 attempts (the first send plus 3 retries), backoff min(60, 2^attempt × 5) s — about 10, 20, 40 s.
• Non‑2xx or a timeout counts as a failed attempt. Failed deliveries can be resent with POST /v1/webhook‑subscriptions/{id}/redeliver — same idempotency key, new delivery id.
• Delivery is at‑least‑once and not ordered. Payloads are minimal — ids, not full records; fetch details via the REST API.

JS API

Pass what you already know about the visitor straight to the agent. Calls are accepted only from the domain set in the widget settings.

smartbtn_widget_api.setContactInfo(info)

Sets the visitor's contact data. The agent sees it as if the visitor filled in the intro form. Name, phone and email play a special role in Smartbtn — hence a separate method.

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

smartbtn_widget_api.setCustomData(fields)

Any extra data for the info panel on the right of the agent app. Call it as often as you like — in an open dialog the panel updates in real time. Fields are shown in array order.

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

Switch the widget theme on the fly without reloading the page (classic, minimal, capsule, liquid) or control the chat window programmatically. For permanent per‑project customization, pass the same fields to PATCH /v1/widget/settings.

// JS API · switch skin on the page in real time
smartbtn_widget_api.setSkin("minimal");
smartbtn_widget_api.setSkin("capsule", { capsuleTitle: "Smartbtn AI", capsuleSubtitle: "Replies in ~1 s" });

// REST API · PATCH /v1/widget/settings (scope 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": "Online 24/7"
}

Support‑agent API

An automated support agent works the ticket queue and customer chats: takes a chat, answers as your human support operator, closes the ticket. Off until the widget owner turns it on.

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":"Done, access has been restored."}'

AI API

Everything the AI section of the dashboard does: assistants, your own provider keys, knowledge base, self‑learning with rollback, wishes, problems, demand signals and an assistant inside your app.

Rate limits

Per token, two counters: reads and writes are counted apart, so polling never eats the write budget.

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 and /v1/ai/assistant/account‑link have their own counters; the support‑agent API can have a per‑widget override.

Errors

Every error is RFC‑7807 application/problem+json: a machine‑readable status and reason, a human‑readable detail.

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

The body names required_scopes and where to grant them. No need to re‑issue the key.

Idempotency

Networks fail. A key makes a retried write safe: the same operation is never applied twice.

• Send X‑Smartbtn‑Idempotency‑Key on every POST / PATCH / PUT / DELETE: a new UUID for a new operation, the same key for a retry of the same one.
• Operations marked x‑idempotency: required in OpenAPI: no key → 400, the key reused within 24 hours → 409 (not a cached success).
• Not sure it went through? Read the state first. Never change the key automatically; respect Retry‑After.
• A 502 from an upstream provider releases the key — retry with the same key.

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"}'
# network error? repeat with the same $KEY

Changelog

Changes to the public API and webhooks in 2026. Everything below is additive and stays in v1.

WordPress plugin

The widget on a WordPress site without touching the theme code.

Code samples

List every chat with activity since your last poll — following the cursor to the end.

# first page
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 — with next_cursor from the response
curl -G https://smartbtn.me/api/v1/chats \
  -H "Authorization: Bearer $SMARTBTN_TOKEN" \
  --data-urlencode "cursor=eyJpZCI6NDgyMDd9"