API Quickstart

The Smartbtn REST API (/api/v1) lets your own systems read and manage chats, contacts, agents, tags, files and stats, and receive webhooks when relevant events happen. Every request is scoped to a single widget and must be authenticated with a bearer token.

Obtaining a token

API tokens are widget-scoped credentials: each token belongs to exactly one widget and carries an explicit list of granted scopes (for example chats:read or messages:write) -- see Authentication & Scopes for the full scope reference. A token is shown to you as plain text exactly once, at issuance time; Smartbtn stores only a one-way hash of it afterwards, so a lost token cannot be recovered -- only revoked and re-issued.

Issue a token yourself from your widget's personal cabinet under API-токены -- pick a name, an expiry (optional), and the scopes the token needs, and the plain-text token is shown to you once, at creation time.

Your first request

Once you have a token, every request needs it in the Authorization header:

curl -H "Authorization: Bearer <token>" https://<host>/api/v1/chats

Replace <token> with the API token issued to you, and <host> with your Smartbtn instance's domain. A successful response returns a cursor-paginated list of chats for that widget: {"data": [...], "next_cursor": "..." | null}. If the token is missing, invalid, or lacks the required scope, the API responds with a 401 or 403 and an RFC-7807 application/problem+json error body instead.

Where to next

• Authentication & Scopes -- token format, signature rotation, full scope list.
• Endpoints -- the full REST reference.
• Webhooks -- events, payloads, signature verification.
• Changelog -- API changes over time.