Premi Invio.
Ottieni i tuoi dati.

Avvio rapido

Tre passi dallo zero alla prima risposta. Ogni richiesta è legata a un widget e autenticata con un token al portatore.

1. Emetti un tokenDashboard → Token API: un nome, una scadenza opzionale e gli ambiti di cui hai bisogno. Un token appartiene esattamente a un widget. Il token in testo semplice viene mostrato una volta; Smartbtn memorizza solo un hash unidirezionale, quindi un token perso non può essere recuperato, ma solo revocato e riemesso.
2. Attiva l'API widgetNelle impostazioni del widget, attiva «Consenti API widget (JS e REST)». L'emissione di un token non attiva questo interruttore per te.
3. Invia la prima richiestaIl token va solo nell'intestazione Autorizzazione e mai nell'URL.

# elenca le chat del widget
curl -H "Authorization: Bearer $SMARTBTN_TOKEN" \
     https://smartbtn.me/api/v1/chats

// 200 OK · impaginazione del cursore
{
  "data": [ { "id": 48211, "status": "open", "last_message_at": "2026-10-17T09:41:12+03:00" }, … ],
  "next_cursor": "eyJpZCI6NDgyMTB9"   // null — nell'ultima pagina
}

Autenticazione

Tre percorsi, a seconda di chi chiama chi. L'accesso è negato per impostazione predefinita: nessun ambito, nessuna chiamata.

Il cambio che la gente dimentica

«Consenti API widget (JS e REST)» nelle impostazioni del widget apre sia l'API REST che l'API JS del widget. L'emissione di un token non lo abilita. Gli ambiti di una chiave esistente possono essere modificati nella dashboard (token API → chiave → Modifica ambiti) senza riemetterla: le integrazioni continuano a funzionare.

Preimpostazioni

Ambiti

53 ambiti di percorso, più uno condizionale e uno riservato. Una richiesta ha esito positivo solo se il token contiene l'ambito della route (o un'alternativa elencata).

Endpoint

Tutta la superficie pubblica in un unico elenco. Filtra per risorsa, cerca per percorso, fai clic su una riga per copiare un ricciolo pronto.

I percorsi sono relativi a https://smartbtn.me/api. Le scritture richiedono Content‑Type: application/json e X‑Smartbtn‑Idempotency‑Key. Il gruppo compat è un livello di compatibilità per i team che si spostano da un'altra piattaforma di chat.

Webhook

Un POST JSON firmato sul tuo URL ogni volta che si verifica un evento sottoscritto. Gestisci gli abbonamenti tramite /v1/webhook‑subscriptions o nella 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"
  }
}

Intestazioni di consegna

Verifica della firma

HMAC‑SHA256 del corpo raw (byte ricevuti, prima dell'analisi JSON) con il segreto dell'endpoint; confrontare in tempo costante. Il segreto viene mostrato una volta, quando viene creata la sottoscrizione; ruotalo con POST /v1/webhook‑subscriptions/{id}/rotate‑secret.

// Node.js · ad esempio, il segreto è un segnaposto
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; }

Riprovare e ordinare

• Fino a 4 tentativi (il primo invio più 3 tentativi), backoff min(60, 2^tentativo × 5) s: circa 10, 20, 40 s.
• Un tentativo diverso da 2xx o un timeout conta come un tentativo fallito. Le consegne non riuscite possono essere rinviate con POST /v1/webhook‑subscriptions/{id}/redeliver: stessa chiave di idempotenza, nuovo ID di consegna.
• La consegna è effettuata almeno una volta e non è stata ordinata. I carichi utili sono minimi: ID, non record completi; recuperare i dettagli tramite l'API REST.

JS API

Passa ciò che già sai sul visitatore direttamente all'agente. Si accettano chiamate solo dal dominio impostato nelle impostazioni del widget.

smartbtn_widget_api.setContactInfo(info)

Imposta i dati di contatto del visitatore. L'agente lo vede come se il visitatore avesse compilato il modulo di presentazione. Nome, telefono ed e‑mail svolgono un ruolo speciale in Smartbtn, quindi un metodo separato.

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

smartbtn_widget_api.setCustomData(fields)

Eventuali dati aggiuntivi per il pannello informativo a destra dell'app dell'agente. Chiamalo tutte le volte che vuoi: in una finestra di dialogo aperta il pannello si aggiorna in tempo reale. I campi vengono visualizzati in ordine di matrice.

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

Cambia il tema del widget al volo senza ricaricare la pagina (classic, minimal, capsule, liquid) o controlla la finestra di chat in modo programmatico. Per la personalizzazione permanente per progetto, passa gli stessi campi a PATCH /v1/widget/settings.

// JS API · cambia skin sulla pagina in tempo reale
smartbtn_widget_api.setSkin("minimal");
smartbtn_widget_api.setSkin("capsule", { capsuleTitle: "Smartbtn AI", capsuleSubtitle: "Risposte entro ~ 1 s" });

// REST API · PATCH /v1/widget/settings (ambito 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 ore su 24, 7 giorni su 7"
}

Support‑agent API

Un agente di supporto automatizzato gestisce la coda dei ticket e le chat dei clienti: avvia una chat, risponde come il tuo operatore di supporto umano, chiude il ticket. Disattivato finché il proprietario del widget non lo attiva.

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":"Fatto, l'accesso è stato ripristinato."}'

API dell'intelligenza artificiale

Tutto ciò che fa la sezione AI della dashboard: assistenti, chiavi del tuo fornitore, knowledge base, autoapprendimento con rollback, desideri, problemi, segnali di domanda e un assistente all'interno della tua app.

Limiti di tariffa

Per token, due contatori: le letture e le scritture vengono conteggiate separatamente, quindi il polling non consuma mai il budget di scrittura.

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 e /v1/ai/assistant/account‑link hanno i propri contatori; l'API dell'agente di supporto può avere un override per widget.

Errori

Ogni errore è RFC‑7807 application/problem+json: uno stato e un motivo leggibili dalla macchina, un dettaglio leggibile dall'uomo.

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

Il corpo nomina gli ambiti_richiesti e dove concederli. Non è necessario riemettere la chiave.

Idempotenza

Le reti falliscono. Una chiave rende sicura la scrittura riprovata: la stessa operazione non viene mai eseguita due volte.

• Invia X‑Smartbtn‑Idempotency‑Key su ogni POST / PATCH / PUT / DELETE: un nuovo UUID per una nuova operazione, la stessa chiave per un nuovo tentativo della stessa.
• Operazioni contrassegnate con x‑idempotenza: richiesta in OpenAPI: nessuna chiave → 400, la chiave riutilizzata entro 24 ore → 409 (non un successo memorizzato nella cache).
• Non sei sicuro che sia andato a buon fine? Leggi prima lo stato. Non cambiare mai la chiave automaticamente; rispettare Retry‑After.
• Un 502 da un fornitore upstream rilascia la chiave: riprova con la stessa chiave.

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"}'
# errore di rete? ripetere con la stessa $KEY

Changelog

Modifiche all'API pubblica e ai webhook nel 2026. Tutto ciò che segue è additivo e rimane in v1.

Plug‑in WordPress

Il widget su un sito WordPress senza toccare il codice del tema.

Esempi di codici

Elenca tutte le chat con attività dal tuo ultimo sondaggio, seguendo il cursore fino alla fine.

# prima pagina
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 - con next_cursor dalla risposta
curl -G https://smartbtn.me/api/v1/chats \
  -H "Authorization: Bearer $SMARTBTN_TOKEN" \
  --data-urlencode "cursor=eyJpZCI6NDgyMDd9"