Einmal-Passcodes über WhatsApp mit der Flowella-API senden

Ihre App erstellt einen Einmal-Passcode, sendet ihn mit der Flowella-API an das WhatsApp des Kunden und prüft den Code, den der Kunde eingibt. Die Nachricht verwendet eine Authentifizierungsvorlage mit einer Code-kopieren-Schaltfläche. HubSpot ist optional: Ihre App kann das Ergebnis am Kontakt protokollieren.

Ein HubSpot-Workflow kann keine Passcodes senden. Die Flowella-Aktion Send WhatsApp Template kann einer OTP- oder Code-kopieren-Schaltfläche nicht für jeden Kontakt einen anderen Wert geben, und HubSpot sollte die Codes nicht speichern. Senden Sie Codes stattdessen mit der API aus Ihrer App.

Auf einen Blick

Punkt	Details
Trigger	Eine Anmeldung oder sensible Aktion in Ihrer App
Flowella	`POST /v1/templates/send` mit `buttonParameters` pro Empfänger
Vorlage	Eine Authentifizierungsvorlage mit einer Code-kopieren-Schaltfläche (Authentication)
HubSpot	Optional. Ihre App protokolliert das Ergebnis am Kontakt, niemals den Code
Zeitplan	Code wird sofort gesendet. Erlauben Sie ein erneutes Senden frühestens 15 Sekunden später

So funktioniert es

Das Diagramm zeigt einen Anmeldeversuch, von der Code-Anforderung bis zur Anmeldung oder Sperre.

Bevor Sie beginnen

Erstellen Sie einen API-Schlüssel. Siehe API-Schlüssel. Dieser Endpunkt akzeptiert nur API-Schlüssel, keine OAuth-Zugriffstoken.
Erfassen Sie die WhatsApp-Nummer jedes Kunden im internationalen Format, etwa +447700900123, sowie seine Zustimmung, Codes auf WhatsApp zu erhalten. Siehe die Opt-in-Hinweise von Meta.
Lesen Sie die API-Einführung zu Authentifizierung, Fehlern und Ratenlimits.

Die Vorlage erstellen

Erstellen Sie die Vorlage im WhatsApp Manager von Meta, mit der Kategorie Authentication und einer Code-kopieren-Schaltfläche. Nur Authentifizierungsvorlagen dürfen einen Einmal-Passcode enthalten, und sie benötigen eine Code-kopieren- oder One-Tap-Schaltfläche. Meta legt den Wortlaut fest: „<code> is your verification code.” Sie können einen Hinweis hinzufügen, den Code nicht weiterzugeben, sowie eine Ablaufzeile von 1 bis 90 Minuten. URLs, Medien und Emojis sind nicht erlaubt, und der Code darf bis zu 15 Zeichen lang sein. Sobald Meta die Vorlage genehmigt, erscheint sie in Flowella. Siehe die Richtlinien zur Vorlagenkategorisierung und Authentifizierungsvorlagen mit Code-kopieren-Schaltfläche von Meta. Wenn Sie Kunden auch über eine Sperre informieren, verwenden Sie eine separate Utility-Vorlage, etwa

Hi {{1}}, we have paused sign-in to your account after several incorrect codes. Try again in 30 minutes or contact our support team.

Ein Sicherheitshinweis zum Konto ohne Werbung passt zur Kategorie Utility.

Einen Code senden

Vorlage und Kanal finden

Rufen Sie GET /v1/templates?status=APPROVED auf. Notieren Sie die id und wabaId Ihrer Vorlage sowie die whatsappChannelId der Nummer, von der Sie senden. Wenn Sie mehrere Nummern haben, siehe Mehrere Kanäle.

Den Code in Ihrer App erstellen

Erzeugen Sie einen zufälligen Code mit bis zu 15 Zeichen. Speichern Sie einen Hash davon mit kurzer Ablaufzeit und markieren Sie ihn als einmalig verwendbar.

Die Anfrage senden

Setzen Sie den Code zweimal ein: einmal als Body-Parameter und einmal als Wert der Code-kopieren-Schaltfläche. Das Sendeformat von Meta behandelt die Code-kopieren-Schaltfläche als URL-Schaltfläche. Verwenden Sie daher subType url, mit index 0 für die erste Schaltfläche.

curl -X POST "https://api.flowella.io/v1/templates/send" \
  -H "Authorization: Bearer $FLOWELLA_API_KEY" \
  -H "Idempotency-Key: otp-7f3c2a91" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "1234567890123456",
    "templateWabaId": "102290129340398",
    "whatsappChannelId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "recipients": [
      {
        "phone": "+447700900123",
        "bodyParameters": ["482913"],
        "buttonParameters": [
          { "index": 0, "subType": "url", "text": "482913" }
        ]
      }
    ]
  }'

