Consulter l'état d'un message (polling)

GET

/api/message/{messageId}

Production

Retourne l’enveloppe du message avec son état courant. Tant que le traitement est en cours, le statut HTTP est 202 ; il passe à 200 dès qu’un état stable est atteint (answered, pending, failed, closed).

Le corps est identique à celui livré par le webhook : un seul parseur suffit côté client.

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).

Responses

200

État stable atteint : answered, pending, failed ou closed.

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

required

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

string

thread

required

object

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

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
null

object

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

sent_at

string | null format: date-time

error

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

string

Examples

Réponse envoyée automatiquement

{
  "id": "0196c3f2-1111-7000-8000-000000000001",
  "thread": {
    "id": "demo-thread-001",
    "title": "Question sur la commande 1042"
  },
  "state": "answered",
  "answer": "Bonjour Jeanne, votre commande 1042 a été expédiée ce matin…",
  "confidence": 84,
  "suggestions": [],
  "contact": {
    "id": "0196c3f2-2222-7000-8000-000000000002",
    "name": "Jeanne Martin",
    "email": "jeanne@example.com",
    "phone": null
  },
  "sent_at": "2026-08-13T10:12:33+02:00"
}

En attente d'une validation humaine

{
  "id": "0196c3f2-1111-7000-8000-000000000001",
  "thread": {
    "id": "demo-thread-001",
    "title": "Question sur la commande 1042"
  },
  "state": "pending",
  "answer": null,
  "confidence": 52,
  "required_action": null,
  "suggestions": [
    {
      "rank": 1,
      "content": "Bonjour Jeanne, pouvez-vous préciser…"
    },
    {
      "rank": 2,
      "content": "Bonjour, votre commande 1042…"
    }
  ],
  "contact": {
    "id": "0196c3f2-2222-7000-8000-000000000002",
    "name": "Jeanne Martin",
    "email": "jeanne@example.com",
    "phone": null
  }
}

En attente — action à réaliser par votre équipe

{
  "id": "0196c3f2-1111-7000-8000-000000000001",
  "thread": {
    "id": "demo-thread-001",
    "title": "Réexpédition de la commande 1042"
  },
  "state": "pending",
  "answer": null,
  "confidence": 88,
  "required_action": {
    "summary": "Réexpédier la commande 1042 à l'adresse confirmée par le client."
  },
  "suggestions": [
    {
      "rank": 1,
      "content": "Bonjour Jeanne, nous avons procédé à la réexpédition de votre commande 1042…"
    },
    {
      "rank": 2,
      "content": "Bonjour Jeanne, votre nouvelle expédition est enregistrée…"
    }
  ],
  "contact": {
    "id": "0196c3f2-2222-7000-8000-000000000002",
    "name": "Jeanne Martin",
    "email": "jeanne@example.com",
    "phone": null
  }
}

Traitement en échec

{
  "id": "0196c3f2-1111-7000-8000-000000000001",
  "thread": {
    "id": "demo-thread-001",
    "title": null
  },
  "state": "failed",
  "error": "Le fournisseur IA est momentanément indisponible.",
  "contact": null
}

202

Traitement toujours en cours (state = processing).

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

required

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

string

thread

required

object

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

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

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
null

object

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

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

Ressource inconnue pour cet agent.

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