n8n
Connectez votre instance n8n et vos agents vocaux peuvent exécuter les workflows que vous avez déjà construits, pendant l'appel et après : rechercher une commande, créer une fiche, envoyer un message, puis confier le rapport de l'appel terminé au workflow de votre choix. Fonctionne avec n8n 1.x et 2.x, auto-hébergé ou sur une offre n8n Cloud payante.
Comment ça marche
Un workflow qui commence par un déclencheur Webhook est déjà un endpoint HTTP : Aethex n'a rien à installer dans votre n8n. Vous vous connectez une fois avec une clé API n8n. Aethex crée un identifiant Header Auth dans votre n8n et présente son secret à chaque appel, si bien qu'aucun secret n'est jamais copié à la main entre les deux systèmes. Vous demandez ensuite à Aethex quels workflows sont prêts, corrigez dans n8n ceux qui ne le sont pas, et liez chacun à un nom d'outil, une description et les arguments que l'agent peut passer. À partir de là, l'agent décide en cours d'appel quand un outil vaut la peine d'être appelé, et à la fin de l'appel le rapport complet peut atterrir dans un workflow de plus. Toute la mise en place tient en quatre appels API et quelques clics dans n8n.
Versions prises en charge
Toute version n8n 1.x ou 2.x qui expose l'API publique peut être connectée, auto-hébergée ou sur une offre n8n Cloud payante ; le parcours complet a été vérifié de bout en bout sur 1.123, 2.13, 2.32 et 2.37 avec le même script. L'expérience est identique sur toute la ligne 2.x. La ligne 1.x a une différence visible, sur l'identifiant.
| Version n8n | Ce qui change |
|---|---|
2.32 et suivantes | Expérience complète. Aethex lit d'emblée les scopes de la clé : un scope manquant est nommé à la connexion avant que rien ne soit créé, et se reconnecter renouvelle l'identifiant Aethex sur place. |
2.0 à 2.31 | Même expérience. Aethex prouve la clé en listant les workflows et n'apprend qu'un scope d'identifiant manque que lorsque la création de l'identifiant échoue ; le 422 nomme tout de même le scope à accorder. Se reconnecter renouvelle sur place. |
1.x | Fonctionne de bout en bout. 1.x n'a aucune route pour lister ou mettre à jour les identifiants : chaque reconnexion crée donc un nouvel identifiant Aethex (…) au lieu de renouveler l'existant. Sélectionnez le plus récent dans vos nœuds Webhook et supprimez les anciens. Les workflows s'allument avec Active plutôt que par publication. |
Connecter votre instance n8n
Dans n8n, créez une clé API sous Settings → n8n API. Elle a besoin de workflow:list et workflow:read pour voir vos workflows, et de credential:create et credential:update pour qu'Aethex puisse créer et renouveler son identifiant ; credential:list est facultatif et permet à Aethex de retrouver cet identifiant plutôt que d'en créer un second. Un owner ou un admin peut tous les accorder à la création de la clé. Envoyez la clé à POST /integrations avec l'URL de votre instance dans base_url (HTTPS public uniquement) et auth_type réglé sur api_key. Aethex prouve la clé auprès de votre instance avant de rien stocker, puis crée un identifiant Header Auth nommé Aethex (…), le suffixe étant les premiers caractères de l'id de votre espace de travail, dont la valeur est un secret qu'Aethex génère et stocke chiffré. Rien qui ressemble à un outil ne passe dans cet appel : les workflows sont liés après la découverte. La réponse montre l'identifiant qu'Aethex présentera sous credential, avec source à managed. Se connecter nécessite integrations:write.
config.webhook_base_url sur cet hôte et Aethex en dérive chaque URL de production. Si la clé ne peut pas gérer les identifiants, passez votre propre webhook_secret (16 à 512 caractères ; openssl rand -hex 32 est un bon choix) : Aethex enregistre source à customer, et vous créez vous-même l'identifiant Header Auth dans n8n avec Name réglé sur X-Aethex-Token et Value sur ce secret.curl -X POST https://api.aethexai.com/api/v1/integrations \
-H "X-API-Key: $AETHEX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"provider": "n8n",
"auth_type": "api_key",
"base_url": "https://n8n.your-company.com",
"access_token": "<your-n8n-api-key>",
"display_name": "Operations n8n"
}'
# 201 Created. The API key is never returned.
# Note the "id" it returns; every call below takes it.
export CONNECTION_ID=<the "id" from the response>Voir quels workflows sont prêts
GET /integrations/{id}/n8n/workflows lit votre instance et renvoie chaque workflow qui a un déclencheur Webhook, jugé sur sa version publiée ; un workflow qui n'existe qu'en brouillon est listé aussi, signalé not_published. Chaque entrée porte la webhook_url de production dérivée par Aethex, si bien que vous n'en saisissez jamais, les methods et l'authentication du déclencheur, l'identifiant qu'il utilise et si c'est celui d'Aethex, et un verdict ready. Un workflow qui n'est pas prêt liste ses issues et, sous fixes, la correction à faire dans n8n pour chacune, dans les termes exacts ci-dessous. bound_as montre le nom d'outil auquel un workflow répond déjà, et truncated avertit que l'instance contient plus de workflows que le parcours borné n'en a couvert. Rien n'est écrit dans n8n. Nécessite integrations:read.
| Problème | Correction |
|---|---|
not_published | Publiez le workflow dans n8n ; seule la version publiée répond aux webhooks. |
not_found | Aucun workflow avec cet id n'est visible par la clé API. |
archived | Le workflow est archivé. Restaurez-le dans n8n ou choisissez-en un autre. |
no_webhook_trigger | Ajoutez un nœud déclencheur Webhook au workflow. |
multiple_triggers | Ne gardez qu'un seul déclencheur Webhook activé dans le workflow. |
method_not_post | Réglez HTTP Method du nœud Webhook sur POST. |
auth_not_header | Réglez Authentication du nœud Webhook sur Header Auth. |
credential_not_aethex | Sélectionnez l'identifiant Aethex dans le nœud Webhook. |
credential_not_in_project | Partagez ou déplacez l'identifiant Aethex dans le projet du workflow, dans n8n. |
route_params | Utilisez un chemin de webhook fixe ; les paramètres de route comme :id exigent des valeurs. |
curl https://api.aethexai.com/api/v1/integrations/$CONNECTION_ID/n8n/workflows \
-H "X-API-Key: $AETHEX_API_KEY"Rendre un workflow appelable
Ouvrez le workflow dans n8n. Sur le nœud Webhook, réglez HTTP Method sur POST, Authentication sur Header Auth, et choisissez Aethex (…) dans la liste des identifiants ; il y est déjà. Gardez un chemin fixe : un paramètre de route tel que :id n'a aucune valeur qu'Aethex pourrait remplir. Terminez le workflow par un nœud Respond to Webhook qui renvoie du JSON, et gardez l'exécution complète sous 9 secondes, car l'appelant attend en ligne : au-delà, l'agent cesse d'attendre et passe à la suite. Puis publiez, ou sur n8n 1.x passez le workflow en Active. Depuis n8n 2.0, seule la version publiée répond aux webhooks de production : un brouillon enregistré ne change rien tant que vous ne publiez pas, et il en va de même pour chaque modification ultérieure. Relancez la découverte : le workflow affiche maintenant ready à true.
{"status": "ok", "body_empty": true} plutôt qu'un simple succès. Terminez toujours un workflow-outil par un nœud Respond qui renvoie les champs que l'agent doit relire à l'appelant ; une réponse sans aucun champ signifie que le nœud n'a rien produit.Lier des workflows comme outils
PUT /integrations/{id}/n8n/tools déclare tout l'ensemble des outils en un appel. Pour chaque workflow, donnez le tool_name que le modèle appellera, une description qui lui dit quand utiliser l'outil, et parameters, un objet JSON Schema décrivant les arguments que le modèle peut passer ; le nœud Webhook de n8n n'a pas de schéma d'entrée propre, c'est donc ici qu'il vit. Mettez writes à false sur un outil qui ne fait que lire : c'est ce qui le rend visible à un agent en lecture seule. post_call_workflow_id nomme le workflow qui reçoit le rapport d'appel. Aethex relit chaque workflow depuis n8n avant de rien stocker : si l'un n'est pas prêt, toute la requête échoue en 422 en listant workflow_id, issues et fixes par workflow, et rien ne change. La liste remplace la précédente : [] délie tout. Les autorisations d'agents ne sont pas touchées. Nécessite integrations:write.
| Champ | Règle |
|---|---|
workflows | Au plus 20 par connexion, chaque workflow lié une seule fois. |
tool_name | 1 à 64 caractères : lettres, chiffres, _ ou -, unique dans la connexion. end_call, voicemail_detected, transfer_to_number, send_whatsapp_message et n8n_send_call_report sont réservés. |
description | Texte brut, 1 à 300 caractères. Le modèle la lit pour décider quand appeler l'outil : dites ce que fait l'outil et quand il s'applique. |
parameters | Un JSON Schema avec type à object, 8 KiB au plus. Chaque nom de required doit être déclaré dans properties. Par défaut, un objet sans propriétés. |
writes | true par défaut. Mettez false sur un outil qui ne fait que lire, pour que les agents autorisés en read puissent le voir. |
curl -X PUT https://api.aethexai.com/api/v1/integrations/$CONNECTION_ID/n8n/tools \
-H "X-API-Key: $AETHEX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workflows": [
{
"workflow_id": "nP72CdKcpWs1H6Ei",
"tool_name": "lookup_order",
"description": "Return the status and delivery date of an order from its order number.",
"parameters": {
"type": "object",
"properties": {
"order_id": { "type": "string", "description": "The order number the caller gives" }
},
"required": ["order_id"]
},
"writes": false
}
],
"post_call_workflow_id": "X0pMPZCPehNtOtX7"
}'L'accorder aux agents
Lier un outil ne le confie à personne. Accordez la connexion par agent avec PUT /integrations/{id}/agents, en énonçant chaque fois l'ensemble complet : les agents que vous envoyez sont ceux qui ont l'accès, et une liste vide signifie personne. Le niveau décide de ce que voit un agent. read n'offre que les outils liés avec writes à false ; write offre tous les outils et active le rapport post-appel pour les appels de cet agent. Un agent sans autorisation ne voit jamais un outil n8n, quoi qu'il y ait de lié. Les autorisations sont lues au début de l'appel : un changement s'applique donc à l'appel suivant.
curl -X PUT https://api.aethexai.com/api/v1/integrations/$CONNECTION_ID/agents \
-H "X-API-Key: $AETHEX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agents": [
{ "agent_id": "<agent-uuid>", "access": "write" }
]
}'Ce que reçoit votre workflow
Quand l'agent appelle un outil, Aethex envoie un POST à l'URL de production du workflow avec l'en-tête X-Aethex-Token réglé sur le secret de l'identifiant. Le corps porte tool, les arguments du modèle sous input, et agent_id, conversation_id et call_id pour que le workflow puisse relier l'appel au rapport qui suit. Lisez un argument dans n8n avec $json.body.input.order_id pour un argument nommé order_id. La clé est input plutôt que arguments à dessein : le bac à sable d'expressions de n8n refuse l'identifiant arguments, si bien qu'un workflow ne pourrait jamais lire les valeurs sous ce nom. L'objet JSON que renvoie le nœud Respond revient au modèle tel quel, un tableau JSON revient sous result, et un corps vide devient {"status": "ok", "body_empty": true}, ce qui permet à l'agent de distinguer un workflow qui n'a rien renvoyé d'un workflow qui a répondu. L'agent obtient sa réponse sous 9 secondes, le délai imposé à tout outil. Si le workflow tourne encore à ce moment-là, un outil lié avec writes: false est abandonné et l'agent apprend qu'il n'a pas obtenu de réponse ; un outil lié avec writes: true va à son terme, et l'agent apprend que le résultat est inconnu et qu'il ne doit pas recommencer. La requête elle-même s'arrête à 10 secondes, et la réponse est plafonnée à 32 KiB. Après cinq échecs d'affilée, Aethex suspend les appels vers votre instance pendant 30 secondes et dit à l'agent que l'outil est indisponible, pour qu'un workflow cassé ne bloque pas chaque appel.
N8N_RUNNERS_AUTO_SHUTDOWN_TIMEOUT côté n8n. Une règle n8n de plus quand vous écrivez le corps du Respond : dans une expression, deux accolades fermantes à la suite la terminent, même dans un objet imbriqué ; mettez une espace entre elles.POST https://n8n.your-company.com/webhook/order-lookup
X-Aethex-Token: <the credential's secret>
Content-Type: application/json
{
"tool": "lookup_order",
"input": { "order_id": "4821" },
"agent_id": "2f6c6a1e-9d8b-4c1a-9f3e-0b7d5e4a1c22",
"conversation_id": "7d1a3f0c-52b4-4e6e-8a9f-3c2d1b0e9f88",
"call_id": "c0ffee00-1111-4222-8333-444455556666"
}Recevoir le rapport d'appel
Quand un appel se termine, Aethex poste le même rapport que reçoit votre webhook call.ended au workflow que vous avez nommé dans post_call_workflow_id, avec un champ supplémentaire, event, réglé sur call.ended : ids d'appel, de conversation et d'agent, direction et numéros, durée et coût, horodatages et transcription. Il utilise le même en-tête et la même configuration Webhook qu'un outil en cours d'appel, avec un budget de 30 secondes au lieu de 10 puisque personne n'attend en ligne, et il ne se déclenche que pour les agents autorisés en write. Le rapport est envoyé au plus une fois par appel : son event_id est dérivé de l'id de l'appel, si bien qu'une nouvelle tentative ne produit jamais un second rapport différent, et un envoi qui a peut-être déjà quitté Aethex n'est pas répété. Un workflow qui échoue sur le rapport ne fait pas échouer l'appel, et le résultat n'apparaît pas sur l'appel lui-même : confirmez la livraison dans les Executions du workflow dans n8n. Voir Webhooks pour la charge utile champ par champ.
{
"event": "call.ended",
"event_id": "6f1d2c3b-4a5e-5f60-9b7c-8d9e0f1a2b3c",
"timestamp": 1756900000,
"call_id": "c0ffee00-1111-4222-8333-444455556666",
"conversation_id": "7d1a3f0c-52b4-4e6e-8a9f-3c2d1b0e9f88",
"agent_id": "2f6c6a1e-9d8b-4c1a-9f3e-0b7d5e4a1c22",
"status": "completed",
"direction": "inbound",
"from_number": "+2348012345678",
"to_number": "+2341234567890",
"duration_seconds": 184,
"cost_cents": 12,
"started_at": "2026-09-03T12:40:11Z",
"ended_at": "2026-09-03T12:43:15Z",
"transcript": [
{ "role": "user", "content": "Hi, I want to check on order 4821." },
{ "role": "assistant", "content": "Order 4821 shipped with DHL and arrives on the 5th." }
],
"transcript_text": "user: Hi, I want to check on order 4821.\nassistant: Order 4821 shipped ...",
"transcript_truncated": false
}Sécurité
Votre instance n8n doit être joignable en HTTPS public ; les hôtes privés, en boucle locale et internes sont refusés, et le nom d'hôte est résolu et épinglé juste avant chaque requête. Les redirections ne sont jamais suivies ; les lectures API expirent au bout de 15 secondes et sont plafonnées à 1 MiB, les appels de webhook à 10 secondes et 32 KiB. Pendant un appel, l'agent répond tout de même sous 9 secondes, quoi que fasse n8n : dimensionnez vos workflows en cours d'appel sur ce délai, pas sur ces limites. La clé API et le secret de webhook sont chiffrés au repos et jamais renvoyés par aucun endpoint, et les identifiants propres à vos workflows ne quittent jamais n8n. Se reconnecter renouvelle le secret sur place, si bien que chaque nœud Webhook qui utilise déjà l'identifiant Aethex continue de fonctionner avec la nouvelle valeur sur n8n 2.x ; sur 1.x, une reconnexion crée un nouvel identifiant, voir Versions prises en charge. La vérification de l'en-tête est la seule chose qui protège un workflow de l'extérieur : un déclencheur laissé sur Authentication: None répond à quiconque connaît son URL, et c'est pourquoi la découverte le refuse.
X-Aethex-Token. Traitez cet accès comme un accès aux outils de vos agents : restreignez qui peut voir les exécutions, désactivez l'enregistrement des exécutions de production dans les paramètres des workflows liés si vous n'avez pas besoin de ces données, et reconnectez-vous pour renouveler le secret dès que vous soupçonnez une fuite.Quand un appel échoue
401 et 403 s'appliquent à chaque appel ici et se déclenchent avant tout traitement. Ensuite, se connecter renvoie 404, 409, 422, 429 ou 503 ; la découverte et la liaison renvoient 404, 409, 422, 429 ou 503 et portent le message propre à n8n dans le détail quand votre instance a refusé quelque chose ; définir les agents renvoie 404 ou 409.
Chaque appel de cette page, avant tout traitement. Pas d'en-tête X-API-Key, ou une clé invalide, révoquée ou expirée.
Envoyez une clé valide. Missing API key signifie que l'en-tête n'est jamais arrivé ; Invalid or expired API key qu'il n'a pas correspondu.
Chaque appel, avant tout traitement. La clé est valide mais n'a pas le scope requis : integrations:write pour connecter, lier ou définir les agents, integrations:read pour découvrir ou relire une connexion.
Le détail nomme le scope manquant. Les scopes sont fixés à la création de la clé, alors créez une clé qui le porte plutôt que d'élargir celle-ci.
Se connecter, découvrir, lier et définir les agents. L'id de connexion n'est pas le vôtre ou n'est pas une connexion n8n, ou un agent_id n'est pas un de vos agents.
Vérifiez l'id de la réponse de connexion, et que chaque agent_id est un agent de ce tenant. Un id étranger est délibérément indistinct d'un id manquant.
Découvrir, lier et définir les agents. La connexion existe mais n'est plus la connexion active, parce qu'elle a été révoquée ou remplacée par une reconnexion, ou une requête concurrente a modifié les mêmes autorisations.
Relisez la connexion : si elle n'est plus active, repartez de l'id renvoyé par la dernière connexion. Sinon renvoyez ; les corps sont déclaratifs, donc une nouvelle tentative converge.
Se connecter : n8n a rejeté la clé API, la clé n'a pas un scope n8n que le détail nomme, base_url manque ou n'est pas en HTTPS public, ou config porte un champ autre que webhook_base_url. Lier : un tool_name est réservé ou mal formé, parameters n'est pas un schéma d'objet, ou un workflow n'est pas prêt, et dans ce cas le détail liste workflows avec issues et fixes. La découverte et la liaison renvoient aussi 422 quand n8n répond une erreur qui ne se résoudra pas seule.
Lisez le détail : il nomme le champ, le scope n8n à accorder, ou le workflow et la correction à faire dans n8n. Un 422 de liaison n'a rien stocké : renvoyez toute la liste une fois les corrections faites.
Se connecter : plus de 10 tentatives en 60 secondes depuis un même tenant. Découvrir et lier : plus de 35 requêtes en 60 secondes, puisque chacune lit votre instance n8n.
Attendez la fenêtre indiquée dans l'en-tête Retry-After. La découverte est une étape de mise en place, pas quelque chose à interroger en boucle.
Se connecter, découvrir et lier. Votre instance n8n était injoignable ou a expiré, la clé de chiffrement manque sur ce déploiement, ou le limiteur de débit est hors service.
Réessayez, et lisez le détail pour savoir lequel des trois. Une instance injoignable se résout seule ; une clé manquante ou un limiteur hors service est de notre côté et continue d'échouer jusqu'à correction.
Notes et limites
Quelques points à connaître avant de bâtir dessus.
| Limite | Ce que cela signifie |
|---|---|
| Se reconnecter repart de zéro | Un espace de travail détient une seule connexion n8n active. Se reconnecter renouvelle l'identifiant sur place sur n8n 2.x, vos nœuds Webhook continuent donc de fonctionner, mais c'est une nouvelle connexion : les autorisations d'agents ne sont pas reprises et les outils liés disparaissent jusqu'à ce que vous les déclariez de nouveau avec PUT /integrations/{id}/n8n/tools. |
| Version publiée uniquement | Aethex lit et appelle la version publiée d'un workflow. Modifier un brouillon ne change rien tant que vous ne publiez pas, et dépublier fait échouer l'outil jusqu'à ce que vous publiiez de nouveau. |
| L'identifiant vit dans un seul projet | Aethex crée son identifiant dans le projet personnel de l'utilisateur qui possède la clé API. Un workflow d'un autre projet ne peut pas le sélectionner tant que vous n'avez pas partagé ou déplacé l'identifiant dans n8n ; la découverte le signale par credential_not_in_project. |
| La découverte est bornée | La découverte parcourt jusqu'à 1 000 workflows et met truncated quand l'instance en contient plus. Lier par id fonctionne toujours pour tout workflow que la clé peut lire. |
| Les autorisations s'appliquent au début de l'appel | Retirer une autorisation prend effet à l'appel suivant, pas à un appel déjà en cours. Se déconnecter agit immédiatement. |