Verify von einem anderen Anbieter migrieren

Nutzen Sie diese Anleitung, um telefonische und E-Mail-Einmalpasswörter (OTP) von einem anderen Verifizierungsanbieter zu Bird Verify zu migrieren. Der Aufwand ist gering, weil die Oberfläche gering ist: Zwei Aufrufe ersetzen das Create-and-Check-Paar Ihres bisherigen Anbieters, und Bird verwaltet den Code, die Nachricht und den Zustellkanal dahinter.

Ein struktureller Unterschied bestimmt den Umfang der Arbeit. Bird hat kein anwendungsbezogenes Service-Objekt und keine Verification-ID, die Sie nachverfolgen müssten. Eine Verifizierung wird über den Empfänger identifiziert, beide Aufrufe verwenden daher denselben to, und der Zustand, den Ihre Integration vorhalten muss, schrumpft auf null.

Die Migrations-Checkliste:

Create- und Check-Aufrufe zuordnen
Kanäle, Länder und Absender festlegen
Verifizierungslebenszyklus portieren
Webhooks umstellen
Pro Code-Lebensdauer umschalten

Die Schritte 1 und 3 hängen davon ab, welchen Anbieter Sie verlassen. Ihr Anbieter-Leitfaden enthält die feldweise Zuordnung und die Status-Übersetzung.

1. Create- und Check-Aufrufe zuordnen

POST /v1/verify/verifications sendet einen Bestätigungscode. Die kleinste Anfrage besteht aus einem Empfänger:

Codebeispiel

curl -X POST https://us1.platform.bird.com/v1/verify/verifications \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": {"phone_number": "+15551234567"}}'

POST /v1/verify/verifications/check übermittelt die Eingabe des Nutzers, adressiert über denselben Empfänger plus den Code. Die vollständigen Payloads finden Sie unter Verifizierungen senden.

Vier Unterschiede, die Sie beim Portieren beachten müssen:

Der Empfänger ist der Schlüssel. Anbieter, die eine Verification-SID oder -ID zurückgeben, erwarten sie beim Check zurück. Bird gleicht stattdessen über das Adress-Set ab, und es muss exakt übereinstimmen: Eine Verifizierung, die mit E-Mail und Telefonnummer erstellt wurde, wird nicht gefunden, wenn nur eine davon angegeben wird. Die Spalte, die bisher die Verification-ID des Anbieters enthält, kann entfallen.
Ein falscher Code liefert 200 zurück. Die Antwort enthält success: false, einen reason mit dem Wert incorrect_code, expired oder attempts_exhausted sowie attempts_remaining. Reservieren Sie Ihren Fehlerpfad für fehlgeschlagene Anfragen. Sobald eine Verifizierung einen Endzustand erreicht hat, liefern weitere Checks 404 statt success: false.
Bird erzeugt den Code und gibt ihn nie zurück. Es gibt keinen Custom-Code-Parameter. Eine Anbieter-Integration, die einen eigenen Bestätigungscode übergeben oder den Code ausgelesen hat, um ihn selbst zu versenden, hat hier keine Entsprechung.
Beide Endpunkte akzeptieren Idempotency-Key. Ein Replay nach einem Timeout gibt die ursprüngliche Antwort zurück, ohne einen weiteren Code zu senden oder einen Versuch zu verbrauchen.

Per-Request-Optionen sind bewusst wenige: options.code_length und options.channels, womit Sie die Kanäle für eine einzelne Anfrage umsortieren oder einschränken. Alles andere ist Workspace-Konfiguration und kein Feld im Send-Aufruf.

2. Kanäle, Länder und Absender festlegen

Bird liefert Codes per E-Mail, SMS, WhatsApp und Telegram. Für einen Telefonempfänger versuchen die meisten Länder zuerst WhatsApp mit SMS als Fallback, und die Zustellung rückt zum nächsten Kanal im Plan vor, wenn ein Versand fehlschlägt. Legen Sie die Reihenfolge fest oder deaktivieren Sie einen Kanal pro Land auf der Seite Countries; deaktivieren Sie dort auch die Länder, die Sie nicht bedienen, denn ein ungenutztes Ziel ist kein Reichweitengewinn, sondern Angriffsfläche für SMS-Pumping.

