Le cycle de vie d'un message

Vue d’ensemble

1. POST /api/message enregistre le message et répond 202 avec l’état processing.
2. L’agent génère sa réponse : la conversation bascule vers answered (réponse envoyée seule) ou pending (validation humaine requise), ou failed en cas d’erreur.
3. Vous suivez ce basculement par polling ou par webhook — les deux livrent exactement la même enveloppe JSON.
4. Si pending : votre équipe répond depuis la boîte de réception d’Assilya, ou votre application publie la réponse via POST /api/message/{messageId}/answer.

Les cinq états

state	HTTP	Signification	Champs supplémentaires
processing	202	Génération en cours.	contact
answered	200	Réponse envoyée.	answer, confidence, suggestions (vide), contact, sent_at, attachments*
pending	200	En attente de validation humaine.	answer (toujours null), confidence, required_action, suggestions, contact
failed	200	Le traitement a échoué.	error, contact
closed	200	Clôturée sans réponse (depuis la boîte de réception).	—

* uniquement si les pièces jointes sont activées sur l’agent.

confidence est le pourcentage de confiance (0–100) de l’IA ; answer respecte le format de sortie configuré sur l’agent (texte brut, Markdown ou HTML) — voir Agent API.

required_action (état pending uniquement) signale une opération que l’IA ne peut pas effectuer elle-même — réexpédier une commande, rembourser… — sous la forme { "summary": "…" }, rédigée dans la langue de travail de votre entreprise ; null quand la mise en attente ne tient qu’à la confiance (celle-ci peut donc dépasser le seuil de l’agent quand une action est signalée). Réalisez l’action avant de publier la réponse : la publication — comme la clôture depuis la boîte de réception — marque comme traitées toutes les actions en attente de la conversation.

Une action en attente bloque toute réponse automatique

Tant qu’une action signalée n’a pas été traitée, l’IA ne répond plus jamais seule sur cette conversation : chaque nouveau message du client aboutit à pending, quelle que soit la confiance — répondre reviendrait à promettre une opération qu’un humain n’a pas encore effectuée. Le fonctionnement normal reprend une fois la réponse publiée (depuis Assilya ou via l’API) ou la conversation clôturée.

Suivre par polling

GET /api/message/{messageId} répond 202 tant que l’état est processing, puis 200. La plupart des réponses arrivent en moins d’une minute : un intervalle de quelques secondes avec repli progressif convient bien — la limite de 30 requêtes/minute par conversation laisse de la marge. Pour vous épargner le polling, activez le webhook.

Répondre à une conversation « pending »

POST /api/message/{messageId}/answer accepte trois combinaisons :

Corps	Effet	source du message
content seul	Réponse libre rédigée par votre équipe.	human
suggestion seul (rang 1 à 4)	Reprend la suggestion telle quelle.	suggestion_selected
les deux	La suggestion sert de base, content est la version retouchée.	suggestion_edited

Réponses d’erreur à prévoir :

• 409 — la conversation n’est plus pending : quelqu’un a répondu depuis la boîte de réception entre-temps, ou elle a été clôturée. Rechargez l’état avant de retenter.
• 404 — rang de suggestion inexistant pour ce message.
• 502 — sur une conversation dans une langue étrangère, la réponse est traduite automatiquement avant l’envoi ; si la traduction échoue, rien n’est enregistré : retentez.

Un title optionnel donne un sujet au message sortant et sert de titre à la conversation si elle n’en a pas encore.

Titres et pièces jointes

Deux options de l’agent conditionnent le contrat de l’API — désactivées, les champs correspondants sont rejetés (422) :

• « Permettre un titre par message » → champ title (80 caractères max) et subject dans les historiques.
• « Autoriser les pièces jointes » → champ files en multipart/form-data : 10 fichiers max, 10 Mo chacun (PDF, PNG, JPEG, WebP, GIF, CSV, TXT, XLSX, DOCX).

Les pièces jointes des réponses sont livrées en URLs présignées valables 15 minutes (tableau attachments) : téléchargez-les sans en-tête d’authentification, et redemandez l’enveloppe si le lien a expiré.

L’historique complet

Au-delà du suivi d’un message, trois endpoints donnent accès aux conversations : la liste, le détail (statut, titre, tags, notes) et les messages paginés — plus la gestion des tags et des notes internes.

Côté actions à réaliser : chaque conversation porte un booléen requires_action (true tant qu’une action signalée attend d’être traitée), et chaque message de l’historique rappelle son éventuelle required_action avec sa date de traitement (processed_at, null tant qu’elle est en attente).