Recette d'intégration

WhatsApp + n8n : envoyez et recevez WhatsApp depuis vos workflows

Fonctionne dès aujourd'hui avec le nœud HTTP RequestDernière vérification : octobre 2026

Spun dispose d'une REST API conçue précisément pour ce type d'automatisation, et n8n n'a besoin de rien de particulier pour l'utiliser : un nœud HTTP Request avec un jeton Bearer envoie des messages WhatsApp, téléverse des médias, crée et met à jour des contacts, applique des étiquettes et vérifie si un numéro a WhatsApp. Un nœud déclencheur Webhook reçoit en retour les vrais événements WhatsApp, signés pour que vous puissiez prouver qu'ils viennent de Spun.

Cette page décrit la voie qui fonctionne dès aujourd'hui, rédigée d'après l'API en service et non d'après une feuille de route. Lorsqu'une chose n'est pas encore en libre-service, elle le dit au lieu de faire semblant.

1. Créez une clé API

  1. 1

    Ouvrez les clés API

    Dans votre boîte de réception Spun : « Paramètres », puis « Webhooks », puis « Gérer les clés API », puis « Nouvelle clé ».

  2. 2

    Nommez-la et choisissez les portées

    Donnez-lui un nom comme « n8n Production ». N'activez que ce dont le workflow a besoin : envoyer des messages (texte et médias), vérifier les numéros de téléphone, gérer les contacts, lire les contacts, gérer les étiquettes, lire les étiquettes. Chaque endpoint ci-dessous indique la portée qu'il exige.

  3. 3

    Copiez-la une seule fois

    La clé commence par wap_ et n'est affichée qu'une fois. Conservez-la dans n8n comme identifiant (credential), jamais collée dans un paramètre de nœud où elle finirait dans le journal d'exécution.

  4. 4

    En option : limitez la clé à votre serveur n8n

    Une instance n8n auto-hébergée a une IP sortante stable, ce qui rend une clé API bien plus sûre que d'habitude. Renseignez les IP autorisées de la clé avec l'adresse de sortie de votre n8n ou sa plage CIDR, et une clé volée devient inutilisable depuis n'importe où ailleurs. Laissez le champ vide et la clé fonctionne depuis partout. Une erreur de saisie ne vous bloque jamais l'accès aux Paramètres, qui utilisent votre connexion Spun et non la clé.

Dans n8n, ajoutez la clé comme identifiant Header Auth : nom d'en-tête Authorization, valeur d'en-tête Bearer wap_YOUR_KEY. Réutilisez ce même identifiant dans chaque nœud Spun de chaque workflow.

2. Envoyez des messages WhatsApp depuis un workflow

Ajoutez un nœud HTTP Request, réglez la méthode et l'URL, rattachez l'identifiant Header Auth et envoyez du JSON. Tous les endpoints se trouvent sous la même URL de base, https://api.spun.com/api/integrations.

  • send-message (portée : envoyer des messages) : un message texte. Si le canal WhatsApp se trouve hors ligne, l'API répond 202 avec un queue_id au lieu d'échouer, et le message part dès que le canal se reconnecte.
  • send-media (envoyer des messages) : une image, une vidéo, un fichier audio, une note vocale ou un document, depuis une URL publique ou un envoi en base64, avec une légende facultative sur les images, les vidéos et les documents.
  • check-phone (vérifier les numéros de téléphone) : ce numéro a-t-il WhatsApp. Accepte jusqu'à 20 numéros en un seul appel, donc regroupez au lieu de boucler.
  • create-contact et update-contact (gérer les contacts) : gardez une fiche de prospect synchronisée depuis un formulaire, un CRM ou un tableur. Transmettre un numéro de téléphone met à jour le contact existant au lieu de créer un doublon.
  • contacts (lire les contacts) : retrouvez un contact par numéro de téléphone ou par identifiant.
  • apply-label et remove-label (gérer les étiquettes) : étiquetez une conversation à partir d'un déclencheur externe, par exemple appliquez l'étiquette « Nouveau prospect » dès qu'un formulaire est envoyé.
  • labels (lire les étiquettes) : listez les étiquettes du compte, ce qui est aussi le moyen le moins coûteux de confirmer qu'une clé fonctionne.
Envoyer un message WhatsApp (POST /api/integrations/send-message)
POST https://api.spun.com/api/integrations/send-message
Authorization: Bearer wap_YOUR_KEY
Content-Type: application/json

