API-Einführung

Mit der Flowella REST API können Sie WhatsApp-Nachrichten versenden, Kontakte und Opt-Outs verwalten, Vorlagen für Listen- und Massensendungen erstellen und Analysen abrufen - und zwar programmatisch. Auf dieser Seite erfahren Sie alles, was Sie wissen müssen, bevor Sie einen Endpunkt aufrufen. Die vollständige Endpunktreferenz finden Sie in der Seitenleiste API-Referenz (automatisch generiert aus der OpenAPI-Spezifikation).

Basis-URL

https://api.flowella.io/v1

Alle v1-Endpunkte liegen unter dieser kanonischen Basis — zum Beispiel https://api.flowella.io/v1/messages.

Die API lag zuvor auf dem App-Host unter https://app.flowella.io/api/v1/.... Anfragen an diesen Legacy-Pfad werden dauerhaft (308) auf https://api.flowella.io/v1/... umgeleitet, wobei Methode und Body erhalten bleiben — bestehende Integrationen funktionieren also weiter. Aktualisieren Sie Ihre Basis-URL bei Gelegenheit, um den zusätzlichen Hop zu sparen.

Authentifizierung

Jede Anfrage benötigt einen API-Schlüssel im Authorization-Header:

Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx

Schlüssel sind organisationsbezogen - sie wirken auf eine einzelne Flowella-Organisation und erben die Berechtigungen eines Administrators in dieser Organisation.

Behandeln Sie Schlüssel wie Passwörter. Übertragen Sie sie niemals in die Versionskontrolle, fügen Sie sie niemals in Chats oder gemeinsame Dokumente ein und wechseln Sie sie aus, wenn Teammitglieder die Organisation verlassen. Siehe Einstellungen → API-Schlüssel für Schritte zur Rotation.

Einen Schlüssel erstellen

Sie benötigen die Rolle Owner oder Admin, um API-Schlüssel zu verwalten.

Gehen Sie zu Einstellungen → API-Schlüssel in der Flowella-App.
Klicken Sie auf Schlüssel erstellen und geben Sie ihm einen einprägsamen Namen.
Kopieren Sie den Schlüssel einmal - er wird nur zum Zeitpunkt der Erstellung angezeigt.

Behandeln Sie Schlüssel wie Passwörter: Übertragen Sie sie nie in die Versionsverwaltung, fügen Sie sie nie im Chat ein und wechseln Sie sie aus, wenn Teamkollegen die Organisation verlassen.

Überprüfen eines Schlüssels

Drücken Sie den Ping-Endpunkt, um zu bestätigen, dass ein Schlüssel gültig ist:

curl https://api.flowella.io/v1/ping \
  -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx"

await fetch("https://api.flowella.io/v1/ping", {
  headers: { Authorization: `Bearer ${process.env.FLOWELLA_API_KEY}` },
});

import os, requests

requests.get(
    "https://api.flowella.io/v1/ping",
    headers={"Authorization": f"Bearer {os.environ['FLOWELLA_API_KEY']}"},
)

Ein 200 OK mit { "ok": true, "organizationId": "…" } bedeutet, dass Sie authentifiziert sind.

Fehler

Alle Fehler werden in einem einheitlichen Umschlag zurückgegeben:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

HTTP-Status	Wann Sie es sehen werden
`400`	Validierung fehlgeschlagen, fehlerhafter Body oder vorgelagerte Meta Ablehnung
`401`	Fehlender oder ungültiger API-Schlüssel
`402`	Zahlung erforderlich - Ihr Abonnement deckt die Aktion nicht ab
`403`	Verboten - z.B. Senden an einen abgemeldeten Kontakt, oder Meta ist nicht verbunden
`404`	Der angeforderte Kanal oder die angeforderte Ressource existiert nicht
`429`	Ratenbeschränkung - langsamer werden

Das Feld error.code ist stabil und kann sicher programmatisch eingeschaltet werden. Das error.message-Feld ist von Menschen lesbar und kann sich ändern.

Ratenbegrenzung

API-Schlüssel haben ein Ratenlimit pro Organisation. Wenn Sie das Limit überschreiten, erhalten Sie eine 429 mit dem Code RATE_LIMITED und der Nachricht Too many requests. Sofern vorhanden, teilt Ihnen der Antwort-Header Retry-After mit, wie viele Sekunden Sie warten sollten. Gehen Sie zurück und versuchen Sie es mit exponentieller Verzögerung erneut. Wenn Sie große Mengen senden, bevorzugen Sie POST /v1/templates/send mit dem Parameter throttlePerHour - Flowella setzt die Drosselung serverseitig durch, so dass Sie die Anfragen nicht selbst steuern müssen.

Idempotenzschlüssel

Massensendungen von Vorlagen sind asynchron. POST /v1/templates/send validiert die Anfrage, stellt sie dauerhaft in die Warteschlange und gibt sofort 202 Accepted zurück:

