API SmileTalk — démarrer

Construisez sur le moteur d’arbre décisionnel SmileTalk : arbres, runtime de conversation headless et webhooks. Développez gratuitement en bac à sable, puis passez en production avec un essai de 14 jours et l’abonnement Développeurs.

1. Bac à sable gratuit

Les clés de test st_test_… sont gratuites et exécutent même des arbres en brouillon. Idéal pour développer et valider votre intégration avant de payer.

2. Essai 14 jours

Dans votre espace, cliquez sur « Démarrer l’essai 14 jours » pour activer les clés st_live_… en production, sans carte bancaire.

3. Clés test vs live

st_test_ = bac à sable (gratuit, arbres en brouillon). st_live_ = production (arbres publiés) ; nécessite un essai actif ou un abonnement.

4. Abonnement

À la fin de l’essai, l’abonnement Développeurs maintient l’accès live. Sans abonnement actif, un appel live répond 402 — la clé reste valide, l’accès reprend dès régularisation.

Premier appel — l’API de données en 2 minutes

# 1. Profil du cabinet (coordonnées, adresse, horaires)
curl https://votre-domaine.tld/v1/practice \
  -H "Authorization: Bearer st_test_VOTRE_CLE"

# 2. Intentions de rendez-vous du mois (canaux widget + runtime)
curl "https://votre-domaine.tld/v1/appointments?from=2026-06-01T00:00:00Z&limit=50" \
  -H "Authorization: Bearer st_test_VOTRE_CLE"

La clé secrète (st_live_… / st_test_…) ne quitte jamais votre serveur. Ne l’embarquez ni dans une page web, ni dans une app mobile, ni dans un dépôt public. Côté navigateur, utilisez exclusivement la surface /v1/public/{token}/… avec le jeton publiable du chatbot (celui du snippet d’intégration) — il ne donne accès qu’aux données publiques de son arbre. C’est la surface que consomme le widget officiel : vous pouvez reproduire son comportement avec ces seules routes. Limites : 600 requêtes/minute par clé secrète ; 120 requêtes/minute par jeton publiable et par IP (429 avec Retry-After).

Exemple serveur — JavaScript (Node)

// La clé secrète vit dans l'environnement de VOTRE serveur.
const res = await fetch('https://votre-domaine.tld/v1/practice/status', {
  headers: { Authorization: 'Bearer ' + process.env.SMILETALK_KEY },
})
const status = await res.json()
// status.open_now → afficher « Ouvert / Fermé actuellement » sur le site du cabinet

Exemple serveur — PHP

$ch = curl_init('https://votre-domaine.tld/v1/appointments?limit=20');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . getenv('SMILETALK_KEY')]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$appointments = json_decode(curl_exec($ch), true);
// $appointments['data'] : intentions de RDV (source widget + runtime)

Intégration custom côté navigateur (jeton publiable)

Le widget officiel n’utilise QUE ces routes — votre propre interface peut faire pareil, sans aucune clé secrète :

// 1. Config publique (coordonnées, parcours localisé, réglages)
const cfg = await (await fetch('/v1/public/' + TOKEN + '/config')).json()

// 2. Démarrer une conversation runtime, puis avancer pas à pas
const start = await (await fetch('/v1/public/' + TOKEN + '/conversations', {
  method: 'POST', headers: { 'Content-Type': 'application/json' }, body: '{}',
})).json()
// start.current_block : bloc neutre à rendre (kind, text, options…)

// 3. Soumettre le formulaire (email + persistance côté SmileTalk)
await fetch('/v1/public/' + TOKEN + '/form-submissions', {
  method: 'POST', headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ fields: { sujet: 'RDV', email: 'patient@ex.fr', consentement: 'oui' } }),
})

Erreurs à gérer

Code	Sens	Quoi faire
`401`	Clé manquante/inconnue/révoquée	Vérifier l’en-tête `Authorization: Bearer`
`402` `api_subscription_required`	Clé `live` sans abonnement/essai API actif	Démarrer l’essai ou souscrire ; la clé reste valide
`403`	Scope insuffisant, clé bornée à un autre arbre, ou origine refusée	Vérifier scopes/domaines autorisés
`404`	Ressource inexistante ou hors de votre organisation	Vérifier l’identifiant
`409` / `422`	État incompatible / arbre invalide à la publication	Lire `error.details`
`429`	600 req/min par clé secrète ; 120 req/min par jeton publiable + IP	Respecter `Retry-After`
`503` `widget_inactive`	Surface publique : essai expiré / abonnement inactif du cabinet	Régulariser côté cabinet ; données conservées

Surfaces de l’API & statut

Surface	Auth	Statut
`/v1/*`	Clé secrète `Bearer` (serveur uniquement)	Contrat officiel — versionné, documenté dans la référence ci-dessous
`/v1/public/{token}/*`	Jeton publiable (navigateur)	Contrat officiel — consommé par le widget officiel et les modules CMS
`/api/widget/*`, `/api/send-email`, `/api/conversations/{id}/upload`	Chemins historiques	Legacy temporaire — servis à l’identique (mêmes traitements, même billing) pour les pages déjà déployées. Usage surveillé, date de retrait non fixée : n’y construisez aucune nouvelle intégration.

Intégration CMS sans code : plugins officiels WordPress et Joomla, module Drupal — à télécharger dans votre espace (chatbot → onglet Intégration). Ils ne stockent que le jeton publiable (jamais de clé secrète) et chargent le widget officiel, client de /v1/public.

Obtenir une clé API →