Drücken Sie die Eingabetaste.
Holen Sie sich Ihre Daten.

Schnellstart

Drei Schritte von Null zur ersten Antwort. Jede Anfrage ist an ein Widget gebunden und mit einem Bearer‑Token authentifiziert.

1. Geben Sie einen Token ausDashboard → API‑Tokens: ein Name, ein optionaler Ablauf und die von Ihnen benötigten Bereiche. Ein Token gehört zu genau einem Widget. Das Klartext‑Token wird einmal angezeigt; Smartbtn speichert nur einen Einweg‑Hash, sodass ein verlorenes Token nicht wiederhergestellt, sondern nur widerrufen und erneut ausgestellt werden kann.
2. Aktivieren Sie die Widget‑APIAktivieren Sie in den Widget‑Einstellungen „Widget‑API zulassen (JS und REST)“. Durch die Ausgabe eines Tokens wird dieser Schalter für Sie nicht umgelegt.
3. Senden Sie die erste AnfrageDas Token geht nur in den Header Authorization – niemals in die URL.

# Listen Sie die Chats des Widgets auf
curl -H "Authorization: Bearer $SMARTBTN_TOKEN" \
     https://smartbtn.me/api/v1/chats

// 200 OK · Cursor-Paginierung
{
  "data": [ { "id": 48211, "status": "open", "last_message_at": "2026-10-17T09:41:12+03:00" }, … ],
  "next_cursor": "eyJpZCI6NDgyMTB9"   // null — auf der letzten Seite
}

Authentifizierung

Drei Wege, je nachdem, wer wen anruft. Der Zugriff wird standardmäßig verweigert: kein Bereich – kein Aufruf.

Den Schalter vergessen die Leute

„Widget‑API zulassen (JS und REST)“ in den Widget‑Einstellungen öffnet sowohl die REST‑API als auch die Widget‑JS‑API. Durch die Ausgabe eines Tokens wird dieser nicht aktiviert. Die Bereiche eines vorhandenen Schlüssels können im Dashboard (API‑Tokens → Schlüssel → Bereiche bearbeiten) ohne erneute Ausstellung bearbeitet werden – Integrationen funktionieren weiterhin.

Voreinstellungen

Bereiche

53 Routenbereiche, plus ein bedingter und ein reservierter. Eine Anfrage ist nur dann erfolgreich, wenn das Token den Routenbereich (oder eine aufgelistete Alternative) enthält.

Endpunkte

Die gesamte öffentliche Oberfläche in einer Liste. Filtern Sie nach Ressource, suchen Sie nach Pfad, klicken Sie auf eine Zeile, um eine fertige Locke zu kopieren.

Pfade sind relativ zu https://smartbtn.me/api. Für Schreibvorgänge sind Content‑Type: application/json und X‑Smartbtn‑Idempotency‑Key erforderlich. Die Gruppe compat ist eine Kompatibilitätsebene für Teams, die von einer anderen Chat‑Plattform wechseln.

Webhooks

Ein signierter JSON-POST an Ihre URL, wann immer ein abonniertes Ereignis stattfindet. Verwalten Sie Abonnements über /v1/webhook‑subscriptions oder im 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"
  }
}

Lieferkopfzeilen

Signaturüberprüfung

HMAC‑SHA256 des Rohkörpers (Bytes wie empfangen, vor der JSON‑Analyse) mit Ihrem Endpunktgeheimnis; in konstanter Zeit vergleichen. Das Geheimnis wird einmalig angezeigt, wenn das Abonnement erstellt wird; Drehen Sie es mit POST /v1/webhook‑subscriptions/{id}/rotate‑secret.

// Node.js · Beispielsweise ist das Geheimnis ein Platzhalter
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; }

Wiederholungen und Bestellung

• Bis zu 4 Versuche (der erste Versand plus 3 Wiederholungsversuche), Backoff min(60, 2^attempt × 5) s – etwa 10, 20, 40 s.
• Nicht‑2xx oder ein Timeout gelten als Fehlversuch. Fehlgeschlagene Zustellungen können mit POST /v1/webhook‑subscriptions/{id}/redeliver erneut gesendet werden – gleicher Idempotenzschlüssel, neue Zustellungs‑ID.
• Die Lieferung erfolgt mindestens einmal und ist nicht bestellt. Die Nutzlasten sind minimal – IDs, keine vollständigen Datensätze; Details über die REST‑API abrufen.

JS API

Geben Sie das, was Sie bereits über den Besucher wissen, direkt an den Agenten weiter. Anrufe werden nur von der in den Widget‑Einstellungen festgelegten Domäne angenommen.

