WhatsApp-Automatisierung selbst bauen: Anleitung mit der API

Wann ist der Eigenbau über die API sinnvoll?

Der Eigenbau kommt infrage, wenn eine vorhandene Anbindung Ihren gewünschten Ablauf nicht abdeckt und ein anderes Programm die Kundenreise starten soll.

Prüfen Sie deshalb zuerst die Integrationsübersicht. hellomateo bietet über 70 direkte Integrationen. Welche Daten eine Anbindung übernimmt, hängt vom jeweiligen System ab.

Liegen die benötigten Daten bereits in hellomateo, brauchen Sie möglicherweise keine API. Eine Kundenreise kann beispielsweise durch ein Datum am Kontakt oder einen Termin ausgelöst werden.

Für Betriebe ohne Technikkenntnisse ist der erste Weg der passende Einstieg, sofern er die Aufgabe abdeckt. Für die anderen Wege müssen Sie zusätzlich die Verbindung einrichten und prüfen.

Quellen: hellomateo: Integrationen; eigene Abrufe am 10. und 11.11.2026. Abgerufen am 11.11.2026.

Wie funktioniert der Ablauf mit einem API-Startsignal?

Bei diesem Aufbau legt die Kundenreise fest, was passiert, während die API den Ablauf für einen bestimmten Kontakt startet.

Ein Beispiel: Ein Auftrag wird in Ihrer anderen Software als fertig markiert. Dieses Ereignis soll eine Kundenreise in hellomateo starten, die eine vorbereitete Abholnachricht versendet.

Dafür müssen Sie zwei Dinge einrichten:

• Die Kundenreise in hellomateo: Auslöser „API-Anfrage“, passende Vorlage und gegebenenfalls Wartezeiten oder Bedingungen.
• Die Verbindung zur anderen Software: Sie erkennt das gewünschte Ereignis und übergibt den Kontakt an den Startabruf.

Die Tabelle oder die andere Software sendet dieses Signal nicht allein dadurch, dass Sie die Kundenreise angelegt haben. Dafür brauchen Sie einen eingerichteten Automatisierungsdienst oder ein Programm.

Die Anleitung erstellt die Kundenreise in der Oberfläche. Über die API wird anschließend ihre Ausführung gestartet.

Quellen: hellomateo: OpenAPI-Beschreibung, „Start Journey Execution“; Oberfläche von hellomateo, Stand 11.11.2026. Abgerufen am 11.11.2026.

Was brauchen Sie vor dem ersten Test?

Für den ersten Test brauchen Sie ein eingerichtetes WhatsApp-Konto in hellomateo, API-Zugang, eine passende Vorlage und einen Testkontakt mit Ihrer eigenen Nummer.

Prüfen Sie vor der Einrichtung:

• Zugang: Automatisierte Kundenreisen und die API sind ab dem Paket Business enthalten. Für das Paket Premium fragen Sie den API-Zugang als Zusatz an.
• WhatsApp: Die Nummer Ihres Betriebs muss in hellomateo eingerichtet sein.
• Vorlage: Verwenden Sie für diese Anleitung eine veröffentlichte und für das betreffende WhatsApp-Konto von Meta genehmigte Vorlage.
• Testkontakt: Verwenden Sie ausschließlich Ihre eigene Nummer und eindeutig erkennbare Testdaten.
• Einwilligung: Klären und dokumentieren Sie vor einem späteren Kundenversand, wen Sie für welchen Anlass anschreiben dürfen.

Die API kann Angaben zu transaktionaler Einwilligung und Werbezustimmung entgegennehmen. Ein gesetztes Feld ist jedoch kein Nachweis einer tatsächlich erteilten Zustimmung. Lassen Sie diese Angaben weder von einer KI erraten noch pauschal für eine Kontaktliste setzen.

Quellen: hellomateo: Preise; hellomateo: OpenAPI-Beschreibung, „ContactChannelStateWrite“ und „Send Message“; Oberfläche von hellomateo, Stand 11.11.2026. Abgerufen am 11.11.2026.

Wie bereiten Sie die Kundenreise vor?

Sie bereiten die Kundenreise vor, indem Sie eine Vorlage auswählen, den Auslöser „API-Anfrage“ einrichten und den Ablauf für den eigenen Test kontrollieren.

