Einrichtungsanleitung

WhatsApp + n8n: WhatsApp aus deinen Workflows senden und empfangen

Funktioniert heute mit dem HTTP Request NodeZuletzt geprüft: Oktober 2026

Spun hat eine REST API, die genau für diese Art von Automatisierung gebaut ist, und n8n braucht nichts Besonderes, um sie zu nutzen: Ein HTTP Request Node mit einem Bearer-Token sendet WhatsApp-Nachrichten, lädt Medien hoch, erstellt und aktualisiert Kontakte, setzt Labels und prüft, ob eine Nummer WhatsApp hat. Ein Webhook-Trigger-Node empfängt echte WhatsApp-Ereignisse zurück, signiert, damit du nachweisen kannst, dass sie von Spun kommen.

Diese Seite beschreibt den Weg, der heute funktioniert, geschrieben anhand der Live-API statt einer Roadmap. Wo etwas noch nicht selbst einrichtbar ist, sagt sie das, statt etwas anderes vorzutäuschen.

1. Erstelle einen API-Schlüssel

  1. 1

    Öffne die API-Schlüssel

    In deinem Spun-Posteingang: „Einstellungen“, dann „Webhooks“, dann „API-Schlüssel verwalten“, dann „Neuer Schlüssel“.

  2. 2

    Benennen und Berechtigungen wählen

    Gib ihm einen Namen wie „n8n Production“. Aktiviere nur, was der Workflow braucht: Nachrichten senden (für Text und Medien), Telefonnummern prüfen, Kontakte verwalten, Kontakte lesen, Labels verwalten, Labels lesen. Bei jedem Endpoint unten steht, welche Berechtigung er verlangt.

  3. 3

    Nur einmal kopieren

    Der Schlüssel beginnt mit wap_ und wird nur einmal angezeigt. Speichere ihn in n8n als Credential (Zugangsdaten), nie direkt in einen Node-Parameter eingefügt, wo er im Ausführungsprotokoll landet.

  4. 4

    Optional: Beschränke den Schlüssel auf deinen n8n-Server

    Ein selbst gehostetes n8n hat eine feste ausgehende IP, was einen API-Schlüssel deutlich sicherer macht als sonst. Trag bei „Erlaubte IPs“ des Schlüssels die ausgehende Adresse oder den CIDR-Bereich deines n8n ein, dann ist ein gestohlener Schlüssel von überall sonst nutzlos. Lässt du das Feld leer, funktioniert der Schlüssel von überall. Ein Fehler dabei sperrt dich nie aus den „Einstellungen“ aus, denn die nutzen deinen Spun-Login und nicht den Schlüssel.

Füge den Schlüssel in n8n als Credential vom Typ Header Auth hinzu: Header-Name Authorization, Header-Wert Bearer wap_YOUR_KEY. Nutze dieses eine Credential in jedem Spun-Node jedes Workflows.

2. Sende WhatsApp-Nachrichten aus einem Workflow

Füge einen HTTP Request Node hinzu, stell Methode und URL ein, hänge das Header-Auth-Credential an und sende JSON. Alle Endpoints liegen unter derselben Basis-URL, https://api.spun.com/api/integrations.

  • send-message (Berechtigung: Nachrichten senden): eine Textnachricht. Ist der WhatsApp-Kanal gerade offline, antwortet die API mit 202 und einer queue_id, statt fehlzuschlagen, und die Nachricht geht raus, sobald der Kanal wieder verbunden ist.
  • send-media (Nachrichten senden): ein Bild, ein Video, eine Audiodatei, eine Sprachnachricht oder ein Dokument, über eine öffentliche URL oder einen Base64-Upload, mit optionaler Bildunterschrift bei Bildern, Videos und Dokumenten.
  • check-phone (Telefonnummern prüfen): Hat diese Nummer WhatsApp? Nimmt bis zu 20 Nummern in einem Aufruf an, also bündeln statt in einer Schleife abfragen.
  • create-contact und update-contact (Kontakte verwalten): Halte einen Lead-Datensatz aus einem Formular, einem CRM oder einer Tabelle synchron. Wenn du eine Telefonnummer übergibst, wird der bestehende Kontakt aktualisiert, statt ein Duplikat anzulegen.
  • contacts (Kontakte lesen): Schlag einen Kontakt über Telefonnummer oder ID nach.
  • apply-label und remove-label (Labels verwalten): Versieh einen Chat über einen externen Auslöser mit einem Label, zum Beispiel mit „Neuer Lead“, sobald ein Formular abgeschickt wird.
  • labels (Labels lesen): Liste die Labels im Konto auf, zugleich der günstigste Weg, um zu prüfen, ob ein Schlüssel funktioniert.
