Publier la réponse validée par un humain

POST

/api/message/{messageId}/answer

• Production

Réservé aux conversations à l’état pending. Trois façons de répondre :

• content seul — réponse libre rédigée par votre équipe ;
• suggestion seul (rang 1 à 4) — reprend telle quelle l’une des suggestions générées par l’IA ;
• les deux — la suggestion sert de base et content est la version retouchée par l’humain.

Sur une conversation dans une autre langue que celle de l’entreprise, la réponse est traduite automatiquement avant publication ; un échec de traduction renvoie 502 et rien n’est enregistré. Si le service IA est temporairement indisponible (délai d’attente, surcharge du fournisseur), la réponse est 503 — rien n’est enregistré non plus, réessayez plus tard.

Si l’enveloppe pending porte une required_action (réexpédition, remboursement…), réalisez cette action avant de publier la réponse : la publication la marque automatiquement comme traitée.

L’en-tête X-Assilya-Message fixe l’identifiant du message sortant créé par cet appel.

Authorizations

• apiKey

Parameters

Path Parameters

messageId

required

string

Identifiant du message entrant : la valeur passée via X-Assilya-Message, ou l’UUID v7 généré par Assilya (champ id des réponses).

Header Parameters

X-Assilya-Message

string

<= 191 characters

Votre identifiant de message (191 caractères max, unique par agent). Renvoyé dans id ; un doublon est rejeté.

Request Body^required

content et/ou suggestion — au moins l’un des deux.

object

content

Réponse libre. Seule : réponse humaine. Combinée à suggestion : version retouchée de la suggestion choisie.

string

<= 4000 characters

suggestion

Rang de la suggestion à utiliser telle quelle.

integer

>= 1 <= 4

title

Sujet du message sortant (si l’option est activée) ; sert aussi de titre à la conversation si elle n’en a pas encore.

string

<= 80 characters

files

Pièces jointes de la réponse (mêmes règles que la soumission).

Array<string>

<= 10 items

Variante JSON — sans pièces jointes (réservées au multipart).

object

content

string

<= 4000 characters

suggestion

integer

>= 1 <= 4

title

string

<= 80 characters

Responses

200

Réponse publiée — l’enveloppe repasse à l’état answered.

Enveloppe commune aux endpoints Messages et au webhook. Les champs présents dépendent de state :

state	Champs supplémentaires
processing	contact
pending	answer (toujours null), confidence, required_action, suggestions, contact
answered	answer, confidence, suggestions (vide), contact, sent_at, attachments*
failed	error, contact
closed	— (enveloppe nue : clôturée sans réponse)

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

object

id

required

Identifiant du message entrant (le vôtre, ou un UUID v7 généré).

string

thread

required

object

id

Identifiant de la conversation.

string

title

Titre généré par l’IA (peut arriver après coup).

string | null

state

required

string

Allowed values: processing pending answered failed closed

answer

La réponse, dans le format de sortie configuré sur l’agent (texte brut, Markdown ou HTML). null à l’état pending.

string | null

confidence

Pourcentage de confiance de l’IA.

integer | null

<= 100

required_action

État pending uniquement. Action opérationnelle que l’IA ne peut pas exécuter elle-même (réexpédition, remboursement, annulation…) : votre équipe la réalise avant de publier la réponse via POST …/answer — la publication marque comme traitées toutes les actions en attente de la conversation. Tant qu’une action reste en attente, l’IA ne publie plus aucune réponse automatique sur la conversation : un message ultérieur non signalé porte alors la dernière action encore en attente. null quand la mise en attente ne tient qu’à la confiance et qu’aucune action n’est en attente ; la confiance peut alors dépasser le seuil de l’agent.

object

summary

Description de l’action à réaliser, dans la langue de travail de l’entreprise.

string | null

suggestions

Suggestions à faire valider (état pending uniquement, sinon vide).

Array<object>

object

rank

integer

>= 1 <= 4

content

string

attachments

Array<object>

object

id

string format: uuid

filename

string

mime

string

size

Taille en octets.

integer

url

URL présignée de téléchargement, valable 15 minutes.

string

contact

One of:

object

object

id

Identifiant du contact côté agent — à renvoyer via X-Assilya-User-Id pour les messages suivants.

string | null

name

string | null

email

string | null

phone

string | null

null

null

sent_at

string | null format: date-time

error

Cause de l’échec (état failed uniquement).

string

401

Clé API absente ou en-tête Authorization mal formé.

object

error

Message d’erreur lisible, dans la langue de l’agent.

string

403

Clé invalide ou révoquée, agent inactif ou d’un autre type, ou clé utilisée sur l’URL d’un autre espace.

object

error

Message d’erreur lisible, dans la langue de l’agent.

string

404

Message introuvable, ou rang de suggestion inexistant pour ce message.

object

error

Message d’erreur lisible, dans la langue de l’agent.

string

409

La conversation n’est pas (ou plus) à l’état pending — réponse déjà publiée par un autre canal, ou conversation clôturée.

object

error

Message d’erreur lisible, dans la langue de l’agent.

string

422

Corps de requête invalide (erreurs de validation Laravel).

object

message

string

errors

object

key

additional properties

Array<string>

429

Limites de débit dépassées. Plafonds appliqués simultanément : 30/min par conversation, 200/min par agent, 120/min par IP et 1 000/min par espace (valeur par défaut).

object

error

Message d’erreur lisible, dans la langue de l’agent.

string

502

Échec de la traduction automatique — rien n’a été enregistré.

object

error

Message d’erreur lisible, dans la langue de l’agent.

string

503

Service IA temporairement indisponible — la traduction automatique n’a pas pu être réalisée, rien n’a été enregistré. Réessayez plus tard.

object

error

Message d’erreur lisible, dans la langue de l’agent.

string