Notification de fin de traitement (push)

POST

Si le webhook est activé sur l’agent (URL HTTPS + secret), Assilya envoie un POST à votre URL dès qu’un message atteint un état stable — le même corps que GET /api/message/{messageId}, pour un parseur unique.

Signature : X-Assilya-Signature: sha256=<hmac> où hmac = HMAC-SHA256(timestamp + "." + corpsBrut, webhook_secret). Recalculez-la depuis le corps brut de la requête et comparez en temps constant (hash_equals, crypto.timingSafeEqual…).

Livraison : 4 tentatives au maximum — immédiate, puis +60 s, +5 min et +15 min après chaque échec (réponse non-2xx ou délai de 30 s dépassé). Après le 4ᵉ échec la livraison est abandonnée : prévoyez le repli par polling. Répondez 2xx rapidement et traitez le contenu de façon idempotente (id est stable).

Authorizations

• apiKey

Parameters

Header Parameters

X-Assilya-Event

string

Allowed values: message.answered message.pending message.failed

Événement : message.answered, message.pending ou message.failed.

X-Assilya-Message

string

Identifiant du message entrant concerné.

X-Assilya-Timestamp

string

Horodatage Unix (secondes) utilisé dans la signature.

X-Assilya-Signature

string

sha256=<hmac> — signature HMAC-SHA256 du corps.

User-Agent

string

Allowed value: Assilya-Webhook/1.0

Request Body

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

Responses

200

Tout statut 2xx retourné sous 30 secondes vaut accusé de réception et stoppe les relances.