Eine WhatsApp-Nachricht senden (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 }}"
}

Übergib beim Senden einen idempotency_key und setz ihn auf einen für die Ausführung festen Wert, etwa {{ $execution.id }}. Wiederholt n8n den Node, erkennt Spun den Schlüssel, statt die Nachricht zweimal zu senden.

3. Sende eine Datei, ein Bild oder eine Sprachnachricht

Medien gehen an einen eigenen Endpoint. Gib genau eines von beiden an: media_url, das Spun abruft, oder media_base64, das Spun zuerst für dich hochlädt.

  • type ist einer der Werte image, video, audio, voice oder document.
  • Eine Bildunterschrift wird bei Bildern, Videos und Dokumenten mitgesendet. Audiodateien und Sprachnachrichten haben in WhatsApp keine Bildunterschrift.
  • Eine als Base64 gesendete Sprachnachricht wird automatisch in das Format umgewandelt, das WhatsApp erwartet. Eine als URL übergebene Sprachnachricht wird genau so gesendet, wie sie ist, sie muss also bereits ogg oder opus sein; andernfalls sende sie als Base64 und lass Spun sie umwandeln.
  • Medien werden bewusst nicht in die Warteschlange gestellt, wenn der Kanal offline ist. Text kommt in die Warteschlange, Medien antworten stattdessen mit 409 channel_offline, weil das erneute Abspielen einer wartenden Mediennachricht sie als Text zustellen würde. Behandle 409 mit der Wiederholungsfunktion von n8n, statt es als dauerhaften Fehler zu werten.
Ein Dokument senden (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. Löse einen Workflow durch ein WhatsApp-Ereignis aus

  1. 1

    Erstelle zuerst den Webhook-Node

    Füge einem neuen Workflow einen Webhook-Trigger-Node hinzu und kopiere dessen Production URL. n8n stellt diese URL nur bereit, solange der Workflow aktiv ist, also aktiviere ihn vor dem Testen.

  2. 2

    Füge die URL in Spun ein

    „Einstellungen“, dann „Webhooks“, dann „Webhook hinzufügen“. Füge die n8n-URL ein, wähle, welche Ereignisse sie auslösen sollen, und speichere. Spun signiert jede Zustellung mit dem Secret, das für dieses Abonnement angezeigt wird.

  3. 3

    Sende eine Testnachricht

    Schreib der verbundenen WhatsApp-Nummer von deinem Handy aus. Der Webhook-Node empfängt die echte Payload, das Beispiel, anhand dessen du den Rest des Workflows baust.

  • Ereignisse, die du abonnieren kannst: eingehende Nachricht, ausgehende Nachricht, Kontakt erstellt, Kontakt aktualisiert, Kontakt gelöscht, Label zugewiesen, Chat-Flow abgeschlossen, Nachricht aus der Warteschlange verarbeitet, Lead qualifiziert, Chat archiviert und Anruf beendet.
  • X-Webhook-Signature ist ein HMAC-SHA256 des exakten rohen Anfragekörpers, geschrieben als sha256 gefolgt vom Hex-Digest. Prüfe sie gegen die rohen Bytes des Körpers, nicht gegen eine neu serialisierte Kopie des geparsten JSON, denn die Reihenfolge der Schlüssel übersteht Parsen und erneutes Kodieren nicht garantiert.
  • Eine Zustellung wird bis zu dreimal wiederholt, sofort, dann nach 5 Sekunden, dann nach 30 Sekunden, und jeder Versuch wartet 10 Sekunden auf eine Antwort. Jede 2xx-Antwort gilt als zugestellt.
  • Wegen dieser Wiederholungen kann dasselbe Ereignis zweimal ankommen. event_id bleibt über die Wiederholungen eines Ereignisses gleich, nutze sie also, um Duplikate zu überspringen.
Was Spun bei message.inbound sendet
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!"
  }
}

Die Signaturprüfung ist wichtiger, als sie aussieht: Die Webhook-URL ist das Einzige, was den Workflow schützt, und n8n-Webhook-URLs sind leicht genug zu erraten, dass sich eine Prüfung der Signatur lohnt.

Die WhatsApp-Webhook-Payload, Feld für Feld

