Appuyez sur Entrée.
Récupérez vos données.

Démarrage rapide

Trois étapes de zéro à la première réponse. Chaque demande est liée à un widget et authentifiée avec un jeton de porteur.

1. Émettre un jetonTableau de bord → Jetons API : un nom, une expiration facultative et les étendues dont vous avez besoin. Un jeton appartient à exactement un widget. Le jeton en texte brut est affiché une fois ; Smartbtn stocke uniquement un hachage unidirectionnel, de sorte qu'un jeton perdu ne peut pas être récupéré, mais seulement révoqué et réémis.
2. Activez l'API du widgetDans les paramètres du widget, activez «Autoriser l'API du widget (JS et REST)». L'émission d'un jeton ne fait pas basculer ce commutateur à votre place.
3. Envoyez la première demandeLe jeton va uniquement dans l'en‑tête Authorization - jamais dans l'URL.

# lister les chats du widget
curl -H "Authorization: Bearer $SMARTBTN_TOKEN" \
     https://smartbtn.me/api/v1/chats

// 200 OK · pagination du curseur
{
  "data": [ { "id": 48211, "status": "open", "last_message_at": "2026-10-17T09:41:12+03:00" }, … ],
  "next_cursor": "eyJpZCI6NDgyMTB9"   // null — sur la dernière page
}

Authentification

Trois chemins, selon qui appelle qui. L'accès est refusé par défaut : pas de portée, pas d'appel.

Le changement que les gens oublient

«Autoriser l'API du widget (JS et REST)» dans les paramètres du widget ouvre à la fois l'API REST et l'API JS du widget. L'émission d'un jeton ne l'active pas. Les étendues d'une clé existante peuvent être modifiées dans le tableau de bord (jetons API → clé → Modifier les étendues) sans la réémettre : les intégrations continuent de fonctionner.

Préréglages

Portées

53 étendues d'itinéraire, plus une conditionnelle et une réservée. Une requête ne réussit que si le jeton contient la portée de la route (ou une alternative répertoriée).

Points de terminaison

Tout le public apparaît dans une seule liste. Filtrez par ressource, recherchez par chemin, cliquez sur une ligne pour copier une boucle prête.

Les chemins sont relatifs à https://smartbtn.me/api. Les écritures nécessitent Content‑Type : application/json et X‑Smartbtn‑Idempotency‑Key. Le groupe compat est une couche de compatibilité pour les équipes migrant depuis une autre plateforme de chat.

Webhooks

Un POST JSON signé à votre URL chaque fois qu'un événement souscrit se produit. Gérez les abonnements via /v1/webhook‑subscriptions ou dans le tableau de bord.

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

En‑têtes de livraison

Vérification des signatures

HMAC‑SHA256 du corps brut (octets tels que reçus, avant analyse JSON) avec le secret de votre point de terminaison ; comparer en temps constant. Le secret est affiché une fois, lors de la création de l'abonnement ; faites‑le pivoter avec POST /v1/webhook‑subscriptions/{id}/rotate‑secret.

// Node.js · exemple, le secret est un espace réservé
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; }

Nouvelles tentatives et commande

• Jusqu'à 4 tentatives (le premier envoi plus 3 tentatives), intervalle de min(60, 2^attempt × 5) s — environ 10, 20, 40 s.
• Un non‑2xx ou un délai d'attente compte comme une tentative échouée. Les livraisons échouées peuvent être renvoyées avec POST /v1/webhook‑subscriptions/{id}/redeliver — même clé d'idempotence, nouvel identifiant de livraison.
• La livraison est effectuée au moins une fois et non commandée. Les charges utiles sont minimes : des identifiants, pas des enregistrements complets ; récupérer les détails via l'API REST.

JS API

Transmettez ce que vous savez déjà sur le visiteur directement à l'agent. Les appels sont acceptés uniquement à partir du domaine défini dans les paramètres du widget.

smartbtn_widget_api.setContactInfo(info)

Définit les données de contact du visiteur. L'agent voit cela comme si le visiteur avait rempli le formulaire d'introduction. Le nom, le téléphone et l'e‑mail jouent un rôle particulier dans Smartbtn — d'où une méthode distincte.

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

smartbtn_widget_api.setCustomData(fields)

Toutes les données supplémentaires pour le panneau d'informations à droite de l'application agent. Appelez‑le aussi souvent que vous le souhaitez : dans une boîte de dialogue ouverte, le panneau est mis à jour en temps réel. Les champs sont affichés dans l'ordre du tableau.

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

Changez le thème du widget à la volée sans recharger la page (classic, minimal, capsule, liquid) ou contrôlez la fenêtre de discussion par programme. Pour une personnalisation permanente par projet, transmettez les mêmes champs à PATCH /v1/widget/settings.

// JS API · changer de skin sur la page en temps réel
smartbtn_widget_api.setSkin("minimal");
smartbtn_widget_api.setSkin("capsule", { capsuleTitle: "Smartbtn AI", capsuleSubtitle: "Réponses dans ~1 s" });

// REST API · PATCH /v1/widget/settings (portée 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": "En ligne 24h/24 et 7j/7"
}

Support‑agent API

Un agent d'assistance automatisé gère la file d'attente des tickets et les discussions avec les clients : prend une conversation, répond en tant qu'opérateur d'assistance humain, ferme le ticket. Désactivé jusqu'à ce que le propriétaire du widget l'active.

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": "Terminé, l'accès a été restauré."}'

API IA

Tout ce que fait la section IA du tableau de bord : assistants, vos propres clés de fournisseur, base de connaissances, auto‑apprentissage avec restauration, souhaits, problèmes, signaux de demande et un assistant dans votre application.

Limites de taux

Par jeton, deux compteurs : les lectures et les écritures sont comptées séparément, de sorte que l'interrogation ne consomme jamais le budget d'écriture.

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 et /v1/ai/assistant/account‑link ont leurs propres compteurs ; l'API de l'agent de support peut avoir un remplacement par widget.

Erreurs

Chaque erreur est RFC‑7807 application/problem+json : un statut et une raison lisibles par machine, un détail lisible par l'homme.

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

Le corps nomme les require_scopes et où les accorder. Pas besoin de réémettre la clé.

Idempotence

Les réseaux échouent. Une clé sécurise une nouvelle tentative d'écriture : la même opération n'est jamais appliquée deux fois.

• Envoyez X‑Smartbtn‑Idempotency‑Key à chaque POST / PATCH / PUT / DELETE : un nouvel UUID pour une nouvelle opération, la même clé pour une nouvelle tentative de la même.
• Opérations marquées x‑idempotency : obligatoire dans OpenAPI : pas de clé → 400, la clé réutilisée dans les 24 heures → 409 (pas de succès en cache).
• Vous n'êtes pas sûr que cela soit passé ? Lisez d'abord l'état. Ne changez jamais la clé automatiquement ; respectez Retry‑After.
• Un 502 d'un fournisseur en amont libère la clé – réessayez avec la même clé.

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"}'
# erreur réseau ? répéter avec le même $KEY

Changelog

Modifications apportées à l'API publique et aux webhooks en 2026. Tout ce qui suit est additif et reste dans v1.

Plugin WordPress

Le widget sur un site WordPress sans toucher au code du thème.

Exemples de codes

Répertoriez toutes les discussions ayant eu une activité depuis votre dernier sondage, en suivant le curseur jusqu'à la fin.

# première page
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 — avec next_cursor de la réponse
curl -G https://smartbtn.me/api/v1/chats \
  -H "Authorization: Bearer $SMARTBTN_TOKEN" \
  --data-urlencode "cursor=eyJpZCI6NDgyMDd9"