{
  "to": "15551234567",
  "text": "Hi {{ $json.first_name }}, thanks for getting in touch.",
  "idempotency_key": "{{ $execution.id }}"
}

Transmettez un idempotency_key lors des envois et donnez-lui une valeur stable pour l'exécution, comme {{ $execution.id }}. Si n8n relance le nœud, Spun reconnaît la clé au lieu d'envoyer le message deux fois.

3. Envoyez un fichier, une image ou une note vocale

Les médias passent par un endpoint distinct. Fournissez exactement l'un des deux : media_url, que Spun va chercher, ou media_base64, que Spun téléverse d'abord pour vous.

  • type vaut image, video, audio, voice ou document.
  • Une légende accompagne les images, les vidéos et les documents. Les fichiers audio et les notes vocales n'ont pas de légende dans WhatsApp.
  • Une note vocale envoyée en base64 est convertie automatiquement au format attendu par WhatsApp. Une note vocale transmise par URL est envoyée telle quelle, elle doit donc déjà être en ogg ou opus ; sinon, envoyez-la en base64 et laissez Spun la convertir.
  • Les médias ne sont volontairement pas mis en file d'attente lorsque le canal est hors ligne. Le texte est mis en file d'attente, les médias répondent 409 channel_offline à la place, parce que rejouer un média en file d'attente le livrerait sous forme de texte. Traitez le 409 avec les nouvelles tentatives de n8n plutôt que comme un échec définitif.
Envoyer un document (POST /api/integrations/send-media)
POST https://api.spun.com/api/integrations/send-media
Authorization: Bearer wap_YOUR_KEY
Content-Type: application/json

{
  "type": "document",
  "to": "15551234567",
  "media_url": "https://example.com/invoice-1043.pdf",
  "filename": "invoice-1043.pdf",
  "caption": "Your invoice"
}

4. Déclenchez un workflow à partir d'un événement WhatsApp

  1. 1

    Créez d'abord le nœud Webhook

    Ajoutez un nœud déclencheur Webhook à un nouveau workflow et copiez son URL de production (Production URL). n8n ne sert cette URL que lorsque le workflow est actif, activez-le donc avant de tester.

  2. 2

    Collez l'URL dans Spun

    « Paramètres », puis « Webhooks », puis « Ajouter un webhook ». Collez l'URL n8n, choisissez les événements qui doivent la déclencher, et enregistrez. Spun signe chaque livraison avec le secret affiché pour cet abonnement.

  3. 3

    Envoyez un message de test

    Écrivez au numéro WhatsApp connecté depuis votre téléphone. Le nœud Webhook récupère le vrai contenu, qui devient l'exemple à partir duquel vous construisez le reste du workflow.

  • Événements auxquels vous pouvez vous abonner : message entrant, message sortant, contact créé, contact mis à jour, contact supprimé, étiquette attribuée, flux de conversation terminé, message en file d'attente traité, prospect qualifié, conversation archivée et appel terminé.
  • X-Webhook-Signature est un HMAC-SHA256 du corps brut exact de la requête, écrit sha256 suivi du condensat hexadécimal. Vérifiez-le sur les octets bruts du corps, pas sur une copie re-sérialisée du JSON analysé, car l'ordre des clés n'est pas garanti après une analyse puis un ré-encodage.
  • Une livraison est retentée jusqu'à trois fois, immédiatement, puis après 5 secondes, puis après 30 secondes, et chaque tentative attend une réponse pendant 10 secondes. Toute réponse 2xx compte comme livrée.
  • En raison de ces nouvelles tentatives, le même événement peut arriver deux fois. event_id reste identique d'une tentative à l'autre pour un même événement, utilisez-le donc pour ignorer les doublons.
Ce que Spun envoie sur message.inbound
POST https://your-n8n.example.com/webhook/abc123
X-Webhook-Event: message.inbound
X-Webhook-Delivery: 550e8400-e29b-41d4-a716-446655440000
X-Webhook-Signature: sha256=<hmac of the raw body>

{
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "message.inbound",
  "timestamp": "2026-08-18T10:30:00.000Z",
  "org_id": "123",
  "data": {
    "message_id": "[email protected]_ABC123",
    "chat_id": "[email protected]",
    "from": "15551234567",
    "type": "text",
    "text": "Hello!"
  }
}

Vérifier la signature compte plus qu'il n'y paraît : l'URL du webhook est la seule chose qui protège le workflow, et les URL de webhook n8n sont suffisamment devinables pour justifier une vérification de signature.