Zwei Lücken sollten Sie vor einem festen Termin mit Ihrem aktuellen Ablauf abgleichen:

Es gibt keinen Sprachanruf-Kanal und keine stille Netzwerk-Authentifizierung. Ein Ablauf, der für Nutzer, die SMS nicht empfangen können, auf einen Telefonanruf zurückfällt, braucht hier eine andere Lösung.
Wählen Sie den Absender vor der Umstellung. E-Mail, SMS und WhatsApp verwenden standardmäßig Bird Verify und können stattdessen Authifly nutzen. Sie können auch Ihre verifizierte E-Mail-Domain, eine vorhandene SMS-Absenderkennung oder eine verbundene WhatsApp-Nummer mit einem genehmigten Authentifizierungstemplate verwenden. Telegram nutzt einen eigenen verifizierten Benachrichtigungsaccount. Wenn Sie einen SMS-Absender beibehalten möchten, den Ihre Nutzer bereits kennen, prüfen Sie, ob er in jedem Zielland unterstützt und registriert ist. Absender und Branding beschreibt die Optionen und das Fallback-Verhalten.

Wenn Sie Ihre eigene WhatsApp-Nummer verwenden, wählen Sie in Ihrer Verify-Konfiguration ein vorhandenes genehmigtes Authentifizierungstemplate aus. Bird steuert den E-Mail- und SMS-Nachrichtentext. Sie können weder eine Template-ID noch einen individuellen Nachrichtentext in einer einzelnen Verifizierungsanfrage übergeben.

3. Verifizierungslebenszyklus portieren

Eine Verifizierung ist pending, bis sie sich auflöst: verified, wenn ein korrekter Code rechtzeitig eintrifft, failed mit Grund attempts_exhausted oder undeliverable, oder expired mit Grund ttl_elapsed. Bilden Sie die Endstatus Ihres Anbieters auf diese drei ab und behandeln Sie reason als offenes Enum.

Die Zeitvorgaben, die Ihre UI prägen, sind Workspace-Einstellungen auf der Seite Configure: wie lange ein Code gültig bleibt, wie viele Check-Versuche ein Nutzer hat und wie lange die Resend-Abklingzeit läuft. Stellen Sie sie so ein, dass sie dem entsprechen, was Ihre Nutzer heute erleben, statt Ihre UI-Texte umzuschreiben. Die Codelänge ist der einzige Wert, den Sie auch pro Anfrage setzen können. Die Standardwerte und Bereiche finden Sie unter Verifizierungseinstellungen.

Zwei Verhaltensweisen ersetzen in der Regel Code, den Sie bereits haben:

Erneutes Senden ist ein weiterer Create-Aufruf. Rufen Sie Create mit demselben Empfänger auf: Innerhalb der Abklingzeit gibt er die laufende Verifizierung zurück, ohne zu senden, und danach wird ein neuer Code verschickt. Jeder für eine laufende Verifizierung gesendete Code bleibt gültig, bis die Verifizierung aufgelöst wird. Ein Nutzer, der den ersten Code eingibt, nachdem der zweite angekommen ist, wird dafür nicht bestraft.
"I didn't get a code" hat einen eigenen Endpunkt. POST /v1/verify/verifications/next-channel rückt zum nächsten Kanal im Plan vor und sendet dort sofort, wobei die Resend-Abklingzeit ignoriert, aber Ablaufzeit, Versuchsbudget und Verifizierung beibehalten werden. Verknüpfen Sie ihn mit dem Button, statt Resends auf einem Kanal zu wiederholen, der nicht ankommt.

Über Ihren Einstellungen liegen Plattform-Leitplanken, die Sie nicht konfigurieren: ein stündliches Sendelimit pro Adresse und ein Check-Limit pro Empfänger, die beide mit einem 429 und einem Retry-After beantwortet werden. Wenn Ihr bisheriger Anbieter es erlaubt hat, Rate-Limits pro Endpunkt zu erhöhen, und Sie das getan haben, prüfen Sie Ihren Spitzenwert vor der Umstellung gegen die Werte in Missbrauchsschutz.