smartbtn_widget_api.setContactInfo(info)

Legt die Kontaktdaten des Besuchers fest. Der Agent sieht es so, als ob der Besucher das Einführungsformular ausgefüllt hätte. Name, Telefon und E‑Mail spielen bei Smartbtn eine besondere Rolle – daher eine separate Methode.

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

smartbtn_widget_api.setCustomData(fields)

Alle zusätzlichen Daten für das Infofeld rechts in der Agent‑App. Rufen Sie es so oft auf, wie Sie möchten – im offenen Dialog aktualisiert sich das Panel in Echtzeit. Felder werden in Array‑Reihenfolge angezeigt.

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

Wechseln Sie das Widget‑Thema im Handumdrehen, ohne die Seite neu zu laden (classic, minimal, capsule, liquid) oder steuern Sie das Chat‑Fenster programmgesteuert. Für eine permanente projektspezifische Anpassung übergeben Sie dieselben Felder an PATCH /v1/widget/settings.

// JS API · Wechseln Sie den Skin auf der Seite in Echtzeit
smartbtn_widget_api.setSkin("minimal");
smartbtn_widget_api.setSkin("capsule", { capsuleTitle: "Smartbtn AI", capsuleSubtitle: „Antworten in ~1 s“ });

// REST API · PATCH /v1/widget/settings (Umfang 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 rund um die Uhr“
}

Support‑agent API

Ein automatisierter Supportmitarbeiter bearbeitet die Ticketwarteschlange und Kundenchats: Er nimmt einen Chat auf, antwortet als Ihr menschlicher Supportmitarbeiter und schließt das Ticket. Aus, bis der Widget‑Besitzer es einschaltet.

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":"Fertig, der Zugriff wurde wiederhergestellt."}'

KI‑API

Alles, was der KI‑Bereich des Dashboards macht: Assistenten, Ihre eigenen Anbieterschlüssel, Wissensdatenbank, Selbstlernen mit Rollback, Wünsche, Probleme, Bedarfssignale und ein Assistent in Ihrer App.

Tarifbegrenzungen

Pro Token zwei Zähler: Lese- und Schreibvorgänge werden getrennt gezählt, sodass das Abfragen niemals das Schreibbudget verschlingt.

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 und /v1/ai/assistant/account‑link haben ihre eigenen Zähler; Die Support‑Agent‑API kann über eine Widget-Überschreibung verfügen.

Fehler

Jeder Fehler ist RFC‑7807 application/problem+json: ein maschinenlesbarer Status und Grund, ein für Menschen lesbares 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"
}

Der Hauptteil nennt „required_scopes“ und gibt an, wo sie gewährt werden sollen. Eine erneute Schlüsselausgabe ist nicht erforderlich.

Idempotenz

Netzwerke scheitern. Ein Schlüssel macht einen wiederholten Schreibversuch sicher: Derselbe Vorgang wird nie zweimal angewendet.

• Senden Sie X‑Smartbtn‑Idempotency‑Key bei jedem POST / PATCH / PUT / DELETE: eine neue UUID für einen neuen Vorgang, den gleichen Schlüssel für einen Wiederholungsversuch desselben.
• Vorgänge, die in OpenAPI mit x‑idempotency: erforderlich gekennzeichnet sind: kein Schlüssel → 400, der Schlüssel wurde innerhalb von 24 Stunden wiederverwendet → 409 (kein zwischengespeicherter Erfolg).
• Nicht sicher, ob es durchgegangen ist? Lesen Sie zuerst den Zustand. Ändern Sie den Schlüssel niemals automatisch; Respekt Retry‑After.
• Ein 502 von einem Upstream‑Anbieter gibt den Schlüssel frei – versuchen Sie es erneut mit demselben Schlüssel.

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"}'
# Netzwerkfehler? Wiederholen Sie den Vorgang mit demselben $KEY

Changelog

Änderungen an der öffentlichen API und den Webhooks im Jahr 2026. Alles unten ist additiv und bleibt in v1.

WordPress‑Plugin

Das Widget auf einer WordPress‑Site, ohne den Theme‑Code zu berühren.

Codebeispiele

Listen Sie jeden Chat mit Aktivität seit Ihrer letzten Umfrage auf – indem Sie dem Cursor bis zum Ende folgen.

# erste Seite
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 – mit next_cursor aus der Antwort
curl -G https://smartbtn.me/api/v1/chats \
  -H "Authorization: Bearer $SMARTBTN_TOKEN" \
  --data-urlencode "cursor=eyJpZCI6NDgyMDd9"