Das meiste, was man von einer WhatsApp-API erwartet, läuft auf vier Dinge hinaus: eine Nachricht senden, etwas nachschlagen, einen Datensatz ändern und benachrichtigt werden, wenn etwas passiert ist. Spun stellt alle vier über einfaches HTTP bereit, für dieselbe Nummer, auf der dein Team im Posteingang antwortet, authentifiziert mit einem Schlüssel, den du selbst erstellst und genau auf das beschränkst, was die Integration braucht.
Diese Seite ist die praktische Version: welche Endpunkte es gibt, wie Authentifizierung und Scopes funktionieren, was passiert, wenn deine WhatsApp-Nummer genau im Moment deines Aufrufs offline ist, und wo der maschinenlesbare Vertrag liegt.
Schlüssel, Scopes und wie weit ein Leak reicht
Die Authentifizierung läuft über ein Bearer-Token. Du erstellst einen Schlüssel in der App, er wird dir einmal angezeigt, und jede Anfrage trägt ihn in einem Authorization-Header. Spun speichert nur einen Hash des Schlüssels, ein verlorener Schlüssel lässt sich also nicht wiederherstellen, nur ersetzen.
Eine Minute wert ist der Teil mit den Scopes. Ein Schlüssel ist nicht einfach „Zugriff auf das Konto“: Er trägt eine Liste von Scopes, und jeder Endpunkt prüft genau den Scope, den er braucht. Ein Schlüssel nur mit read_contacts kann keine Nachricht senden. Ein Schlüssel nur mit send_message kann deine Kontaktliste nicht auslesen. Zusätzlich zu den Scopes kann ein Schlüssel ein Ablaufdatum und eine IP-Allowlist haben, sodass ein Schlüssel, der für einen Server mit fester Adresse ausgegeben wurde, sofort nicht mehr funktioniert, sobald er von irgendwo anders benutzt wird.
- send_message deckt das Senden von Text und Medien ab sowie das Abrufen eines Versands aus der Warteschlange.
- read_contacts, read_messages und read_labels sind die Leseseite, einzeln vergebbar.
- manage_contacts und manage_labels decken Erstellen, Aktualisieren und das Setzen von Labels ab.
- check_phone beantwortet, ob eine Nummer auf WhatsApp erreichbar ist.
- manage_webhooks erstellt, listet und löscht Webhook-Abonnements.
Anfrage
curl -X POST https://api.spun.com/api/integrations/send-message \
-H "Authorization: Bearer wap_0f3c9a1d7b524e86a1c05d9e2f7b48ac" \
-H "Content-Type: application/json" \
-d '{
"to": "+14155550142",
"text": "Your appointment is confirmed for Thursday at 10:00.",
"idempotency_key": "booking-8871"
}'Antwort
HTTP/1.1 200 OK
Content-Type: application/json
{
"success": true,
"message_id": "yq0Zt9C1sK2mfE7x"
}Schlüssel, die für den MCP-Server von Spun erstellt wurden, werden von dieser API bewusst abgelehnt, auch wenn sie gültige Schlüssel sind. Die beiden Schnittstellen haben unterschiedliche Freigaberegeln, und ein Schlüssel für die eine lässt sich nicht stillschweigend auf der anderen verwenden.
Siehe auch: Einen KI-Assistenten verbinden, statt Code zu schreiben
Was die Endpunkte der WhatsApp-API wirklich abdecken
Die Schnittstelle ist bewusst klein und stabil, statt das Produkt vollständig zu spiegeln. Sie existiert, damit ein externes System das tun kann, was externe Systeme wirklich tun müssen.
- Senden: eine Textnachricht oder Medien, entweder als URL oder als base64, mit optionaler Bildunterschrift.
- Kontakte: einen Kontakt erstellen, einen aktualisieren und Kontakte mit Cursor-Paginierung auflisten.
- Labels: die Labels im Arbeitsbereich auflisten, eines auf eine Unterhaltung anwenden, eines entfernen.
- Nachrichten: Nachrichten mit Cursor-Paginierung auflisten, zum Synchronisieren in ein Data Warehouse oder ein CRM.
- Nummer prüfen: bestätigen, dass eine Nummer auf WhatsApp ist, bevor du eine Liste darum herum aufbaust.
- Warteschlange: einen Versand nachschlagen, der in die Warteschlange kam, weil die Nummer offline war.
- Webhooks: Abonnements erstellen, auflisten und löschen.
Der maschinenlesbare Vertrag ist unter /api/integrations/openapi.json veröffentlicht und lässt sich ohne Schlüssel lesen. So können die Autorin eines n8n-Nodes, der Entwickler einer Zapier-App oder dein eigener Generator die Spezifikation abrufen, bevor ihnen überhaupt jemand Zugangsdaten ausgestellt hat.
Was passiert, wenn die WhatsApp-Nummer offline ist
Das ist der Teil, der Leute überrascht, deshalb lohnt es sich, ihn klar auszusprechen. Spun sendet über eine laufende WhatsApp-Sitzung, und eine laufende Sitzung kann genau in der Sekunde getrennt sein, in der dein Code aufruft. Die API tut nicht so, als wäre es anders, und sie verhält sich bei Text und bei Medien bewusst unterschiedlich.
Ein Textversand an eine Nummer, die offline ist, liefert 202 statt eines Fehlers, mit einer Warteschlangen-ID. Die Nachricht wird zurückgehalten und zugestellt, sobald die Nummer wieder verbunden ist, und du kannst am Warteschlangen-Endpunkt abfragen, was aus ihr geworden ist. Ein Medienversand an eine Nummer, die offline ist, liefert stattdessen einen Konflikt und sendet nichts. Diese Asymmetrie ist Absicht: Die Warteschlange stellt Nachrichten als Text zu, ein Bild aus der Warteschlange käme also als Bildunterschrift ohne Bild an. Ein deutlicher Fehler ist das bessere Ergebnis, und deine Wiederholungslogik entscheidet, wie es weitergeht.
Das Rate-Limit liegt bei 60 Anfragen pro Minute und Schlüssel, mit den üblichen Rate-Limit-Headern in jeder Antwort. So kann ein Client anhand der Header bremsen, statt erst auf eine 429 zu reagieren, mit der er nicht gerechnet hat.
Webhooks: benachrichtigt werden statt abfragen
Einen Nachrichten-Endpunkt per Timer abzufragen passt nicht zu einer Unterhaltung, deshalb kann die API stattdessen pushen. Du registrierst eine URL und die Ereignisse, die dich interessieren, und Spun sendet per POST einen JSON-Body dorthin, sobald sie eintreten.
Jede Zustellung trägt in Headern den Ereignisnamen und eine eindeutige Zustellungs-ID und, wenn das Abonnement ein Signiergeheimnis hat, eine HMAC-SHA256-Signatur genau dieses Bodys. Prüfe die Signatur, bevor du dem Inhalt vertraust: Sie ist das Einzige, was deinen Endpunkt von jedem trennt, der die URL erfährt. Das Geheimnis wird einmal zurückgegeben, wenn du das Abonnement erstellst, und danach nie wieder.
- Nachrichtenereignisse, eingehend und ausgehend.
- Kontakt erstellt, aktualisiert und gelöscht.
- Label zugewiesen.
- Chat-Flow abgeschlossen, Versand aus der Warteschlange verarbeitet, Lead qualifiziert.
- Unterhaltung geschlossen, Anruf beendet und Phase in der Vertriebspipeline geändert.
Siehe auch: Spun mit Zapier und Make verbinden · Spun mit n8n verbinden · Ein Helpdesk-System anbinden: Zendesk, Zoho Desk, Freshdesk, HubSpot Service Hub, Jira
Grenzen und ehrliche Einschränkungen
- Das ist nicht die WhatsApp Business API. Es ist die eigene API von Spun vor deiner verknüpften Nummer, also gibt es keine Nachrichtenvorlagen, die genehmigt werden müssen, und keine Gebühren pro Nachricht, aber ebenso keine offiziellen Garantien von Meta.
- Sechzig Anfragen pro Minute und Schlüssel. Arbeit in großen Mengen gehört in Kampagnen, die ihr Tempo selbst sauber steuern, nicht in eine enge API-Schleife.
- Die Endpunktliste oben ist heute die gesamte Schnittstelle. Was nicht darauf steht, ist nicht freigegeben, und auf keinen undokumentierten Endpunkt solltest du dich verlassen.
- Ein Schlüssel hat Scopes, gilt aber nicht pro Person. Behandle ihn wie Zugangsdaten des Arbeitsbereichs und tausche ihn aus, wenn jemand mit Zugriff geht.
- Wer an Menschen sendet, die nie eingewilligt haben, bekommt die Nummer von WhatsApp eingeschränkt, egal welchen Weg die Nachricht genommen hat.
Siehe auch: Wie Spun sich mit WhatsApp verbindet