> ## Documentation Index
> Fetch the complete documentation index at: https://knowledge.flowella.io/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp-Vorlagen und Flows aus Customer.io senden

> Freigegebene WhatsApp-Vorlagen und Flows mit der Flowella API aus Customer.io-Kampagnen senden und eingehende Nachrichten optional an Customer.io senden.

Flowella verbindet sich über die Webhook-Aktionen von Customer.io und die Flowella REST API mit Customer.io. Eine Customer.io-Kampagne ruft Flowella auf, um jeder Person, die diesen Schritt erreicht, eine freigegebene WhatsApp-Vorlage zu senden, auch Vorlagen mit einer WhatsApp-Flow-Schaltfläche. Wenn Sie WhatsApp-Antworten auch in Customer.io haben möchten, kann Flowella jede eingehende Nachricht an eine per Webhook ausgelöste Automatisierung in Customer.io senden, die Sie selbst steuern.

> [!NOTE]
>
> In Customer.io müssen Sie keine App installieren. Sie bauen beide Richtungen mit Standardaktionen von Customer.io und entscheiden so genau, welche Anfragen laufen und welche Attribute sich ändern.

## So funktioniert die Integration

| Richtung | Was läuft | Was sich ändert |
| - | - | - |
| Customer.io zu Flowella | Eine Aktion **Send and receive data** (Webhook) in Ihrer Kampagne ruft `POST /v1/templates/send` für die Person in der Kampagne auf. | Flowella stellt eine WhatsApp-Vorlagennachricht in die Warteschlange. In Customer.io wird nichts geschrieben. |
| Flowella zu Customer.io (optional) | Ein ausgehender Flowella-Webhook sendet Ereignisse `message.received` an eine per Webhook ausgelöste Automatisierung in Customer.io. | Nur die Personenattribute, die Sie in Ihrer eigenen Aktion **Create or Update Person** zuordnen. |

Flowella ruft nie die Customer.io API auf. In der optionalen eingehenden Richtung sendet Flowella Ereignisse nur an die Webhook-URL, die Sie angeben, und Ihre Automatisierung entscheidet, was damit geschieht.

```mermaid theme={null}
flowchart LR
    A["Customer.io: Person erreicht die Webhook-Aktion"] --> B["Flowella: POST /v1/templates/send"]
    B --> C["Meta: WhatsApp-Nachricht zugestellt"]
    C --> D["Kontakt antwortet auf WhatsApp"]
    D --> E["Flowella: Webhook message.received"]
    E --> F["Customer.io: per Webhook ausgelöste Automatisierung"]
    F --> G["Customer.io: Create or Update Person"]
```

## Bevor Sie beginnen