4. Webhooks umstellen

Verify sendet Events auf zwei Achsen. Session-Events, verify.verification.created, verify.verification.verified und verify.verification.failed, folgen der Verifizierung selbst. Attempt-Events, verify.attempt.sent, verify.attempt.delivered und verify.attempt.undelivered, folgen jedem einzelnen Bestätigungscode-Versand, sodass ein erneuter Versand oder ein Kanal-Failover dem gleichen Session weitere Attempts hinzufügt. Abonnieren Sie einen Endpunkt für die gewünschten Typen mit POST /v1/webhooks; die Payloads finden Sie unter Verify-Events.

Abonnieren Sie die Session-Events, die Ihre Integration benötigt. verify.verification.failed deckt die Zustellsackgasse ab: Es wird mit reason: "undeliverable" ausgelöst, wenn der Plan erschöpft ist und die aufgezeichneten Fehler darauf hinweisen, dass kein Bestätigungscode gesendet wurde, und last_attempt_reason benennt den Fehler auf dem letzten versuchten Kanal. Eine Verifizierung, die abläuft oder ihre Prüfversuche aufbraucht, löst kein Session-Event aus – entnehmen Sie diese beiden Ergebnisse stattdessen der Check-Antwort.

Diese Events dienen Analysen, Alerting und Support-Tooling. Ihre Authentifizierungsentscheidung kommt vom Check-Aufruf, der synchron antwortet, und ein Login-Flow sollte niemals auf einen Webhook warten, um einen Benutzer einzulassen. Die Zustellung erfolgt at-least-once und ungeordnet, signiert gemäß Standard Webhooks. Deduplizieren Sie anhand des webhook-id-Headers genauso wie bei jedem anderen Bird-Event.

5. Schrittweise umstellen, jeweils eine Code-Lebensdauer

Verify hat keine simulierten Empfänger: Was sich zu testen lohnt, ist der ankommende Code. Führen Sie die Integration daher vor dem Produktiveinsatz gegen eine Telefonnummer und ein Postfach aus, die Sie kontrollieren, auf jedem aktivierten Kanal.

Die Umstellung selbst hat eine Regel, die leicht übersehen wird. Ein vom alten Anbieter ausgestellter Code kann nicht von Bird geprüft werden und umgekehrt. Wechseln Sie daher beim Create-Aufruf, und leiten Sie für die Dauer einer Code-Lebensdauer jeden Check an den Anbieter weiter, der die jeweilige Verifizierung ausgestellt hat. In der Praxis:

Halten Sie fest, welcher Anbieter jede laufende Verifizierung erstellt hat.
Senden Sie einen Anteil neuer Verifizierungen über Bird und prüfen Sie diese gegen Bird.
Prüfen Sie ältere Verifizierungen weiterhin gegen den alten Anbieter, bis die letzte abläuft – das dauert ein Code-Gültigkeitsfenster plus einen Puffer.
Erhöhen Sie den Anteil von Bird, sobald die Konversionsraten der ersten Kohorte stimmen, und stellen Sie dann den alten Pfad ein.

Beobachten Sie die Konversion, nicht nur die Zustellung. Die Seite Verifications und die Verify-Metriken zeigen Sendungen, Zustellungen und wie viele Verifizierungen verified erreicht haben – das ist die Zahl, die Ihnen verrät, ob eine Kanalreihenfolge oder eine neue Absenderidentität Sie Registrierungen kostet.

Migration von einem bestimmten Anbieter

Twilio Verify: Services werden zu Workspace-Einstellungen, VerificationCheck wird zu einem empfängerbasierten Check, Kanal- und Statusübersetzung
Prelude: eine nahezu identische Create-und-Check-Struktur, wobei Routing-Signale und stille Verifizierung die Teile sind, die sich nicht portieren lassen

Nächste Schritte

Verifizierungen senden: der vollständige Request- und Response-Vertrag, Status und Limits
Länderkonfiguration: Kanalreihenfolge und Verfügbarkeit pro Land
Absender und Branding: wie jede Nachricht aussieht und der gebrandete E-Mail-Absender
Verify-Events: Session- und Attempt-Event-Payloads

Verwandte Ressourcen