Eine 202-Antwort mit "status": "accepted" bedeutet, dass Flowella den Versand in die Warteschlange gestellt hat. Sie bestätigt nicht die Zustellung.

Den Code prüfen

Wenn der Kunde den Code eingibt, vergleichen Sie ihn mit dem gespeicherten Hash. Akzeptieren Sie ihn nur einmal und nur vor Ablauf.

Erneutes Senden und Sperre handhaben

Senden Sie für jeden Versuch einen neuen Code und machen Sie den alten ungültig. Warten Sie mindestens 15 Sekunden vor einem erneuten Senden: Flowella überspringt einen zweiten Versand derselben Vorlage an dieselbe Nummer innerhalb von 15 Sekunden. Begrenzen Sie die Versuche und sperren Sie die Anmeldung dann für einen festgelegten Zeitraum und bieten Sie Support an.

Das Ergebnis in HubSpot protokollieren (optional)

Lassen Sie Ihre App den HubSpot-Kontakt über die HubSpot-API aktualisieren, zum Beispiel Last WhatsApp verification (Datums- und Uhrzeitauswahl) und Last verification result (Dropdown-Auswahl: Passed, Failed, Locked). Ein HubSpot-Workflow kann dann eine Aufgabe erstellen, wenn das Ergebnis Locked ist. Speichern Sie niemals Codes in HubSpot.

Verwenden Sie für jeden Code einen neuen Idempotency-Key, etwa Ihre eigene Verifizierungs-ID. Eine Wiederholung mit demselben Schlüssel innerhalb von 7 Tagen gibt die ursprüngliche id zurück und sendet nichts.

Die Integration testen

Senden Sie einen Code an Ihre eigene WhatsApp-Nummer und prüfen Sie, ob die Code-kopieren-Schaltfläche ihn kopiert.
Geben Sie einen falschen Code ein, fordern Sie nach der Wartezeit ein erneutes Senden an und prüfen Sie, ob der alte Code nicht mehr funktioniert.
Beobachten Sie die Zustellung mit den Webhook-Ereignissen message.delivered und message.failed. Siehe Webhooks.

Fehlerbehebung

Symptom	Ursache	Lösung
Antwort `401`	Der Schlüssel fehlt oder ist ungültig, oder Sie haben ein OAuth-Zugriffstoken verwendet	Verwenden Sie einen gültigen API-Schlüssel. Siehe API-Schlüssel.
Antwort `429`	Sie haben das Ratenlimit überschritten	Warten Sie die im Header `Retry-After` angegebene Zeit und versuchen Sie es dann erneut.
Ein erneut gesendeter Code kommt nie an	Er wurde innerhalb von 15 Sekunden nach dem vorherigen Code gesendet, oder ein `Idempotency-Key` wurde wiederverwendet	Warten Sie 15 Sekunden und verwenden Sie einen neuen Schlüssel.
Bei einem Kunden kommt kein Code an	Die Nummer hat sich von Nachrichten Ihrer WhatsApp-Nummer abgemeldet	Der Kunde kann `START` senden, um sich wieder anzumelden. Siehe Opt-outs.
Der Versand schlägt bei langen Codes fehl	Der Code hat mehr als 15 Zeichen	Verwenden Sie einen kürzeren Code.

Verwandt

API-Einführung: Authentifizierung, Idempotenz, Fehler und Ratenlimits.
Vorlagenreferenz: Vorlagenkategorien und Schaltflächentypen.
Webhooks: Zustellereignisse von Flowella empfangen.

Erste Schritte

Grundlagen

App nutzen

Einstellungen

Meta- und WhatsApp-Einrichtung

HubSpot-Integration

Flows und Kampagnen

API-Referenz

Fehlerbehebung

Änderungsprotokoll

Einmal-Passcodes über WhatsApp mit der Flowella-API senden

Auf einen Blick

So funktioniert es

Bevor Sie beginnen

Die Vorlage erstellen

Einen Code senden

Die Integration testen

Fehlerbehebung

Verwandt

​Auf einen Blick

​So funktioniert es

​Bevor Sie beginnen

​Die Vorlage erstellen

​Einen Code senden

​Die Integration testen

​Fehlerbehebung

​Verwandt

Auf einen Blick

So funktioniert es

Bevor Sie beginnen

Die Vorlage erstellen

Einen Code senden

Die Integration testen

Fehlerbehebung

Verwandt