1. Vorlage vorbereiten. Schreiben Sie eine kurze Testnachricht. Prüfen Sie, welche Kontaktfelder ihre Platzhalter benötigen. Veröffentlichen Sie die Vorlage und prüfen Sie die Genehmigung für Ihr WhatsApp-Konto.
2. Kundenreise anlegen. Öffnen Sie „Reisen“ und wählen Sie den Auslöser „API-Anfrage“. Beginnen Sie mit einem überschaubaren Ablauf, etwa dem Versand einer einzigen Vorlage.
3. Ablauf kontrollieren. Prüfen Sie Vorlage, Versandkanal, Empfängerbezug und mögliche Folgeschritte. Verwenden Sie für den ersten Test keine weiteren Kundenkontakte.
4. Reise aktivieren. Nutzen Sie „Reise aktivieren“. Die Oberfläche weist gegebenenfalls darauf hin: „Veröffentliche diese Vorlage, bevor du die Reise aktivierst“.
5. Eigenes Token erstellen. Ein Administrator erstellt es unter „Einstellungen > Integrationen > API-Token“. Geben Sie ihm einen eindeutigen Namen für diesen Ablauf.

Ein API-Token lässt sich derzeit nicht mit eigenen Rechtestufen auf diesen einen Ablauf beschränken. Ein gesondertes Token erleichtert die Zuordnung, begrenzt seine Rechte aber nicht. Geben Sie es niemals in einen KI-Chat ein.

Ein Test der Kundenreise kann echte Nachrichten versenden. Verwenden Sie deshalb Ihre eigene Nummer.

Quellen: Oberfläche von hellomateo, Stand 11.11.2026.

Wie finden Sie die richtige Kennung?

Die Kennung für den Start steht im Feld „journey_id“ des passenden Eintrags aus „GET /v1/journeys/http-triggers“.

Die Antwort enthält mehrere Kennungen. Für den Startabruf brauchen Sie ausdrücklich „journey_id“, nicht „id“ oder „journey_version_id“. Prüfen Sie außerdem, ob der Eintrag zur vorbereiteten Kundenreise gehört.

Die Liste kann mehrere Seiten haben. Ist „next_page_url“ gesetzt, gibt es eine weitere Seite.

Der folgende optionale Befehl fragt die Liste ab. Er startet keine Kundenreise und versendet keine Nachricht. Öffnen Sie dafür ein Terminal unter macOS oder Linux. Das Terminal ist das Programmfenster für Texteingaben und Befehle. Der Befehl fragt Ihr Token verdeckt ab, damit Sie es nicht direkt in den Befehl schreiben müssen.

bash -c '
read -r -s -p "API-Token eingeben: " HELLOMATEO_TOKEN
printf "\n"
curl --silent --show-error \
  "https://api.getmateo.com/v1/journeys/http-triggers" \
  --header "Authorization: Bearer $HELLOMATEO_TOKEN" \
  --header "hellomateo-version: 2026-11-12"
'

hellomateo hat diesen Befehl am 11. November 2026 am eigenen Konto ausgeführt. Die erste Seite enthielt zehn Einträge und verwies auf eine weitere Seite. „2026-11-12“ ist die Versionskennung, die bei den Abrufen verwendet wurde.

Wenn Sie mit einem Terminal nicht vertraut sind, lassen Sie sich den lesenden Abruf anhand Ihres Betriebssystems erklären. Teilen Sie dabei weder das Token noch vollständige Antworten mit Kundendaten.

Quellen: eigener Abruf am 11.11.2026; hellomateo: OpenAPI-Beschreibung, „List HTTP Triggers“ und „Start Journey Execution“. Abgerufen am 11.11.2026.

Wie verbinden Sie einen Automatisierungsdienst mit der Kundenreise?

Ein Automatisierungsdienst muss das Ereignis aus Ihrer anderen Software erkennen und anschließend den Startabruf mit den passenden Daten ausführen.

Prüfen Sie zuerst, ob Ihr Dienst genau das benötigte Ereignis erkennt, beispielsweise die Änderung eines Auftragsstatus. Eine vorhandene Verbindung zur Software allein beantwortet diese Frage noch nicht.

Für den Startabruf beschreibt die API diese Angaben:

JSON ist ein Textformat mit benannten Datenfeldern. Name, Nummer und Kundennummer müssen den passenden Feldern der API zugeordnet werden. Zwei Kopfzeilen und eine Kennung reichen für den Start noch nicht.

Die Zapier-App von hellomateo bietet eigene Aktionen, etwa Kontakt anlegen und Vorlage senden, aber keine eigenen Auslöser. Diese Aktionen sind nicht automatisch mit dem Start einer Kundenreise gleichzusetzen.

Die Einrichtung mit Make, n8n und Zapier wurde für diese Anleitung nicht ausgeführt. Nutzen Sie die Tabelle als Grundlage für die Einrichtung und prüfen Sie den fertigen Ablauf zuerst mit Ihrer eigenen Nummer.

Quellen: hellomateo: OpenAPI-Beschreibung; Zapier: Mateo; n8n: HTTP Request; Make: HTTP. Abgerufen am 11.11.2026.

Wie hilft eine KI beim eigenen Programm?

Eine KI kann ein Programm für den Startabruf entwerfen und die lokale Einrichtung erklären, ersetzt aber weder den Test noch die Prüfung vor einem Kundenversand.

