Нажмите Энтер.
Получите данные.

Быстрый старт

Три шага от нуля до первого ответа. Каждый запрос привязан к одному виджету и авторизован bearer‑токеном.

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, и JS API виджета. Выпуск токена его не включает. Скоупы существующего ключа меняются в кабинете (API‑токены → ключ → «Изменить скоупы») без перевыпуска — интеграции продолжают работать.

Пресеты

Скоупы

53 скоупа маршрутов, плюс один условный и один зарезервированный. Запрос проходит, только если у токена есть скоуп маршрута (или указанная альтернатива).

Эндпоинты

Вся публичная поверхность в одном списке. Фильтр по ресурсу, поиск по пути, клик по строке — готовый curl в буфере.

Пути — относительно https://smartbtn.me/api. Записи требуют Content‑Type: application/json и X‑Smartbtn‑Idempotency‑Key. Группа compat — слой совместимости для переезда с другой чат‑платформы.

Вебхуки

Подписанный JSON POST на ваш адрес, когда происходит событие из подписки. Подписки — через /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"
  }
}

Заголовки доставки

Проверка подписи

HMAC‑SHA256 от сырого тела (байты как пришли, до разбора JSON) секретом подписки; сравнение — за постоянное время. Секрет показывается один раз при создании подписки; ротация — 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 доставки.
• Доставка «хотя бы раз» и без гарантии порядка. Полезная нагрузка минимальна — идентификаторы, а не копии записей; детали забирайте через REST.

JS API

Передайте оператору то, что вы уже знаете о посетителе. Вызовы принимаются только с домена из настроек виджета.

smartbtn_widget_api.setContactInfo(info)

Задаёт контактные данные посетителя. Оператор видит их так, будто посетитель сам заполнил форму. Имя, телефон и email в 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":"Готово, доступ восстановлен."}'

ИИ API

Всё, что делает раздел ИИ в кабинете: ассистенты, свои ключи провайдеров, база знаний, самообучение с откатом, пожелания, проблемы, сигналы спроса и ассистент внутри вашего приложения.

Лимиты

На каждый токен — два счётчика: чтение и запись считаются отдельно, поэтому опрос не съедает бюджет записи.

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 — свои счётчики; для Support‑agent 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 и подсказка, где выдать скоуп. Перевыпускать ключ не нужно.

Идемпотентность

Сеть подводит. Ключ делает повтор записи безопасным: одна операция не выполнится дважды.

• Передавайте X‑Smartbtn‑Idempotency‑Key в каждом POST / PATCH / PUT / DELETE: новый UUID — для новой операции, тот же ключ — для повтора той же.
• Операции с x‑idempotency: required в OpenAPI: нет ключа → 400, ключ повторён в течение 24 часов → 409 (а не закешированный успех).
• Не уверены, прошла ли запись? Сначала прочитайте состояние. Не меняйте ключ автоматически; соблюдайте Retry‑After.
• Ответ 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

Изменения публичного API и вебхуков в 2026 году. Всё ниже — добавления, версия остаётся 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_cursor из ответа
curl -G https://smartbtn.me/api/v1/chats \
  -H "Authorization: Bearer $SMARTBTN_TOKEN" \
  --data-urlencode "cursor=eyJpZCI6NDgyMDd9"