Nachrichtenereignisse liefern mit, was ein Workflow sonst selbst ermitteln müsste. Die Nummer des Kunden kommt direkt nutzbar im internationalen Format, Gruppen sind gekennzeichnet, Name und E-Mail des Spun-Kontakts kommen mit, wenn Spun sie hat, und Medien kommen als signierter Link, den dein Workflow 24 Stunden lang abrufen kann.

  • peer_phone_e164 ist null bei Gruppen und bei Chats ohne zugehörige Telefonnummer.
  • Ist eine Datei beim Senden des Ereignisses noch nicht fertig verarbeitet, ist media_pending true und media_url null. Das Ereignis wird nicht erneut gesendet, wenn die Datei fertig ist, füge also eine Notiz hinzu, die auf die Unterhaltung in Spun verweist.
  • conversation.closed wird ausgelöst, wenn ein Chat in Spun archiviert wird, und conversation.reopened, wenn er zurückgeholt wird. So hält ein Workflow ein Ticket oder einen Datensatz mit dem Posteingang auf dem gleichen Stand.
  • Das Schließen oder Wiedereröffnen einer Unterhaltung aus deinem Workflow läuft über POST /api/integrations/conversations/close und /reopen, die am Schlüssel die Berechtigung „Gespräche schließen & erneut öffnen“ benötigen.
Zusätzliche Felder bei message.inbound und message.outbound (Beispiel)
{
  "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
}

Siehe auch: Doku: alle Ereignisse und Felder, mit Details zu Signatur und Wiederholungen

Fertige Workflows für Helpdesks

Dieselben Webhooks und dieselbe API treiben fertige n8n-Workflows an, die WhatsApp-Unterhaltungen in Helpdesk-Tickets verwandeln und Antworten von Agenten zurück an WhatsApp senden. Zu jedem gibt es eine Einrichtungsanleitung.

Siehe auch: Alle WhatsApp-Helpdesk-Integrationen · Zendesk · Zoho Desk · Freshdesk · HubSpot Service Hub · Jira Service Management

5. Die vollständige API-Beschreibung

Die vollständige maschinenlesbare Beschreibung der API ist als OpenAPI-3.1-Dokument veröffentlicht, frei abrufbar und ohne API-Schlüssel. Jeder Endpoint, jedes Anfragefeld, jede Antwortstruktur, jeder Fehlercode und der Webhook-Umschlag stehen darin, was meist schneller geht, als eine Anleitung zu lesen.

Öffentliche OpenAPI-3.1-Spezifikation
curl https://api.spun.com/api/integrations/openapi.json

n8n kann eine OpenAPI-Beschreibung direkt importieren, wenn du einen eigenen Node oder einen deklarativen HTTP-Node erzeugst. Das ist also der kürzeste Weg von null zu einem funktionierenden Satz an Operationen.

Ein nativer Spun-Node für n8n

Alles oben nutzt den generischen HTTP Request Node, deshalb funktioniert es heute ohne Warten. Ein eigener Spun-Community-Node ist gebaut und wird gerade veröffentlicht: Er macht aus denselben Endpoints benannte Operationen mit richtigen Feldern, bringt ein Spun-Credential mit eingebautem Verbindungstest mit und gibt der Trigger-Seite einen Node, der sich beim Aktivieren oder Deaktivieren des Workflows selbst an- und abmeldet und dabei die Signatur jeder Zustellung für dich prüft.

Er ist noch nicht im Community-Node-Verzeichnis von n8n, es gibt also derzeit nichts zu installieren, und diese Seite tut auch nicht so. Zwei Funktionen kommen mit ihm: der Trigger, der sich selbst abonniert, und das zeitgesteuerte Abfragen des Nachrichtenverlaufs für den Fall, dass eine n8n-Instanz überhaupt keine eingehenden Webhooks empfangen kann. Beide hängen von API-Schlüssel-Berechtigungen ab, die im Schlüssel-Editor noch nicht angeboten werden, deshalb werden beide hier beschrieben statt als Anleitung gegeben.

Bis er gelistet ist, ist der HTTP-Request-Weg auf dieser Seite die unterstützte Art, Spun mit n8n zu nutzen, und er bleibt auch danach unterstützt.