Beginnen Sie mit einer Datei, die nur Ihre eigenen Testdaten enthält. Für den ersten Programmentwurf brauchen Sie keine Kundenliste.

Übergeben Sie beispielsweise ChatGPT oder Claude diese Aufgabenbeschreibung:

Ein Programm nach dieser Aufgabenbeschreibung und den Start einer Kundenreise hat hellomateo nicht ausgeführt.

Prüfen Sie nach Ihrem eigenen Test die Kundenreise in hellomateo und den Eingang auf Ihrem Telefon. Eine angenommene Startanfrage belegt noch keine zugestellte Nachricht.

Erweitern Sie das Programm erst danach für Kundenkontakte. Dafür müssen Empfängerauswahl, dokumentierte Einwilligungen und der Schutz vor doppelten Starts gesondert geprüft werden. Eine Kundennummer allein ist kein belegter Schutz vor wiederholtem Versand.

Die Unterschiede zwischen KI-Chat, ausführendem KI-Werkzeug und Automatisierungsdienst erklärt der Überblick WhatsApp Business API mit KI nutzen.

Quellen: hellomateo: OpenAPI-Beschreibung, „Start Journey Execution“, „JourneyExecutionContact“ und „JourneyExecution“. Abgerufen am 11.11.2026.

Was wurde für diese Anleitung tatsächlich geprüft?

Für diese Anleitung wurden API-Listen gelesen und ein Testkontakt ohne Telefonnummer angelegt, geändert, abgerufen und gelöscht.

Aus der Löschprobe lässt sich nicht ableiten, welcher Abruf eine Löschung in jedem Fall zuverlässig bestätigt.

Nicht ausgeführt wurden der Start einer Kundenreise, ein Nachrichtenversand und die Einrichtung mit Make, n8n oder Zapier. Der Testkontakt hatte keine Telefonnummer.

Quellen: eigene Abrufe am 11.11.2026.

Welche Fehler sollten Sie beim Einrichten prüfen?

Prüfen Sie bei Fehlern zuerst die API-Adresse, die Versionskopfzeile, das Token und die übergebenen Felder.

Diese Fälle wurden am eigenen Konto beobachtet:

• Fehlende Versionskopfzeile: Antwort 400 mit „MISSING_VERSION_HEADER“.
• Falsches Token: Antwort 401 mit „UNAUTHORIZED“.
• Zusätzlicher Schrägstrich am Ende der getesteten Adresse: Antwort 404; die Gegenprobe ohne Schrägstrich war erfolgreich.
• Falsches Geburtsdatum: „11.11.1990“ wurde abgelehnt. Das dokumentierte Datumsformat ist „1990-11-11“.

Die weiteren Fehlerfälle, einschließlich der abgewiesenen Standardkennung von Python-urllib, stehen im Überblick zur API-Nutzung mit KI.

Übergeben Sie einer KI nur den bereinigten Fehlercode und die nötigen technischen Angaben. Entfernen Sie Token, Namen, Telefonnummern und andere Kundendaten. Wiederholen Sie einen Startabruf nach einer unklaren Antwort nicht ungeprüft.

Quellen: eigene Abrufe am 10. und 11.11.2026; hellomateo: OpenAPI-Beschreibung. Abgerufen am 11.11.2026.

Was kostet der Eigenbau, und wann ist er die günstigere Lösung?

Der Eigenbau kann eine kostengünstige Alternative zu einer eigens programmierten Schnittstelle sein, wenn Sie den Ablauf in der Oberfläche bauen und nur das Startsignal anschließen. Einen Kostenvergleich hat hellomateo dafür nicht gemessen.

Bei diesem Aufbau bleiben Nachrichtentext und Ablauf in hellomateo. Zusätzlich richten Sie die Verbindung ein, die das passende Ereignis erkennt und die Kundenreise startet.

Vergleichen Sie dafür:

• Software und Zugang: Automatisierte Kundenreisen und die API sind ab dem Paket Business enthalten. Für das Paket Premium fragen Sie den API-Zugang als Zusatz an.
• Zusätzliche Dienste: Klären Sie die Konditionen eines gegebenenfalls benötigten Automatisierungsdienstes.
• Nachrichten: Meta-Gebühren können anfallen. hellomateo gibt sie ohne Aufschlag weiter.
• Einrichtung und Pflege: Berücksichtigen Sie Ihre Arbeitszeit sowie benötigte Unterstützung bei Änderungen und Fehlern.

Eine fertige Integration sollte zuerst geprüft werden. Sie kann den benötigten Datenabgleich bereits abdecken. Ob der Eigenbau günstiger ist, hängt davon ab, was Sie zusätzlich einrichten und dauerhaft betreuen müssen.

Quellen: hellomateo: Preise; hellomateo: Integrationen. Abgerufen am 11.11.2026.