Guides

Le cycle d'une conversation

Déroulé type, dans une page web

Charger l'avatar : GET /v1/avatars/{avatar_id} avec la clé publique. Vous recevez le nom, les couleurs et les liens des fichiers du visage. Pas de décompte : l'affichage n'est pas facturé.
Ouvrir la conversation : POST /v1/conversations avec la clé publique, à la première action du visiteur (un clic, une question), pas au simple affichage de la page. Vous recevez un jeton de conversation.
Converser : les questions, la voix et la transcription se font avec ce jeton (Authorization: Bearer <jeton>).
Renouveler le jeton avant ses 30 minutes : POST /v1/conversations/{id}/token. Pas de décompte.
Terminer (facultatif) : POST /v1/conversations/{id}/end. La conversation ne peut plus être reprise et son jeton n'est plus accepté.

Les durées

	Durée	Au-delà
Jeton de conversation	30 minutes	`401 token_expired` : renouveler avant, ou rouvrir avec `resume`
Conversation	10 minutes au plus depuis l'ouverture, renouvellements compris	`410 conversation_expired` : en ouvrir une nouvelle, décomptée
Liens des fichiers du visage	1 heure (`assets_expire_at`)	`403 invalid_link` : relire la fiche de l'avatar

Reprendre une conversation

Si le visiteur recharge la page, rouvrez avec l'identifiant de la conversation précédente :

Code
POST /v1/conversations
Authorization: Bearer pk_test_…
Content-Type: application/json

{ "resume": "conv_9xk2…" }

Réponse	Cas	Décompte
`200`	conversation du même déploiement, non terminée, active il y a moins de 30 minutes	non (`counted: false`)
`201`	sinon : une nouvelle conversation est ouverte	oui (`counted: true`)

Comme une conversation dure 10 minutes au plus, la reprise ne vaut que dans ces 10 minutes.

La réponse d'ouverture

Code
{
  "conversation_id": "conv_9xk2…",
  "token": "eyJ…",
  "expires_at": "2026-10-27T18:42:00Z",
  "counted": true,
  "quota": { "used": 412, "limit": 500, "period": "2026-10" },
  "voice": { "allowed": true, "reason": null, "units": 1, "spoken": 0 }
}

quota : conversations décomptées du mois, et votre forfait.
voice.allowed vaut false quand la voix n'est pas disponible ; voice.reason dit pourquoi (voir Voix et décompte).
Au-delà du forfait, la conversation s'ouvre quand même, en écrit seul : aucun refus, aucun dépassement facturé.

Fichiers du visage

Les liens de assets sont signés et valables 1 heure. Ne les fabriquez pas et ne les gardez pas : relisez la fiche de l'avatar pour en obtenir de nouveaux. Un lien modifié ou expiré reçoit 403 invalid_link.

Le SDK Twimi fait tout cela pour vous ; ces détails servent à une intégration directe.

Last modified on October 28, 2026

Clés et jetons Voix et décompte