Intégration n8n

n8n est un outil pour créer des workflows automatisés. Il existe deux façons de l'utiliser avec Deskwoot. Avec un nœud Webhook dans n8n, les événements Deskwoot, comme une nouvelle conversation, un nouveau message d'un client ou une note CSAT, lancent vos workflows n8n : vous pouvez ainsi les transmettre à votre CRM, à un tableur ou à vos propres systèmes. Le nœud Deskwoot pour n8n agit aussi dans Deskwoot : vos workflows répondent, ajoutent des notes, attribuent, ajoutent des étiquettes et créent ou mettent à jour des contacts. Vous trouvez aussi les deux façons dans Paramètres > Intégrations > n8n.

Le forfait qu'il vous faut

Le nœud Webhook reçoit ses événements d'un webhook Deskwoot. Les webhooks nécessitent le forfait Startup ou supérieur, et l'essai gratuit les inclut. Sur le forfait gratuit Hacker, les webhooks n'envoient rien.

Un webhook envoie seulement des données hors de Deskwoot. Pour que n8n réponde aux messages des clients en tant que bot, ajoutez un bot Custom Webhook dans Paramètres > IA > Plus de bots, qui nécessite un forfait payant (Startup et plus). Pour répondre aux messages des clients ou agir dans Deskwoot depuis n8n, utilisez le nœud Deskwoot pour n8n (voir plus bas). Chaque conversation à laquelle n8n répond, en tant que bot ou avec Reply, compte pour 1 conversation IA. Pour tout ce que le nœud ne fait pas, comme résoudre une conversation, appelez l'API REST de Deskwoot avec le nœud HTTP Request de n8n et un jeton d'API. Le nœud et l'API REST nécessitent un forfait Enterprise payant, et l'essai gratuit n'inclut pas l'accès à l'API. Pour créer un jeton : Jetons d'API et accès pour les développeurs.

Le nœud Webhook dans n8n (Startup et plus)

Configuration dans n8n

1. Dans n8n, ouvrez votre workflow et ajoutez un nœud Webhook comme première étape.
2. Réglez HTTP Method sur POST.
3. Laissez Respond sur Immediately, pour que n8n réponde tout de suite à Deskwoot.
4. Copiez la Production URL du nœud.

Configuration dans Deskwoot

1. Allez dans Paramètres > Webhooks. Seuls les administrateurs voient cette page.
2. Cliquez sur Ajouter un webhook.
3. Collez la Production URL dans URL de l'endpoint.
4. Sous S'abonner aux événements, cochez les événements dont votre workflow a besoin. Si vous n'en cochez aucun, le webhook reçoit tous les événements.
5. Cliquez sur Créer le webhook.

Publiez ensuite le workflow dans n8n : n8n n'écoute sur la Production URL qu'une fois le workflow publié. À partir de là, chaque événement lance une exécution du workflow, et vous voyez les exécutions dans son onglet Executions.

Ce qui arrive dans n8n

Chaque événement arrive sous forme de requête POST avec un corps JSON. Dans la sortie du nœud Webhook, le corps contient event (le nom de l'événement), data (les données de l'événement), timestamp et accountId. Les en-têtes contiennent x-deskwoot-event avec le nom de l'événement et x-deskwoot-signature. Quand un webhook envoie plusieurs événements, faites vérifier event par le nœud suivant, par exemple un nœud If.

Vous pouvez choisir ces événements : Conversation créée, Conversation mise à jour, Conversation attribuée, Conversation résolue, Message créé, Contact créé, Contact mis à jour et CSAT envoyé. Les données de chaque événement figurent dans la documentation de l'API.

Bon à savoir

• Deskwoot attend 10 secondes au maximum. Si n8n ne répond pas à temps ou répond par une erreur, Deskwoot réessaie une fois après 5 secondes. Avec Respond sur Immediately, un long workflow ne fait jamais attendre Deskwoot.
• n8n doit être joignable depuis Internet en HTTPS. Deskwoot envoie uniquement vers des adresses HTTPS publiques. Si n8n tourne sur votre propre serveur, il lui faut une adresse HTTPS publique, pas une adresse de votre réseau interne.
• Utilisez la Production URL, pas la Test URL. Deskwoot continue d'envoyer à l'adresse que vous avez enregistrée : ce doit donc être celle sur laquelle n8n écoute pendant que le workflow est publié.

Le nœud Deskwoot pour n8n (Enterprise)

