Naciśnij Enter.
Uzyskaj swoje dane.

Szybki start

Trzy kroki od zera do pierwszej odpowiedzi. Każde żądanie jest powiązane z jednym widżetem i uwierzytelniane za pomocą tokena na okaziciela.

1. Wydaj tokenPanel → Tokeny API: nazwa, opcjonalny okres ważności i potrzebne zakresy. Token należy do dokładnie jednego widgetu. Token w postaci zwykłego tekstu jest wyświetlany raz; Smartbtn przechowuje tylko jednokierunkowy skrót, więc utraconego tokena nie można odzyskać – można go jedynie unieważnić i ponownie wystawić.
2. Włącz API widżetuW ustawieniach widgetu włącz opcję „Zezwalaj na API widgetów (JS i REST)”. Wydanie tokena nie powoduje przełączenia tego przełącznika za Ciebie.
3. Wyślij pierwszą prośbęToken trafia tylko do nagłówka Authorization — nigdy do adresu URL.

# wyświetl listę czatów widżetu
curl -H "Authorization: Bearer $SMARTBTN_TOKEN" \
     https://smartbtn.me/api/v1/chats

// 200 OK · paginacja kursora
{
  "data": [ { "id": 48211, "status": "open", "last_message_at": "2026-10-17T09:41:12+03:00" }, … ],
  "next_cursor": "eyJpZCI6NDgyMTB9"   // null — na ostatniej stronie
}

Uwierzytelnianie

Trzy ścieżki, w zależności od tego, kto do kogo dzwoni. Dostęp jest domyślnie odmowy: brak zakresu — brak połączenia.

Przełącznik, o którym ludzie zapominają

«Zezwól na API widgetów (JS i REST)» w ustawieniach widgetu otwiera zarówno API REST, jak i API widgetu JS. Wydanie tokena nie umożliwia takiej możliwości. Zakresy istniejącego klucza można edytować w panelu kontrolnym (tokeny API → klucz → Edytuj zakresy) bez ponownego wydawania – integracje działają dalej.

Ustawienia wstępne

Zakresy

53 zakresy tras, plus jeden warunkowy i jeden zarezerwowany. Żądanie powiedzie się tylko wtedy, gdy token zawiera zakres trasy (lub wymienioną alternatywę).

Punkty końcowe

Cała powierzchnia publiczna na jednej liście. Filtruj według zasobu, szukaj według ścieżki, kliknij wiersz, aby skopiować gotowy zawinięcie.

Ścieżki są zależne od https://smartbtn.me/api. Zapisy wymagają Content‑Type: application/json i X‑Smartbtn‑Idempotency‑Key. Grupa compat to warstwa zgodności dla zespołów przenoszących się z innej platformy czatu.

Haki internetowe

Podpisany JSON POST na Twój adres URL za każdym razem, gdy nastąpi subskrybowane wydarzenie. Zarządzaj subskrypcjami poprzez /v1/webhook‑subscriptions lub w panelu kontrolnym.

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

Nagłówki dostawy

Weryfikacja podpisu

HMAC‑SHA256 surowej treści (bajty w postaci otrzymanej, przed analizą JSON) z sekretem punktu końcowego; porównać w stałym czasie. Sekret jest pokazywany jednorazowo podczas tworzenia subskrypcji; obróć go za pomocą POST /v1/webhook‑subscriptions/{id}/rotate‑secret.

// Node.js · na przykład sekret jest symbolem zastępczym
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; }

Ponów próbę i zamów

• Do 4 prób (pierwsza wysyłka plus 3 ponowne próby), opóźnienie min(60, 2^attempt × 5) s — około 10, 20, 40 s.
• Wartość inna niż 2xx lub przekroczenie limitu czasu liczy się jako nieudana próba. Nieudane dostawy można wysłać ponownie za pomocą POST /v1/webhook‑subscriptions/{id}/redeliver — ten sam klucz idempotencji, nowy identyfikator dostawy.
• Dostawa odbywa się co najmniej raz i nie jest zamawiana. Ładunki są minimalne — identyfikatory, a nie pełne rekordy; pobierz szczegóły za pośrednictwem interfejsu API REST.

JS API

Przekaż wszystko, co już wiesz o gościu, bezpośrednio agentowi. Połączenia akceptowane są wyłącznie z domeny ustawionej w ustawieniach widgetu.