Was du wissen solltest, bevor du darauf aufbaust

  • Das Ratenlimit liegt bei 60 Anfragen pro Minute pro API-Schlüssel über alle Endpoints. Bündle Nummernprüfungen mit bis zu 20 pro Aufruf und setz einen Wait-Node in jede Schleife, die eine lange Liste abarbeitet.
  • remove-label braucht die ID des Labels, anders als apply-label, das auch einen Label-Namen annimmt. Ruf den Endpoint labels einmal am Anfang eines Workflows auf und behalte die IDs.
  • Webhook-Abonnements werden heute in den Spun-„Einstellungen“ angelegt. Ein Workflow-Tool kann mit einem Schlüssel, den du im Schlüssel-Editor erzeugen kannst, noch kein eigenes Abonnement anlegen.
  • Das ist eine schlüsselbasierte API. Es gibt dafür keinen OAuth-Bildschirm „Connect your Spun account“, und das ist Absicht: Verbindungen von KI-Assistenten nutzen einen separaten, zustimmungsbasierten Mechanismus und separate Schlüssel, und beides lässt sich nicht auf einem Schlüssel mischen.
  • Alles ist auf die WhatsApp-Nummer beschränkt, zu der der Schlüssel gehört. Ein Konto mit mehreren Nummern hat einen Schlüssel pro Nummer statt eines Schlüssels für alle.

Siehe auch: WhatsApp + Zapier und Make · WhatsApp + Google Sheets (vollständig nativ, kein API-Schlüssel nötig) · WhatsApp + HubSpot CRM

Häufige Fragen

Muss ich auf einen offiziellen Spun-Node warten, um n8n zu nutzen?

Nein. Der HTTP Request Node deckt heute jede Aktion ab: Text und Medien senden, Kontakte, Labels und Nummernprüfungen, dazu ein Webhook-Trigger-Node für eingehende Ereignisse. Ein nativer Node wird veröffentlicht, damit sich dieselben Dinge leichter konfigurieren lassen, nicht damit sie überhaupt möglich werden.

Gibt es einen Spun-Node im Community-Verzeichnis von n8n?

Noch nicht. Das Paket ist gebaut, aber nicht gelistet, es gibt also derzeit nichts zu installieren. Die HTTP-Request-Einrichtung auf dieser Seite funktioniert jetzt und funktioniert auch weiter, wenn der Node gelistet ist.

Wie authentifiziere ich mich?

Erstelle einen API-Schlüssel unter „Einstellungen“, dann „Webhooks“, dann „API-Schlüssel verwalten“, aktiviere nur die Berechtigungen, die du brauchst, und speichere ihn in n8n als Header-Auth-Credential, das Authorization: Bearer wap_YOUR_KEY sendet. Du kannst den Schlüssel außerdem auf die IP-Adresse oder den Adressbereich deines n8n-Servers beschränken.

Wie verhindere ich, dass Wiederholungen in n8n dieselbe WhatsApp-Nachricht zweimal senden?

Sende einen idempotency_key mit der Anfrage und halte ihn für die Ausführung konstant, zum Beispiel die Ausführungs-ID von n8n. Spun erkennt einen wiederholten Schlüssel und gibt das ursprüngliche Ergebnis zurück, statt erneut zu senden.

Wie prüfe ich, dass ein Webhook wirklich von Spun kommt?

Jede Zustellung trägt X-Webhook-Signature, ein HMAC-SHA256 des exakten rohen Körpers mit dem Secret des Abonnements, formatiert als sha256 gefolgt vom Hex-Digest. Berechne denselben HMAC über den rohen Anfragekörper und vergleiche. Nutze die rohen Bytes, statt das geparste JSON neu zu kodieren, denn die Reihenfolge der Schlüssel kann sich ändern, und der Vergleich würde dann bei völlig gültigen Zustellungen fehlschlagen.

Was passiert, wenn der WhatsApp-Kanal offline ist, während mein Workflow läuft?

Textnachrichten werden angenommen und in die Warteschlange gestellt, und die Antwort sagt dir das, mit einer Warteschlangen-ID, die du abfragen kannst. Medien werden nicht in die Warteschlange gestellt und liefern stattdessen einen Fehler „Kanal offline“, weil eine wartende Mediennachricht als reiner Text ankommen würde. Lass n8n diesen Node wiederholen.

Wie hoch sind die Ratenlimits?

60 Anfragen pro Minute pro API-Schlüssel, über alle Endpoints. Die Nummernprüfung nimmt 20 Nummern in einem Aufruf an, so bleibst du beim Prüfen einer Liste am einfachsten deutlich unter dem Limit.

Wo finde ich die vollständige API-Referenz?

Eine OpenAPI-3.1-Beschreibung jedes Endpoints ist unter https://api.spun.com/api/integrations/openapi.json veröffentlicht und lässt sich ohne API-Schlüssel lesen.

Hol dir einen API-Schlüssel und fang an zu bauen

API-Zugriff gibt es in den WhatsApp-Plänen von Spun, neben dem gemeinsamen Team-Posteingang, KI-Antworten und den nativen Integrationen für Google Sheets und HubSpot. Festpreis ab €45 pro Monat, kostenlose Testversion.

Kostenlos starten

Alle Integrationen ansehen