Démarrer avec l'API

Cette section s’adresse aux développeurs qui souhaitent brancher leur propre application — formulaire de contact, application mobile, système de ticketing… — sur le moteur de réponse d’Assilya, via l’agent API. Elle complète la Référence API générée depuis notre schéma OpenAPI.

Le principe

Votre application soumet le message d’un client ; Assilya génère la réponse avec tout son contexte (bases de connaissances, outils, instructions, mémoire). Selon le pourcentage de confiance obtenu :

• au-dessus du seuil de l’agent, la réponse vous est livrée directement (état answered) ;
• en dessous — ou si la résolution exige une action qu’Assilya ne peut pas effectuer seule (réexpédition, remboursement…) —, la conversation passe en validation humaine (état pending) avec 2 à 4 suggestions — votre équipe la traite depuis la boîte de réception d’Assilya ou votre application publie la réponse validée par ses propres écrans.

Le modèle est asynchrone : la soumission répond immédiatement 202, puis vous suivez l’avancement par polling ou par webhook.

Prérequis

Administrateur

1. Un agent de type API actif sur votre espace — voir Créer un agent.
2. Sa clé API (préfixe ak_), affichée dans les paramètres de l’agent.
3. Le slug de votre espace — le segment d’URL visible dans le panneau d’administration (ex. mon-entreprise dans https://app.assilya.fr/mon-entreprise).

Selon votre offre

L’accès API et les webhooks dépendent de votre offre d’abonnement : si votre offre ne les inclut pas, le type d’agent API apparaît grisé et les appels API sont refusés.

URL de base et formats

Toutes les routes sont préfixées par le slug de l’espace :

https://app.assilya.fr/{slug}/api

Les corps de requête s’envoient en JSON (Content-Type: application/json) ou en multipart/form-data — obligatoire dès qu’il y a des pièces jointes. Ajoutez toujours Accept: application/json. Les réponses sont en JSON, les dates au format ISO 8601.

Premier appel

curl -X POST https://app.assilya.fr/{slug}/api/message \
  -H "Authorization: Bearer ak_votre_cle" \
  -H "Accept: application/json" \
  -H "X-Assilya-Thread: ticket-12345" \
  -F "content=Bonjour, où en est ma commande 1042 ?"

Réponse 202 :

{
  "id": "0196c3f2-…",
  "thread": { "id": "ticket-12345", "title": null },
  "state": "processing",
  "contact": null
}

Consultez ensuite GET /api/message/{messageId} jusqu’à l’état final — ou laissez le webhook vous prévenir. Le détail des états et du flux complet est décrit dans Le cycle de vie d’un message.

Limites de débit

Quatre plafonds s’appliquent simultanément ; leur dépassement renvoie 429 :

Portée	Limite
Par conversation (X-Assilya-Thread)	30 requêtes / minute
Par agent (clé API)	200 requêtes / minute
Par adresse IP	120 requêtes / minute
Par espace	1 000 requêtes / minute

Collection Postman

Une collection prête à l’emploi reprend tous les appels de cette section, avec variables et scripts de test : télécharger la collection Postman.

Prochaine étape

Configurez vos en-têtes d’authentification et d’identifiants, puis parcourez la Référence API.