Le nœud Deskwoot pour n8n est un nœud communautaire nommé n8n-nodes-deskwoot. Il comprend 2 nœuds : le Deskwoot Trigger, qui lance un workflow quand quelque chose se passe dans Deskwoot, et le nœud Deskwoot, qui agit dans Deskwoot. Il fonctionne avec n8n sur votre propre serveur. n8n Cloud ne propose que les nœuds communautaires vérifiés par n8n, et ce nœud n'en fait pas encore partie.

L'installer et se connecter

1. Dans n8n, allez dans Settings > Community Nodes, cliquez sur Install, saisissez n8n-nodes-deskwoot et installez-le. Seuls le propriétaire et les administrateurs de votre n8n voient cette page.
2. Dans Deskwoot, allez dans Paramètres > Jetons d'API et cliquez sur Créer un jeton. Cochez les autorisations Lecture et Écriture, puis créez le jeton. Copiez-le : Deskwoot ne l'affiche qu'une seule fois. Seuls les administrateurs voient cette page.
3. Dans n8n, créez un identifiant (credential) Deskwoot API. Collez le jeton dans API Token. Dans Account ID, saisissez l'ID que la même page Deskwoot affiche sous Votre ID de compte. Laissez Base URL tel quel.
4. Enregistrez l'identifiant. n8n le teste tout de suite en listant les boîtes de réception de votre espace de travail.

Si le test échoue, le jeton a été révoqué ou a expiré, l'ID de compte appartient à un autre espace de travail, l'espace de travail n'est pas sur le forfait Enterprise, ou le jeton n'a pas l'autorisation Lecture. Un jeton MCP pour agents IA ne fonctionne pas ici : créez un jeton d'API REST dans Paramètres > Jetons d'API.

Deskwoot Trigger

Choisissez l'un de ces événements sous Event :

• Conversation Created : une conversation commence, qu'un client ait écrit ou que votre équipe l'ait lancée.
• Customer Message Received : un client écrit dans une conversation. Les réponses et les notes de votre équipe ne comptent pas.
• Conversation Assigned : une conversation reçoit un nouveau responsable. Le Round Robin sur une nouvelle conversation et les règles d'automatisation ne le déclenchent pas.
• Conversation Resolved : une conversation est marquée comme résolue.
• Contact Created : un membre de l'équipe ajoute un contact dans Deskwoot, ou une app en ajoute un via l'API. Les contacts que Deskwoot crée à partir des messages entrants déclenchent plutôt Conversation Created.
• Conversation Rated : un client note une conversation dans l'enquête de satisfaction.

Chaque événement arrive sous forme d'un seul élément avec des champs simples. Une conversation arrive avec son ID, son numéro, son lien, son statut, son objet, son canal, sa boîte de réception, son responsable, son équipe, ses étiquettes, le nom, l'adresse e-mail et le numéro de téléphone du client, ainsi que le premier message du client.

Quand vous publiez le workflow, le trigger abonne sa Production URL à l'événement dans Deskwoot, et quand vous annulez la publication, le trigger supprime cet abonnement. Deskwoot signe chaque événement et le trigger vérifie la signature : personne d'autre ne peut donc lancer votre workflow via son URL. Le trigger a besoin des éléments suivants :

• Un jeton créé par un administrateur. Seul un tel jeton peut activer les triggers Deskwoot.
• n8n joignable depuis Internet en HTTPS. Si n8n tourne derrière un proxy inverse, réglez la variable WEBHOOK_URL de n8n sur son adresse publique.

Nœud Deskwoot

Choisissez Resource et Operation :

• Conversation > Start : envoie un premier message à un contact depuis l'une de vos boîtes de réception, via son adresse e-mail, son numéro de téléphone ou son ID de contact. Cela fonctionne là où une entreprise peut écrire en premier, comme par e-mail ou par SMS. Deskwoot refuse un démarrage que le canal ne peut pas livrer (un chat en direct, WhatsApp sans modèle approuvé, ou un utilisateur Telegram, LINE ou X qui n'a jamais écrit à cette boîte de réception), et le nœud en indique la raison. La nouvelle conversation compte pour 1 conversation IA.
• Conversation > Reply : envoie une réponse au client sur le canal de la conversation. Chaque conversation à laquelle il répond compte pour 1 conversation IA. Quand vos conversations IA sont épuisées et que votre solde prépayé ne peut pas en payer une autre, Deskwoot refuse la réponse dans une conversation pas encore comptée ce mois-ci.
• Conversation > Add Private Note : ajoute une note que seule votre équipe voit.
• Conversation > Assign : attribue une conversation à un membre de l'équipe, à une équipe, ou aux deux.
• Conversation > Add Label : ajoute l'une de vos étiquettes à une conversation.
• Contact > Create or Update : met à jour le contact qui a cette adresse e-mail, ou le crée s'il n'existe pas.
• Contact > Find : renvoie un seul contact, celui qui correspond le mieux à une adresse e-mail, un numéro de téléphone ou un nom.

