Guides

Voix et décompte

Ce qui est compté

Une conversation ouverte compte pour 1, même si l'avatar ne parle pas.
Chaque tranche de 5 réponses parlées compte pour une conversation de plus (réglable par déploiement, voir votre contrat).
Une réponse parlée = un tour (turn) qui a reçu au moins une voix. Les morceaux d'une même réponse, envoyés avec le même turn, ne comptent qu'une fois.
Les réponses écrites ne comptent pas.
L'affichage de l'avatar (GET /v1/avatars/…) et la reprise d'une conversation (resume) ne comptent pas.

Réponses parlées dans la conversation	Conversations décomptées
0 à 5	1
6 à 10	2
11 à 15	3

Les tours

Chaque question posée à /messages ouvre un nouveau tour. Son numéro arrive dans l'événement done :

Code
data: {"type": "done", "text": "Oui, nous avons trois SUV.", "turn": 3,
       "voice": {"allowed": true, "reason": null, "units": 1, "spoken": 2}}

Redonnez ce turn à chaque morceau envoyé à /speech pour cette réponse :

Code
{ "text": "Oui, nous avons trois SUV.", "lang": "fr", "turn": 3 }

Sans turn : le dernier tour de la conversation (0 avant la première question, par exemple pour un message d'accueil).
Un tour pas encore donné par /messages est refusé : 400 invalid_request.
Un tour reçoit 1 500 caractères de voix au plus, tous morceaux compris (environ 1 min 30). Un morceau qui ferait dépasser est refusé (409, X-Twimi-Voice-Reason: reponse) et rien n'est dit : découpez vos réponses en conséquence.
Un morceau fait 2 000 caractères au plus ; les liens et le balisage Markdown sont retirés avant lecture.

La réponse de /speech porte trois en-têtes pour suivre le décompte :

En-tête	Valeur
`X-Twimi-Chars`	caractères lus
`X-Twimi-Turn`	tour compté
`X-Twimi-Units`	conversations décomptées pour cette conversation

Quand la voix n'est pas disponible

L'écrit continue toujours. Le champ voice (à l'ouverture et dans done) dit si la voix est disponible ; sinon, affichez la réponse seulement et cachez le micro.

`voice.reason`	Cause	Ce qui se passe
`forfait`	forfait du mois atteint	les nouvelles conversations s'ouvrent en écrit seul ; une conversation en cours ne peut pas entamer une nouvelle tranche de réponses parlées
`conversation`	plafond de réponses parlées de la conversation (si votre déploiement en a un)	la conversation continue par écrit
`fusible`	trafic anormal (plus de 3 fois le volume habituel du jour)	voix suspendue par précaution ; Twimi vous contacte pour la rétablir
`formule`	formule Avatar SDK	la voix est la vôtre : pas de voix Twimi
`reponse`	sur `/speech` : la réponse dépasserait 1 500 caractères de voix	ce morceau n'est pas dit

Sur /speech et /transcriptions, un refus prend la forme 409 voice_limit_reached, avec l'en-tête X-Twimi-Voice-Reason. La suite d'une réponse déjà commencée reste acceptée, dans la limite de 1 500 caractères.

Jamais de dépassement facturé

Au-delà du forfait, rien n'est bloqué et aucun dépassement n'est facturé : l'avatar passe à l'écrit. Twimi est alerté à 80 % et à 100 % du forfait ; l'envoi de ces alertes par e-mail à votre contact arrive prochainement.

Suivre sa consommation

GET /v1/usage?period=AAAA-MM, avec la clé secrète :

Code
{
  "period": "2026-10",
  "deployment": { "id": "dep_…", "client": "concession", "formula": "agent" },
  "conversations": { "opened": 1102, "counted": 1288 },
  "limit": 2000
}

opened : conversations ouvertes ; counted : conversations décomptées du forfait. D'où counted ≥ opened.

Transcription

POST /v1/conversations/{id}/transcriptions transcrit la question orale du visiteur.

Corps multipart/form-data : audio (webm, ogg, mp4, m4a, wav ou mp3 ; 5 Mo au plus) et lang, facultatif.
Une question orale dure 30 secondes au plus : coupez l'enregistrement au-delà.
Le son n'est jamais conservé.

Code
curl -s -X POST $TWIMI/conversations/conv_9xk2…/transcriptions \
  -H "Authorization: Bearer $JETON" \
  -F audio=@question.webm -F lang=fr

Last modified on October 28, 2026

Cycle d'une conversation Erreurs et limites