Utiliser ThunderPhone avec n8n

Installez le nœud ThunderPhone pour n8n, connectez une clé API de serveur et créez un workflow qui s’exécute à chaque fin d’appel.

n8n est un outil d’automatisation des workflows. Le package ThunderPhone pour n8n ajoute deux nœuds :

• ThunderPhone Trigger démarre un workflow lorsqu’un appel se termine (Appel terminé) ou qu’une exécution d’évaluation d’appel se termine (Appel évalué).
• ThunderPhone passe des appels sortants, ajoute des contacts aux campagnes et les lance, récupère les appels avec leur transcription et leur enregistrement, et liste vos agents et numéros de téléphone.

Il s’agit d’un nœud communautaire vérifié, répertorié sur ThunderPhone sur n8n.

Installer le nœud#

Dans l’éditeur n8n, cliquez sur + pour ouvrir le panneau des nœuds et recherchez ThunderPhone. Le propriétaire d’une instance peut devoir configurer les nœuds vérifiés avant que les autres utilisateurs puissent les ajouter.

Sur n8n auto-hébergé, vous pouvez également installer le package par son nom : ouvrez Paramètres > Nœuds communautaires et installez n8n-nodes-thunderphone. Vérifiez les risques liés aux nœuds communautaires et la politique de votre instance avant de l’installer.

Créer une clé API serveur#

1. Ouvrir l’onglet Clés

   Dans ThunderPhone, accédez à Organisation → Clés et cliquez sur Créer une clé.

2. La nommer

   Utilisez un nom indiquant où se trouve la clé, par exemple « n8n ».

3. La copier maintenant

   Le secret complet sk_live_... n’est affiché qu’une seule fois. Copiez-le avant de fermer la boîte de dialogue.

Seul un administrateur ou un propriétaire peut créer la clé, et ThunderPhone traite les requêtes effectuées avec celle-ci comme provenant de cette personne. Le déclencheur et les opérations de campagne nécessitent que cette personne conserve le rôle d’administrateur ou de propriétaire. Créer une clé API serveur explique la rotation et la révocation.

Ajouter l’identifiant dans n8n#

1. Dans n8n, créez un identifiant de type API ThunderPhone.
2. Collez la clé dans Clé API.
3. Enregistrez-la et exécutez le test d’identifiant. Le test lit un appel de votre organisation avec GET /v1/calls?limit=1.

Créer un premier workflow#

Ce workflow ajoute une ligne à une feuille Google Sheets à chaque fin d'appel.

1. Ajouter le déclencheur

   Ajoutez ThunderPhone Trigger, sélectionnez votre identifiant API ThunderPhone et définissez Event sur Call Completed.

2. Récupérer l'appel

   Ajoutez un nœud ThunderPhone. Définissez Resource sur Call, Operation sur Get et Call ID sur l'expression {{ $json.data.call_id }}. La sortie contient l'enregistrement d'appel, ainsi que transcripts et recording_url, un lien temporaire qui vaut null lorsque l'appel ne comporte aucun enregistrement.

3. Ajouter une ligne

   Ajoutez un nœud Google Sheets qui ajoute une ligne et mappez les colonnes souhaitées à partir de la sortie Get Call (voir le tableau ci-dessous).

4. Activer le workflow

   Enregistrez et activez. Le déclencheur enregistre son URL de production comme point de terminaison webhook dans votre organisation ThunderPhone. La désactivation du workflow supprime ce point de terminaison.

5. Le tester

   Ouvrez un agent dans le builder, cliquez sur Parler, puis terminez l'appel. Les appels de test du builder sont envoyés sous la forme de web.complete, l'un des deux événements associés à Call Completed : le workflow s'exécute donc et une ligne apparaît.

Colonnes utiles :

Le lien de l'appel ouvre l'appel dans le tableau de bord ThunderPhone pour les membres de votre organisation, avec sa transcription et son enregistrement, afin que la feuille n'ait pas besoin de stocker ces éléments.