smartbtn_widget_api.setContactInfo(info)

Ustawia dane kontaktowe odwiedzającego. Agent widzi to tak, jakby odwiedzający wypełnił formularz wprowadzający. Imię i nazwisko, telefon i e‑mail odgrywają w Smartbtn szczególną rolę — stąd osobna metoda.

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

smartbtn_widget_api.setCustomData(fields)

Wszelkie dodatkowe dane do panelu informacyjnego po prawej stronie aplikacji agenta. Nazywaj go tak często, jak chcesz — w otwartym oknie dialogowym panel aktualizuje się w czasie rzeczywistym. Pola są wyświetlane w kolejności tablicowej.

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

Zmień motyw widżetu w locie, bez ponownego ładowania strony (classic, minimal, capsule, liquid) lub programowo kontroluj okno czatu. Aby trwale dostosować projekt do potrzeb, przekaż te same pola do PATCH /v1/widget/settings.

// JS API · przełączaj skórkę na stronie w czasie rzeczywistym
smartbtn_widget_api.setSkin("minimal");
smartbtn_widget_api.setSkin("capsule", { capsuleTitle: "Smartbtn AI", capsuleSubtitle: „Odpowiedzi za ~1 s” });

// REST API · PATCH /v1/widget/settings (zakres 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 godziny na dobę, 7 dni w tygodniu”
}

Support‑agent API

Zautomatyzowany agent wsparcia obsługuje kolejkę zgłoszeń i czaty z klientami: bierze udział w czacie, odpowiada jako operator wsparcia technicznego, zamyka zgłoszenie. Wyłączone, dopóki właściciel widżetu go nie włączy.

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":"Gotowe, dostęp został przywrócony."}'

API AI

Wszystko, co robi sekcja AI na pulpicie nawigacyjnym: asystenci, własne klucze dostawców, baza wiedzy, samokształcenie z wycofywaniem, życzenia, problemy, sygnały zapotrzebowania i asystent w Twojej aplikacji.

Limity stawek

Na token przypadają dwa liczniki: odczyty i zapisy, więc odpytywanie nigdy nie pochłania budżetu zapisu.

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 i /v1/ai/assistant/account‑link mają własne liczniki; interfejs API agenta wsparcia może mieć zastąpienie poszczególnych widżetów.

Błędy

Każdy błąd to RFC‑7807 application/problem+json: status i przyczyna czytelne dla maszyny, szczegóły czytelne dla człowieka.

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

Treść zawiera nazwy wymagane_zakresy i miejsce ich przyznania. Nie ma potrzeby ponownego wydawania klucza.

Idempotencja

Sieci zawodzą. Klucz sprawia, że ​​ponowna próba zapisu jest bezpieczna: ta sama operacja nigdy nie jest wykonywana dwukrotnie.

• Wysyłaj X‑Smartbtn‑Idempotency‑Key przy każdym POST/PATCH/PUT/DELETE: nowy UUID dla nowej operacji, ten sam klucz dla ponownej próby tego samego.
• Operacje oznaczone x‑idempotency: wymagane w OpenAPI: brak klucza → 400, klucz ponownie użyty w ciągu 24 godzin → 409 (nie jest to sukces zapisany w pamięci podręcznej).
• Nie jesteś pewien, czy przeszło? Najpierw przeczytaj stan. Nigdy nie zmieniaj klucza automatycznie; szanuj opcję Ponów próbę po.
• 502 od dostawcy wyższego szczebla zwalnia klucz — spróbuj ponownie, używając tego samego klucza.

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"}'
# błąd sieci? powtórz z tym samym $KEY

Changelog

Zmiany w publicznym API i webhookach w 2026 roku. Wszystko poniżej ma charakter addytywny i pozostaje w wersji v1.

Wtyczka WordPressa

Widget na stronie WordPress bez dotykania kodu motywu.

Próbki kodu

Wypisz każdy czat z aktywnością od czasu ostatniej ankiety — podążając za kursorem do końca.

# pierwsza strona
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 — z next_cursor z odpowiedzi
curl -G https://smartbtn.me/api/v1/chats \
  -H "Authorization: Bearer $SMARTBTN_TOKEN" \
  --data-urlencode "cursor=eyJpZCI6NDgyMDd9"