Soumettre un message client

POST

/api/message

• Production

Enregistre un message entrant et déclenche la génération de la réponse. Répond immédiatement 202 avec l’état processing : la réponse de l’IA arrive de façon asynchrone (polling ou webhook).

Les en-têtes X-Assilya-* permettent de fixer vos propres identifiants (conversation, message, utilisateur) : Assilya vous les renvoie tels quels et ils servent de clés dans les URLs. À défaut, des UUID v7 sont générés et retournés dans la réponse.

title et files ne sont acceptés que si les options correspondantes (« Permettre un titre par message », « Autoriser les pièces jointes ») sont activées sur l’agent — sinon la requête est rejetée en 422.

Authorizations

• apiKey

Parameters

Header Parameters

X-Assilya-Thread

string

<= 191 characters

Votre identifiant de conversation (191 caractères max). Les messages partageant cette valeur rejoignent la même conversation ; sans lui, chaque message ouvre une nouvelle conversation.

X-Assilya-Message

string

<= 191 characters

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

X-Assilya-User-Id

string

Identifiant du contact côté agent. Renvoyez la valeur contact.id d’une réponse précédente pour rattacher le message au même contact sans repasser par la résolution e-mail/téléphone.

X-Assilya-User-Email

string

E-mail du contact, utilisé pour le retrouver ou le créer.

X-Assilya-User-Name

string

Nom du contact, appliqué à la création. Une valeur non ASCII (« Mara Götz ») doit être encodée en mot encodé RFC 2047, =?UTF-8?B?<base64 de la valeur UTF-8>?= — un en-tête HTTP transporte des octets, pas du texte. L’UTF-8 brut est également accepté.

Request Body^required

object

content

required

Le message du client.

string

<= 4000 characters

title

Sujet du message. Uniquement si « Permettre un titre par message » est activé sur l’agent (sinon 422).

string

<= 80 characters

files

Pièces jointes (multipart uniquement). Uniquement si « Autoriser les pièces jointes » est activé sur l’agent (sinon 422). 10 fichiers max, 10 Mo chacun. Types acceptés : PDF, PNG, JPEG, WebP, GIF, CSV, TXT, XLSX, DOCX.

Array<string>

<= 10 items

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

object

content

required

Le message du client.

string

<= 4000 characters

title

Sujet du message (si l’option est activée sur l’agent).

string

<= 80 characters

Responses

202

Message accepté — traitement 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

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

Example

{
  "id": "0196c3f2-1111-7000-8000-000000000001",
  "thread": {
    "id": "demo-thread-001",
    "title": null
  },
  "state": "processing",
  "contact": {
    "id": "0196c3f2-2222-7000-8000-000000000002",
    "name": "Jeanne Martin",
    "email": "jeanne@example.com",
    "phone": null
  }
}

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

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