Agent API

Administrateur

L’agent « API » (« Création d’une API pour que vos applications tierces soumettent des messages et reçoivent la réponse générée par Assilya. ») est fourni en standard, sans connexion. Il transforme Assilya en moteur de réponse pour vos propres applications : formulaire de contact, application mobile, système de ticketing…

Les paramètres

Section « Format de réponse » :

Champ	Rôle
Format de sortie	Texte brut (par défaut), Markdown ou HTML — selon ce que votre application sait afficher.
Autoriser les pièces jointes	Active l’envoi et la réception de fichiers (10 fichiers max, 10 Mo chacun, types usuels).
Permettre un titre par message	Autorise un titre par message soumis.

En édition s’ajoutent la section « Intégration API » (la clé ak_…, régénérable), la section « Webhook » et un « Exemple d’appel » prêt à copier pour tester depuis un terminal.

Comment votre application dialogue avec l’agent

Le principe, côté développeur :

1. Soumettre un message : POST /api/message avec la clé API en en-tête d’autorisation, le texte du message, et un identifiant de fil choisi par votre application — c’est lui qui regroupe les messages d’un même client en une conversation. Rejouer un même identifiant de message ne crée jamais de doublon : vos nouvelles tentatives sont sûres.
2. Récupérer la réponse — deux options :
   • interrogation : votre application redemande l’état du message toutes les quelques secondes jusqu’à la réponse ;
   • webhook (recommandé) : Assilya appelle votre serveur dès que la réponse est prête.
3. Interpréter l’état : processing (en cours), answered (la réponse, signature incluse), pending (l’IA passe la main — confiance insuffisante ou action à effectuer par un humain ; l’état porte alors les suggestions, et votre application ou votre équipe peut publier une réponse humaine via l’API), failed, closed.

L’API expose aussi la lecture des conversations, les tags, les notes internes et les contacts — de quoi construire une intégration complète. Votre application peut transmettre l’identité du client (identifiant, e-mail, nom) : elle est considérée vérifiée, ce qui débloque par exemple la recherche de commandes sans numéro.

Le document de référence, c’est l’« Exemple d’appel »

L’exemple curl généré sur la fiche de votre agent contient l’URL exacte de votre espace et votre clé : c’est le point de départ le plus fiable pour votre équipe technique.

Le webhook

Activez « Activer le webhook » et renseignez l’URL de callback (HTTPS obligatoire) : chaque réponse traitée déclenche un envoi vers votre serveur, avec le même contenu que l’interrogation — un seul traitement à développer.

• Chaque envoi est signé : le « Secret de signature » (whsec_…) permet à votre serveur de vérifier l’authenticité de la requête (signature HMAC transmise en en-tête, avec l’horodatage pour bloquer les rejeux).
• En cas d’échec de votre serveur, l’envoi est retenté 4 fois (immédiat, +60 s, +5 min, +15 min) avant abandon.
• Régénérer le secret invalide l’ancien immédiatement — synchronisez la mise à jour avec votre équipe technique.

Limites et messages

• Messages limités à 4 000 caractères ; débit plafonné par fil, par agent et par espace (HTTP 429 « Trop de requêtes, merci de patienter. »).
• La réponse humaine via l’API respecte les mêmes règles que la boîte de réception : conversation « En attente » uniquement, traduction automatique vers la langue du client, échec de traduction = rien n’est envoyé.

Pour vos développeurs

La section Intégration API (développeurs) fournit tout le nécessaire technique : guide de démarrage, authentification et identifiants, cycle de vie du message, mécanisme détaillé du webhook (signature, relances) et la référence complète des endpoints générée depuis notre schéma OpenAPI — avec une collection Postman à télécharger.