* Eine Flowella-Organisation mit einer verbundenen WhatsApp-Nummer. Siehe [Einrichtungsreihenfolge](https://knowledge.flowella.io/de/whatsapp/accounts/setup-sequence.md).
* Eine freigegebene WhatsApp-Vorlage in Flowella. Siehe [Vorlagen](https://knowledge.flowella.io/de/app/templates.md).
* Die Rolle **Owner** oder **Admin** in Flowella, um einen API-Schlüssel und für die eingehende Synchronisierung einen Webhook zu erstellen. Siehe [Team und Rollen](https://knowledge.flowella.io/de/settings/team.md).
* Ein Customer.io-Workspace, in dem Sie Kampagnen oder Automatisierungen mit Webhook-Aktionen erstellen können.
* Die WhatsApp-Nummer jeder Person im internationalen Format in ihrem Customer.io-Profil, etwa `+447700900123`. Siehe [Telefonnummernformat](https://knowledge.flowella.io/de/hubspot/phone-number-format.md).
* Die Zustimmung jeder Person, WhatsApp-Nachrichten von Ihnen zu erhalten. Meta verlangt ein Opt-in, bevor Sie jemandem schreiben. Siehe Metas [Hinweise zum Opt-in](https://developers.facebook.com/documentation/business-messaging/whatsapp/getting-opt-in).

## Eine WhatsApp-Vorlage aus Customer.io senden

**1. Einen Flowella-API-Schlüssel erstellen**

Gehen Sie in Flowella zu **Settings**, dann **API keys**, und erstellen Sie einen Live-Schlüssel mit einem Namen wie `Customer.io production`. Kopieren Sie ihn sofort: Flowella zeigt ihn nur einmal an. Siehe [API-Schlüssel](https://knowledge.flowella.io/de/settings/api-keys.md).

**2. Vorlagen- und Kanal-IDs ermitteln**

Rufen Sie mit Ihrem Schlüssel `GET /v1/templates?status=APPROVED` auf. Notieren Sie die `id` und `wabaId` der Vorlage und die `whatsappChannelId` der Nummer, von der Sie senden möchten. Siehe [Mehrere Kanäle](https://knowledge.flowella.io/de/essentials/multi-channel.md), wenn Sie mehrere Nummern haben.

```bash theme={null}
curl "https://api.flowella.io/v1/templates?status=APPROVED" \
  -H "Authorization: Bearer $FLOWELLA_API_KEY"
```

**3. Ihrer Kampagne eine Webhook-Aktion hinzufügen**

Fügen Sie im Workflow Ihrer Customer.io-Kampagne an der Stelle, an der die WhatsApp-Nachricht hinausgehen soll, eine Aktion **Send and receive data** hinzu. Siehe die Anleitung von Customer.io zu [Webhook-Aktionen](https://docs.customer.io/webhooks-action).

**4. Die Anfrage festlegen**

Setzen Sie die Methode auf `POST` und die URL auf `https://api.flowella.io/v1/templates/send`. Fügen Sie diese Header hinzu:

| Header | Wert |
| - | - |
| `Authorization` | `Bearer ` gefolgt von Ihrem Flowella-API-Schlüssel |
| `Content-Type` | `application/json` |

**5. Den Anfrage-Body schreiben**

Fügen Sie diesen Body ein und ersetzen Sie die IDs durch Ihre eigenen. Ändern Sie `customer.phone` in das Attribut, das die WhatsApp-Nummer der Person enthält.

```json theme={null}
{
  "templateId": "1234567890123456",
  "templateWabaId": "102290129340398",
  "whatsappChannelId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
  "recipients": [
    {
      "phone": "{{customer.phone}}",
      "bodyParameters": ["{{customer.first_name}}"]
    }
  ]
}
```

`bodyParameters` füllt die Textvariablen der Vorlage der Reihe nach: Der erste Wert kommt in `{{1}}`, der zweite in `{{2}}` und so weiter. Lassen Sie die Liste leer, `[]`, wenn die Vorlage keine Textvariablen hat.

**6. Die Aktion testen**

Wählen Sie eine Testperson mit Ihrer eigenen WhatsApp-Nummer und wählen Sie in Customer.io **Test response**. Fügen Sie einen Header `Idempotency-Key` mit einem Wert hinzu, den Sie noch nicht verwendet haben, etwa `test-2026-11-11-01`, und ändern Sie ihn bei jedem Test. Siehe [Wiederholte Sendungen und Idempotenz](#repeat-sends-and-idempotency).

Eine Antwort `202` mit `"status": "accepted"` bedeutet, dass Flowella den Versand in die Warteschlange gestellt hat. Sie bestätigt keine Zustellung: Prüfen Sie das Ergebnis auf dem Tab **Statistics** der Vorlage in Flowella.

**7. Den Test-Header entfernen und die Kampagne starten**

Löschen Sie den Header `Idempotency-Key`, den Sie zum Testen verwendet haben, oder ersetzen Sie ihn durch einen Wert, der für jede Person anders ist. Starten Sie dann die Kampagne.

### Vorlagenoptionen pro Person

Der Anfrage-Body akzeptiert für jeden Empfänger diese Felder. Die [API-Einführung](https://knowledge.flowella.io/de/api-reference/introduction.md) und das [OpenAPI-Dokument](https://api.flowella.io/v1/openapi.json) beschreiben die vollständige Anfrage.

| Feld | Verwendung |
| - | - |
| `phone` | Die WhatsApp-Nummer der Person. Pflichtfeld. |
| `bodyParameters` | Werte für die Textvariablen, der Reihe nach. Bis zu 20. |
| `buttonParameters` | Werte für Variablen in URL-Schaltflächen (`subType` `url`), Flow-Schaltflächen (`subType` `flow`) oder Schaltflächen zum Kopieren eines Codes (`subType` `copy_code`). |

Für eine Vorlage mit einem Bild-, Video- oder Dokument-Header können Sie auf oberster Ebene des Bodys in `headerMedia.url` einen öffentlichen Dateilink angeben.

### Wiederholte Sendungen und Idempotenz

`POST /v1/templates/send` schützt Sie davor, dieselbe Nachricht zweimal zu senden. Das ist wichtig, weil Customer.io eine Webhook-Aktion wiederholt, wenn es keine Antwort `2xx` erhält:

* Ohne Header `Idempotency-Key` verwendet Flowella einen Hash des Anfrage-Bodys als Schlüssel. Ein byte-identischer Body innerhalb von 7 Tagen gibt die ursprüngliche `id` zurück und sendet nichts. Da der Body jeder Person ihre eigene Nummer enthält, sendet eine normale Kampagne an alle genau einmal.
* Mit einem Header `Idempotency-Key` gibt jede Anfrage mit demselben Schlüssel innerhalb von 7 Tagen die ursprüngliche `id` zurück und sendet nichts, auch wenn sich der Body geändert hat.
* Unabhängig davon überspringt Flowella einen zweiten Versand derselben Vorlage an dieselbe Nummer innerhalb von 15 Sekunden.

> [!WARNING]
>
> Lassen Sie nie einen festen Wert für `Idempotency-Key` in einer aktiven Kampagnenaktion. Nur die erste Person erhält die Nachricht: Jede spätere Anfrage verwendet den Schlüssel erneut, sodass Flowella die erste `id` zurückgibt und nichts sendet. Entfernen Sie den Header, bevor Sie die Kampagne starten, oder bilden Sie einen Wert, der für jede Person anders ist, etwa einen Kampagnennamen gefolgt von `{{customer.id}}`.

Dieselben Regeln erklären die meisten fehlgeschlagenen Tests. Wenn Sie dieselbe Vorlage erneut an dieselbe Testperson senden, entsteht derselbe Body. Flowella sendet dann nichts, es sei denn, Sie ändern den Wert von `Idempotency-Key` jedes Mal.

### An ein großes Segment senden

Jede Anfrage von Customer.io stellt einen Versand in die Warteschlange. Flowella stellt ihn im Hintergrund zu und wiederholt ihn bei vorübergehenden WhatsApp-Fehlern. Für große Kampagnen gelten zwei Limits:

* **Metas Messaging-Limit.** Meta begrenzt, wie viele Personen Sie innerhalb von gleitenden 24 Stunden außerhalb des 24-Stunden-Fensters anschreiben können. Siehe [Messaging-Limits](https://knowledge.flowella.io/de/whatsapp/limits/messaging-limits.md).
* **Das Ratenlimit Ihres API-Schlüssels.** Anfragen über dem Limit geben `429` mit einem Header `Retry-After` zurück. Siehe [Ratenlimits](https://knowledge.flowella.io/de/api-reference/introduction.md#rate-limits).

Verteilen Sie große Sendungen mit den Versandsteuerungen von Customer.io und verfolgen Sie den Fortschritt auf dem Tab **Statistics** der Vorlage. Flowella überspringt alle, die sich für die sendende Nummer abgemeldet haben. Siehe [Opt-outs](https://knowledge.flowella.io/de/app/opt-outs.md).

## Eingehende WhatsApp-Nachrichten an Customer.io (optional)

Dieser Teil sendet jede WhatsApp-Nachricht, die ein Kontakt Ihnen schickt, an Customer.io, damit Sie die Person aktualisieren oder daraus weitere Kampagnen starten können.

**1. Eine per Webhook ausgelöste Automatisierung in Customer.io erstellen**

Erstellen Sie eine per Webhook ausgelöste Kampagne oder Automatisierung und kopieren Sie die Webhook-URL, die Customer.io erzeugt. Siehe die Anleitung von Customer.io zu [Webhook-Kampagnen](https://docs.customer.io/journeys/webhook-triggered-campaigns/).

**2. Einen ausgehenden Webhook in Flowella hinzufügen**

Gehen Sie in Flowella zu **Settings**, dann **Webhooks**, und wählen Sie **Add webhook**. Fügen Sie die Customer.io-URL in **Endpoint URL** ein, geben Sie ein Signatur-Secret ein und aktivieren Sie unter **Events** nur `message.received`. Siehe [Webhooks](https://knowledge.flowella.io/de/settings/webhooks.md).

**3. Beispieldaten senden**

Senden Sie sich selbst eine WhatsApp-Vorlage aus Flowella und antworten Sie darauf, damit Customer.io ein echtes Ereignis `message.received` erhält, aus dem Sie den Workflow aufbauen. Jedes Ereignis sieht so aus:

```json theme={null}
{
  "id": "evt_3f2b8c1d9a7e4f60b5c2d8e1a4f7b9c3",
  "type": "message.received",
  "created_at": "2026-10-21T09:30:00.000Z",
  "payload_version": "1",
  "data": {
    "messageId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "conversationId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "contactId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "direction": "INBOUND",
    "type": "TEXT",
    "metaMessageId": "wamid.HBgLMTU1NTEyMzQ1NjcVAgASGBQzQUY"
  }
}
```

**Send test event** in Flowella sendet ein Ereignis `webhook.test`, das keinen Kontakt hat. Filtern Sie es daher im nächsten Schritt heraus.

**4. Nur echte eingehende Nachrichten behalten**

Fügen Sie einen **True/False Branch** hinzu, der nur fortfährt, wenn `type` des Auslösers `message.received` ist.

**5. Den Kontakt in Flowella nachschlagen**

Das Ereignis enthält IDs, nicht die Telefonnummer. Fügen Sie eine Aktion **Send and receive data** mit der Methode `GET`, der URL `https://api.flowella.io/v1/contacts/{{trigger.data.contactId}}` und demselben Header `Authorization` wie zuvor hinzu. Die Antwort enthält `id`, `phone`, `waId`, `name`, `email`, `externalId`, `isOptedOut`, `createdAt` und `updatedAt` des Kontakts.

Um die Nachricht selbst zu speichern, fügen Sie eine weitere Anfrage an `GET /v1/messages/{{trigger.data.messageId}}` hinzu. Ihr Feld `body` enthält den Nachrichtentext und kann leer sein.

**6. Die Person aktualisieren**

Fügen Sie eine Aktion **Create or Update Person** hinzu. Wählen Sie die Kennung, die Ihr Workspace für Personen verwendet, und setzen Sie nur die Attribute, die Sie benötigen, etwa den Zeitpunkt der letzten WhatsApp-Antwort. Siehe die Anleitung von Customer.io zu [Create or update person](https://docs.customer.io/journeys/create-update-person/).

> [!WARNING]
>
> In einer per Webhook ausgelösten Automatisierung erstellt **Create or Update Person** eine neue Person, wenn niemand zur Kennung passt. Damit keine unerwünschten Personen entstehen, fügen Sie eine Aktionsbedingung hinzu, sodass der Schritt nur läuft, wenn die Kennung einen Wert hat, und testen Sie mit einer Nummer, die nicht in Ihrem Workspace ist.

### Sicherheit des eingehenden Webhooks

Flowella signiert jede Anfrage mit dem Header `X-Flowella-Signature`. Eine per Webhook ausgelöste Automatisierung in Customer.io kann diese Signatur nicht prüfen. Daher kann jeder, der die Customer.io-Webhook-URL kennt, Daten daran senden. Halten Sie die URL geheim und verwenden Sie die eingehende Synchronisierung nicht, um Einwilligungs- oder Abrechnungsattribute zu ändern. Siehe [Signaturen prüfen](https://knowledge.flowella.io/de/api-reference/webhooks.md#verify-signatures), wenn Sie Ereignisse zuerst über Ihren eigenen Endpunkt leiten.

### Opt-outs

Wenn ein Kontakt `STOP` oder ein anderes Opt-out-Schlüsselwort sendet, erfasst Flowella das Opt-out für diese WhatsApp-Nummer und blockiert jeden späteren Versand von dieser Nummer an ihn, auch Sendungen aus Customer.io. Siehe [Opt-outs](https://knowledge.flowella.io/de/app/opt-outs.md).

Um Opt-outs nach Customer.io zu übertragen, verlassen Sie sich nicht auf das Ereignis `optout.created`: Es wird derzeit beim ersten Opt-out eines Kontakts für eine Nummer nicht ausgelöst. Listen Sie Opt-outs stattdessen mit `GET /v1/opt-outs` auf. Der Endpunkt akzeptiert die Filter `createdAfter` und `phone`.

## Fehlerbehebung

| Symptom | Ursache | Lösung |
| - | - | - |
| `401` mit `Invalid or expired API key` | Der Schlüssel wurde widerrufen oder ersetzt, oder er wurde falsch eingefügt. | Erstellen Sie einen neuen Schlüssel und aktualisieren Sie den Header `Authorization`. Siehe [API-Schlüssel](https://knowledge.flowella.io/de/settings/api-keys.md). |
| **Could not load API keys** in Flowella | Nur Owner und Admins können API-Schlüssel verwalten. | Bitten Sie einen Owner oder Admin, den Schlüssel zu erstellen. |
| `401` mit `Missing bearer token` | Die Anfrage ging an `https://app.flowella.io/api/v1`, das weiterleitet, und der Header ging verloren. | Verwenden Sie `https://api.flowella.io/v1`. |
| Ein Test gibt `202` zurück, aber nichts kommt an | Der Body oder `Idempotency-Key` entsprach einem früheren Versand innerhalb von 7 Tagen, oder dieselbe Vorlage ging innerhalb von 15 Sekunden an dieselbe Nummer. | Verwenden Sie für jeden Test einen neuen Wert für `Idempotency-Key`. |
| Nur die erste Person einer Kampagne hat die Nachricht erhalten | In der Aktion blieb ein fester Wert für `Idempotency-Key` stehen. | Entfernen Sie den Header oder machen Sie seinen Wert für jede Person eindeutig. |
| Der Versand zeigt auf dem Tab **Statistics** einen Fehler | Meta konnte die Nachricht nicht zustellen, zum Beispiel weil die Nummer nicht bei WhatsApp ist. | Lesen Sie den Grund in der Spalte **Details**. Siehe [Meta-Fehlercodes](https://knowledge.flowella.io/de/whatsapp/errors/error-codes.md). |
| **Invalid phone number.** auf dem Tab **Statistics** | Das Telefonattribut ist leer oder nicht im internationalen Format. | Speichern Sie Nummern mit Ländervorwahl, etwa `+447700900123`. |
| Customer.io erhält keine eingehenden Ereignisse | Der Flowella-Webhook ist inaktiv oder `message.received` ist nicht aktiviert. | Prüfen Sie das **Delivery log** des Webhooks in Flowella. Siehe [Webhooks](https://knowledge.flowella.io/de/settings/webhooks.md#delivery-log). |

## Verwandt

> [card] [API-Einführung](https://knowledge.flowella.io/de/api-reference/introduction.md)
>
> Authentifizierung, Idempotenz, Ratenlimits und Fehler.

> [card] [Webhooks-Referenz](https://knowledge.flowella.io/de/api-reference/webhooks.md)
>
> Ereignistypen, Anfrage-Bodys und Signaturen.

> [card] [Vorlagenvariablen](https://knowledge.flowella.io/de/app/template-variables.md)
>
> Variablen, Beispiele und Fallback-Werte.

> [card] [Massenversand](https://knowledge.flowella.io/de/app/bulk-send.md)
>
> Eine Vorlage stattdessen aus der Flowella-App an eine Liste senden.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.