Pour ajouter tout de même la transcription, mappez {{ $json.transcripts.filter(t => typeof t.content === 'string').map(t => t.role + ': ' + t.content).join('\n') }}. L'URL de l'enregistrement expire : stockez donc l'ID de l'appel et exécutez à nouveau Get Call lorsque vous avez besoin d'un nouveau lien. Les transcriptions, résumés et enregistrements d'appels peuvent contenir des informations personnelles ou de santé. Envoyez-les uniquement aux applications que votre organisation est autorisée à utiliser pour ces données, dans le cadre d'un BAA lorsque des informations de santé sont concernées, et ne conservez que les champs nécessaires.

Le déclencheur produit l'événement complet : type, event_id et data. Consultez telephony.complete / web.complete et call.graded pour connaître tous les champs. La livraison est effectuée au moins une fois, et event_id reste identique lors des nouvelles tentatives pour un même événement : vérifiez-le avant une étape qui ne doit pas être répétée.

Passer des appels sortants en toute sécurité#

Passer un appel sortant (ressource Appel sortant, opération Passer) accepte :

Associez la clé d'idempotence à un ID provenant de l'élément ayant déclenché l'exécution, tel qu'un ID d'enregistrement CRM ou le event_id du déclencheur. Le nœud envoie n8n:<node ID>:<your value>, donc :

• Une nouvelle tentative automatique ou Réessayer l'exécution envoie la même clé, et ThunderPhone renvoie l'appel d'origine avec idempotent_replay: true au lieu de composer à nouveau le numéro.
• Deux nœuds ThunderPhone alimentés par le même enregistrement envoient des clés différentes.
• Une valeur vide échoue avant l'envoi de toute requête.

Évitez les horodatages, les valeurs aléatoires et les ID d'exécution ou de workflow n8n. Une nouvelle valeur lors d'une nouvelle tentative passe un second appel réel. La clé entière peut contenir au maximum 128 caractères. La réutilisation d'une clé avec un autre agent, numéro ou d'autres variables échoue avec un conflit.

Campagnes. Ajouter des contacts (ressource Campagne) ajoute des contacts à une campagne brouillon. Cette opération accepte un ID de campagne et un tableau JSON de contacts. Chaque contact nécessite phone_number ; les autres clés deviennent des variables d'appel. Le nœud échoue lorsque tous les contacts sont rejetés et définit partial_success: true lorsque seuls certains le sont. Démarrer nécessite de cocher la case confirmant que la campagne passe de vrais appels et dépense des crédits ThunderPhone. Consultez Campagnes sortantes.

Avant qu'un workflow ne démarre des appels :

• Si ThunderPhone demande à votre organisation de confirmer que ses appels sortants respectent la TCPA et les autres lois sur les appels, un administrateur doit d'abord consigner cette confirmation dans le tableau de bord.
• Le numéro d'origine doit être activé pour les appels sortants. Les numéros fournis par votre propre opérateur sont éligibles après vérification. Les numéros ThunderPhone sont au départ réservés aux appels entrants et peuvent être approuvés pour les appels sortants : un administrateur en fait la demande depuis la page Numéros de téléphone. Consultez Obtenir un numéro de téléphone.
• Votre organisation est responsable de disposer du consentement nécessaire pour appeler chaque numéro et de respecter les lois applicables aux appels. Consultez Lois sur les appels sortants.

Exemples de workflows#

• Contacts CRM vers une campagne. Ajoutez des contacts CRM à une campagne ThunderPhone brouillon, puis démarrez la campagne lorsqu'une personne approuve la liste.
• Appel terminé vers la fiche client. Lors d'un appel terminé, exécutez Obtenir l'appel et enregistrez la transcription et le lien de l'enregistrement dans la fiche client correspondante.
• Notes faibles à examiner. Lors d'un appel évalué, filtrez selon {{ $json.data.grade.score }} et effectuez le routage des appels avec un faible score vers une file d'examen avec l'ID de l'appel et les détails de l'évaluation. Un appel peut être évalué plusieurs fois, et chaque exécution d'évaluation terminée déclenche le déclencheur, conservez donc uniquement le dernier graded_at pour chaque ID d'appel.

Les transcriptions, résumés et enregistrements d'appels peuvent contenir des informations personnelles ou de santé. Envoyez-les uniquement aux applications que votre organisation est autorisée à utiliser pour ces données, dans le cadre d'un BAA lorsque des informations de santé sont concernées, et conservez uniquement les champs dont vous avez besoin.