Le contenu du webhook WhatsApp, champ par champ

Les événements de message transportent ce qu'un workflow doit d'ordinaire déduire lui-même. Le numéro du client arrive prêt à l'emploi au format international, les groupes sont signalés, le nom et l'e-mail du contact Spun sont fournis lorsque Spun les connaît, et les médias arrivent sous forme de lien signé que votre workflow peut récupérer pendant 24 heures.

  • peer_phone_e164 vaut null pour les groupes et pour les conversations sans numéro de téléphone associé.
  • Lorsqu'un fichier n'a pas fini d'être traité au moment de l'envoi de l'événement, media_pending vaut true et media_url vaut null. L'événement n'est pas renvoyé une fois le fichier prêt, ajoutez donc une note renvoyant à la conversation dans Spun.
  • conversation.closed se déclenche lorsqu'une conversation est archivée dans Spun et conversation.reopened lorsqu'elle est rouverte, ce qui permet à un workflow de garder un ticket ou une fiche aligné sur la boîte de réception.
  • Fermer ou rouvrir une conversation depuis votre workflow passe par POST /api/integrations/conversations/close et /reopen, qui exigent la portée « Fermer & Rouvrir les Conversations » sur la clé.
Champs supplémentaires sur message.inbound et message.outbound (à titre d'exemple)
{
  "is_group": false,
  "peer_phone_e164": "+15551234567",
  "contact_id": "8812",
  "contact_name": "Sarah Miller",
  "contact_email": "[email protected]",
  "type": "image",
  "text": null,
  "caption": "The damaged box",
  "media_url": "https://<signed link, valid for 24 hours>",
  "media_mime": "image/jpeg",
  "media_filename": null,
  "media_size": 182344,
  "media_pending": false
}

À lire aussi : Documentation : chaque événement et chaque champ, avec la signature et les nouvelles tentatives

Des workflows prêts à l'emploi pour les helpdesks

Les mêmes webhooks et la même API alimentent des workflows n8n prêts à l'emploi qui transforment les conversations WhatsApp en tickets de helpdesk et renvoient les réponses des agents sur WhatsApp. Chacun est accompagné d'un guide de configuration.

À lire aussi : Toutes les intégrations WhatsApp avec un helpdesk · Zendesk · Zoho Desk · Freshdesk · HubSpot Service Hub · Jira Service Management

5. La description complète de l'API

La description complète et lisible par machine de l'API est publiée sous forme de document OpenAPI 3.1, consultable librement et sans clé API. Chaque endpoint, champ de requête, forme de réponse, code d'erreur et l'enveloppe des webhooks y figurent, ce qui est généralement plus rapide que de lire un guide.

Spécification OpenAPI 3.1 publique
curl https://api.spun.com/api/integrations/openapi.json

n8n peut importer directement une description OpenAPI lors de la génération d'un nœud personnalisé ou d'un nœud HTTP déclaratif, c'est donc le chemin le plus court pour passer de zéro à un ensemble d'opérations qui fonctionne.

Un nœud Spun natif pour n8n

Tout ce qui précède utilise le nœud HTTP Request générique, c'est pourquoi cela fonctionne dès aujourd'hui sans attendre. Un nœud communautaire Spun dédié est développé et en cours de publication : il transforme les mêmes endpoints en opérations nommées avec de vrais champs, ajoute un identifiant Spun avec un test de connexion intégré, et donne au côté déclencheur un nœud qui s'abonne et se désabonne tout seul lorsque vous activez ou désactivez le workflow, en vérifiant pour vous la signature de chaque livraison.

Il ne figure pas encore dans le registre des nœuds communautaires n8n, il n'y a donc rien à installer pour le moment et cette page ne prétend pas le contraire. Deux fonctions arrivent avec lui : le déclencheur qui s'abonne tout seul, et l'interrogation planifiée de l'historique des messages pour le cas où une instance n8n ne peut pas du tout recevoir de webhooks entrants. Toutes deux dépendent d'autorisations de clé API qui ne sont pas encore proposées dans l'éditeur de clés, c'est pourquoi elles sont décrites ici plutôt que données sous forme d'instructions.

En attendant qu'il soit répertorié, la voie HTTP Request de cette page est la manière prise en charge d'utiliser Spun avec n8n, et elle le reste ensuite.

Ce que vous devez savoir avant de construire dessus

  • La limite est de 60 requêtes par minute et par clé API, tous endpoints confondus. Regroupez les vérifications de numéros jusqu'à 20 par appel, et placez un nœud Wait dans toute boucle qui parcourt une longue liste.
  • remove-label exige l'identifiant de l'étiquette, contrairement à apply-label qui accepte aussi un nom d'étiquette. Appelez l'endpoint labels une fois au début d'un workflow et conservez les identifiants.
  • Les abonnements webhook se créent aujourd'hui dans les Paramètres de Spun. Un outil de workflow ne peut pas encore créer son propre abonnement avec une clé que vous pouvez générer depuis l'éditeur de clés.
  • C'est une API fondée sur des clés. Il n'existe pas d'écran OAuth « connecter votre compte Spun » pour elle, et c'est voulu : les connexions d'assistants IA utilisent un mécanisme distinct, fondé sur le consentement, et des clés distinctes, et les deux ne peuvent pas être mélangés sur une même clé.
  • Tout est limité au numéro WhatsApp auquel appartient la clé. Un compte qui a plusieurs numéros a une clé par numéro plutôt qu'une seule clé couvrant tous les numéros.

À lire aussi : WhatsApp + Zapier et Make · WhatsApp + Google Sheets (entièrement natif, sans clé API) · WhatsApp + HubSpot CRM

Questions fréquentes

Dois-je attendre un nœud Spun officiel pour utiliser n8n ?

Non. Le nœud HTTP Request couvre toutes les actions dès aujourd'hui : envoi de texte et de médias, contacts, étiquettes et vérification des numéros, avec un nœud déclencheur Webhook pour les événements entrants. Un nœud natif est en cours de publication pour rendre ces mêmes choses plus faciles à configurer, pas pour les rendre possibles.

Existe-t-il un nœud Spun dans le registre communautaire de n8n ?

Pas encore. Le paquet est développé mais pas répertorié, il n'y a donc rien à installer pour le moment. La configuration HTTP Request de cette page fonctionne dès maintenant et continuera de fonctionner une fois le nœud répertorié.

Comment m'authentifier ?

Créez une clé API dans « Paramètres », puis « Webhooks », puis « Gérer les clés API », n'activez que les portées nécessaires, et conservez-la dans n8n comme identifiant Header Auth qui envoie Authorization : Bearer wap_YOUR_KEY. Vous pouvez aussi limiter la clé à l'adresse IP ou à la plage de votre serveur n8n.

Comment éviter que les nouvelles tentatives de n8n envoient deux fois le même message WhatsApp ?

Envoyez un idempotency_key avec la requête et gardez-le stable pour l'exécution, par exemple l'identifiant d'exécution n8n. Spun reconnaît une clé répétée et renvoie le résultat d'origine au lieu d'envoyer à nouveau.

Comment vérifier qu'un webhook vient bien de Spun ?

Chaque livraison porte X-Webhook-Signature, un HMAC-SHA256 du corps brut exact calculé avec le secret de l'abonnement, au format sha256 suivi du condensat hexadécimal. Calculez le même HMAC sur le corps brut de la requête et comparez. Utilisez les octets bruts plutôt que de ré-encoder le JSON analysé, car l'ordre des clés peut changer et la comparaison échouerait sur des livraisons parfaitement valides.

Que se passe-t-il si le canal WhatsApp est hors ligne pendant l'exécution de mon workflow ?

Les messages texte sont acceptés et mis en file d'attente, et la réponse vous l'indique avec un identifiant de file d'attente que vous pouvez interroger. Les médias ne sont pas mis en file d'attente et renvoient une erreur de canal hors ligne à la place, car un média en file d'attente arriverait sous forme de texte brut. Laissez n8n relancer ce nœud.

Quelles sont les limites de requêtes ?

60 requêtes par minute et par clé API, tous endpoints confondus. La vérification des numéros accepte 20 numéros en un seul appel, ce qui est le moyen le plus simple de rester largement sous la limite lors de la validation d'une liste.

Où se trouve la référence complète de l'API ?

Une description OpenAPI 3.1 de chaque endpoint est publiée à l'adresse https://api.spun.com/api/integrations/openapi.json et sa lecture ne nécessite aucune clé API.

Obtenez une clé API et commencez à construire

L'accès à l'API est disponible avec les formules WhatsApp de Spun, aux côtés de la boîte de réception d'équipe partagée, des réponses par IA et des intégrations natives Google Sheets et HubSpot. Prix fixe à partir de €45 par mois, essai gratuit.

Commencez gratuitement : 7 jours avec tout inclus

Voir toutes les intégrations