Vous pouvez reprendre l'ID de la conversation dans la sortie du Deskwoot Trigger. Les réponses et les notes venant de n8n affichent le nom de la personne qui a créé le jeton d'API. Le nœud fonctionne aussi comme outil pour les agents IA de n8n.

Questions fréquentes

Quel forfait me faut-il ?

Startup ou supérieur pour le webhook qui lance vos workflows, et l'essai gratuit l'inclut. Un bot Custom Webhook, qui permet à n8n de répondre à vos clients, nécessite un forfait payant (Startup et plus). Le nœud Deskwoot pour n8n et l'API REST nécessitent un forfait Enterprise payant, et l'essai gratuit n'inclut pas l'accès à l'API. Chaque conversation à laquelle n8n répond compte pour 1 conversation IA.

Pourquoi mon workflow ne démarre-t-il pas ?

Vérifiez que le workflow est publié dans n8n, que le webhook dans Deskwoot a la Production URL et non la Test URL, que l'événement est coché (ou qu'aucun ne l'est), et que n8n est joignable depuis Internet en HTTPS. Sur le forfait gratuit Hacker, les webhooks n'envoient rien du tout.

n8n peut-il modifier quelque chose dans Deskwoot ?

Oui, avec le nœud Deskwoot pour n8n sur le forfait Enterprise : il répond, ajoute des notes privées, attribue, ajoute des étiquettes, démarre des conversations et crée ou met à jour des contacts. Pour tout le reste, comme résoudre une conversation, appelez l'API REST avec le nœud HTTP Request de n8n, également sur Enterprise. Le webhook envoie seulement des événements vers l'extérieur. Sans Enterprise, un bot Custom Webhook dans Paramètres > IA > Plus de bots (Startup et plus) permet à n8n de répondre aux messages des clients en tant que bot. Chaque conversation à laquelle n8n répond avec Reply ou en tant que bot compte pour 1 conversation IA, alors que les notes, les attributions, les étiquettes et les contacts ne comptent jamais.

Pourquoi ne puis-je pas publier un workflow avec le Deskwoot Trigger ?

Seul un jeton d'API créé par un administrateur peut activer les triggers Deskwoot, car un trigger reçoit les événements de toutes les conversations, comme un webhook. Créez un jeton en tant qu'administrateur et utilisez-le dans l'identifiant Deskwoot API. n8n doit aussi être joignable depuis Internet en HTTPS, et un espace de travail peut avoir au maximum 100 de ces abonnements, en comptant les triggers de l'app Deskwoot pour Zapier.

Que se passe-t-il si je révoque le jeton ?

Tous les triggers activés par ce jeton s'arrêtent immédiatement, et les actions du nœud échouent. Créez un nouveau jeton, mettez à jour l'identifiant Deskwoot API, puis annulez la publication du workflow et publiez-le de nouveau.

Comment savoir qu'un événement vient vraiment de Deskwoot ?

Chaque requête porte un en-tête x-deskwoot-signature : sha256= suivi du HMAC SHA256 en hexadécimal du corps brut, signé avec le secret du webhook. Le Deskwoot Trigger le vérifie pour vous. Pour le nœud Webhook, le tableau de bord n'affiche pas ce secret, alors traitez la Production URL comme un mot de passe : n8n lui donne un chemin aléatoire, et seul Deskwoot doit la connaître. Un webhook créé via l'API REST renvoie son secret une seule fois dans la réponse.

Est-ce que cela fonctionne avec n8n Cloud ?

Le nœud Webhook fonctionne sur n8n Cloud et sur n8n installé sur votre propre serveur. Le nœud Deskwoot pour n8n ne fonctionne qu'avec n8n sur votre propre serveur, car n8n Cloud ne propose que les nœuds communautaires vérifiés par n8n. Sur votre propre serveur, n8n a besoin d'une adresse HTTPS publique pour que Deskwoot puisse le joindre.

Puis-je lancer plusieurs workflows ?

Oui. Créez un webhook dans Deskwoot pour la Production URL de chaque workflow, chacun avec ses propres événements. Avec le nœud Deskwoot, chaque workflow publié avec un Deskwoot Trigger reçoit son propre abonnement.

Que se passe-t-il si n8n est indisponible pendant un moment ?

Les événements de cette période sont perdus après l'unique nouvelle tentative, car Deskwoot ne conserve rien au-delà. Sur Enterprise, vous pouvez rattraper le retard via l'API REST, par exemple en listant les conversations triées par activité la plus récente.