{
  "id": "v1ts-0123456789abcdef",
  "status": "accepted"
}

Flowella stellt den Stapel im Hintergrund zu und wiederholt temporäre WhatsApp-Fehler automatisch. Empfänger werden einzeln verarbeitet, sodass eine ungültige Nummer nicht den Rest des Stapels blockiert. Verfolgen Sie den Zustellfortschritt auf dem Tab Statistiken der Vorlage in der App. Da die Zustellung nach der Antwort erfolgt, müssen Wiederholungen sicher sein. Übergeben Sie einen Idempotency-Key-Header (bis zu 200 Zeichen), der jeden Stapel eindeutig identifiziert:

curl -X POST "https://api.flowella.io/v1/templates/send" \
  -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: campaign-2026-08-31-launch" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "whatsappChannelId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "recipients": [{ "phone": "+15551234567" }]
  }'

Wiederholungen desselben Schlüssels innerhalb von sieben Tagen geben die ursprüngliche Auftrags-id zurück, anstatt eine neue Sendung anzulegen. Sie können eine Anfrage nach einem Timeout oder Netzwerkfehler gefahrlos wiederholen, ohne jemandem zweimal zu schreiben. Wenn Sie den Header weglassen, leitet Flowella einen Schlüssel aus dem Anfrage-Body ab. Ein identischer Stapel, der zweimal kurz hintereinander übermittelt wird, wird daher nicht doppelt gesendet. Ein expliziter Schlüssel ist dennoch sicherer, da jede Änderung am Body (selbst eine Umsortierung der Empfänger) einen neuen abgeleiteten Schlüssel erzeugt.

Paginierung

Listenendpunkte (/conversations, /contacts, /templates) verwenden Cursor-Paginierung:

Übergeben Sie limit (1-100, Standardwert 25) und ein optionales cursor.
Die Antwort enthält items und, wenn es mehr Ergebnisse gibt, ein nextCursor.
Geben Sie nextCursor als Parameter cursor zurück, um die nächste Seite zu holen.
Wenn nextCursor fehlt, haben Sie das Ende erreicht.

curl "https://api.flowella.io/v1/conversations?limit=50" \
  -H "Authorization: Bearer flo_xxxxxxxxxxxxxxxxxxxxxxxx"

Datum und Uhrzeit

Alle Zeitstempel sind ISO 8601-Strings in UTC (zum Beispiel 2025-01-15T14:30:00.000Z). Wenn die API Datumsangaben akzeptiert, werden sowohl reine Datumsangaben (2025-01-15) als auch vollständige ISO 8601-Zeichenfolgen server-seitig erzwungen.

Telefonnummern

Übergeben Sie Telefonnummern nach Möglichkeit in E.164-Form (+15551234567). Flowella normalisiert die üblichen Varianten serverseitig, aber E.164 ist am sichersten.

Kanäle

Viele Endpunkte akzeptieren ein whatsappChannelId. Wenn Ihre Organisation nur einen einzigen Kanal hat und Sie diesen weglassen, verwendet Flowella Ihren Standardkanal. Wenn Sie mehrere Kanäle haben, geben Sie die ID explizit an, um zu vermeiden, dass Sie von einem falschen Absender senden. Das vollständige URL-Muster und die Kanalumschaltung finden Sie unter Multi-Channel.

OpenAPI spec

Die maschinenlesbare Spezifikation finden Sie unter:

/api-reference/openapi.json

Geben Sie sie in Postman, Insomnia oder den Codegenerator Ihrer Wahl ein.

Bauen Sie eine Integration? Verbinden Sie diese Seite mit Webhooks, um auf Ereignisse zu reagieren, anstatt den Status abzufragen.

Erste Schritte

Änderungsprotokoll

Grundlagen

App nutzen

Einstellungen

Meta- und WhatsApp-Einrichtung

HubSpot-Integration

Flows und Kampagnen

Konto und Anmeldung

Sicherheit und Datenschutz

API-Referenz

Fehlerbehebung

Basis-URL

Authentifizierung

Einen Schlüssel erstellen

Überprüfen eines Schlüssels

Fehler

Ratenbegrenzung

Idempotenzschlüssel

Paginierung

Datum und Uhrzeit

Telefonnummern

Kanäle

OpenAPI spec

​Basis-URL

​Authentifizierung

​Einen Schlüssel erstellen

​Überprüfen eines Schlüssels

​Fehler

​Ratenbegrenzung

​Idempotenzschlüssel

​Paginierung

​Datum und Uhrzeit

​Telefonnummern

​Kanäle

​OpenAPI spec

Basis-URL

Authentifizierung

Einen Schlüssel erstellen

Überprüfen eines Schlüssels

Fehler

Ratenbegrenzung

Idempotenzschlüssel

Paginierung

Datum und Uhrzeit

Telefonnummern

Kanäle

OpenAPI spec