Sign inGet Started

Migracja Verify z Prelude

Ta strona mapuje API weryfikacji Prelude v2 na Bird Verify. Postępuj zgodnie z głównym przewodnikiem migracji po kolei i użyj tych mapowań w krokach 1 i 3.
Struktury są zbliżone. POST https://api.prelude.dev/v2/verification i POST /v2/verification/check w Prelude to uwierzytelniana tokenem para create-and-check identyfikowana po odbiorcy, a nie po ID weryfikacji, i tak samo działają POST /v1/verify/verifications oraz POST /v1/verify/verifications/check. Ponowne wywołanie create dla aktywnego odbiorcy powtarza próbę zamiast rozpoczynać nową weryfikację na obu platformach. To, czego nie da się przenieść, to warstwa ryzyka: sygnały Prelude, werdykty routingu i cicha weryfikacja nie mają odpowiednika w Bird Verify API.

Przekaż to swojemu agentowi

Wklej to do Claude Code, Cursor lub Codex. Agent przechodzi tę stronę na tle Twojego repozytorium, korzystając z dowolnej powierzchni Bird, którą już ma: serwera MCP, jeśli jest podłączony, lub CLI, jeśli jest zainstalowany i zalogowany.
Przykład kodu
I am moving a phone verification integration from Prelude to Bird Verify. Route through it with me.
1. Check what you already have before setting anything up. If Bird's MCP server is connected, use its tools. If the Bird CLI is installed and signed in, use that. Either one is enough, and every step below is an action you take with whichever you have. Only if neither is present, follow https://bird.com/docs/ai/set-up-your-agent.md to set one up and sign me in. Every Bird docs page serves Markdown at its own URL with `.md` appended, so fetch that rather than the HTML.
2. Read https://bird.com/docs/guides/verify/migrate/prelude.md for the create, check and status mapping, and https://bird.com/docs/guides/verify/migrate.md for the order the steps go in.
3. Find and list my Prelude usage in this repository before you change anything: the /v2/verification and /v2/verification/check call sites, anywhere I read signals or a routing verdict, and anywhere I use dispatch_id for retry safety.
4. Tell me early which of these I depend on. Bird Verify has no voice channel and no silent or network-based authentication. It generates the code itself and never returns it, so I cannot supply my own. It accepts `options.language` but no per-request template or message body. Bird can use an existing SMS Sender ID or a connected WhatsApp number with an approved authentication template, configured per channel or country rather than per request; tell me whether my current sender can be kept. Prelude's risk layer does not port either: its signals, its routing verdicts and its silent verification have no counterpart in Bird Verify, so tell me every decision my code makes on those.
5. Configure my channels and destinations following https://bird.com/docs/guides/verify/countries.md and https://bird.com/docs/guides/verify/senders.md. While you are there, disable every country I do not actually verify into. An enabled destination I never send to is not reach, it is exposure to SMS pumping, so ask me which countries I serve rather than leaving the defaults.
6. Port the create and check calls using the mapping tables on the provider page, and move my status handling to Bird's events: https://bird.com/docs/guides/verify/sending-verifications.md and https://bird.com/docs/guides/verify/events.md.
7. Cut over at the create call, not all at once, because a code issued by Prelude cannot be checked by Bird and a code issued by Bird cannot be checked by Prelude. From the moment I say go, send every NEW verification to Bird, and keep routing each check to whichever provider issued that verification. Keep both paths live for one full code lifetime plus margin, then retire the old one. Tell me how you will decide which provider issued a given verification before you write any of it.
8. Test before any real traffic. Bird Verify has no simulated recipients, so do not look for a sandbox: the thing worth testing is the code arriving. Run the integration against a phone number and a mailbox I control, on each channel I enabled, and show me what arrived on each one.
9. Stop and ask me wherever a step needs a decision. Do not start routing new verifications to Bird until I have seen those test results and replied with the words cut over to Bird. Retiring the Prelude path is a separate step: ask me again and wait for me to reply with the words retire the Prelude path, and do not retire it while any code it issued could still be checked. A reply that agrees without naming what it is authorising is not authorisation. Finish by telling me what is left that only a person can do.

Zmapuj wywołanie create

Co robiPreludeBird
Odbiorcatarget.type + target.valueto.phone_number lub to.email
Długość koduoptions.code_sizeoptions.code_length
Preferencja kanałuoptions.preferred_channel, options.channelsoptions.channels, w przeciwnym razie skonfigurowana kolejność danego kraju
Korelacjametadata.correlation_idmetadata
Callbacki dostarczeniaoptions.callback_urlwebhook obszaru roboczego subskrybujący wybrane typy zdarzeń verify
Własny kod weryfikacyjnyoptions.custom_codebrak odpowiednika
Lokalizacjaoptions.localeoptions.language
Tożsamość nadawcyoptions.sender_idwybierz nadawcę zarządzanego przez Bird lub należącego do obszaru roboczego według kanału lub kraju, nie według żądania
Szablon wiadomościoptions.template_id, options.variablesbrak odpowiednika per żądanie; wybierz zatwierdzony szablon uwierzytelniania WhatsApp w konfiguracji Verify
Autouzupełnianie na Androidzieoptions.app_realmbrak odpowiednika
Sygnały ryzykasignals (IP, urządzenie, fingerprint)nieobsługiwane
Bezpieczne ponowieniabrak klucza idempotentności ani nagłówka w referencji create i checknagłówek Idempotency-Key
Korelacja sygnałówdispatch_id, "the identifier of the dispatch that came from the front-end SDK"brak odpowiednika: Bird nie przyjmuje sygnałów
Kontrola fallbackuoptions.max_auto_fallbacks, options.force_challengeplan kanałów danego kraju
dispatch_id nie jest mechanizmem ponawiania i nie należy obok Idempotency-Key. Własna referencja Prelude definiuje go jako "the identifier of the dispatch that came from the front-end SDK": ich Signals SDK zwraca go z dispatchSignals(), a Ty przekazujesz go w wywołaniu create, żeby ich warstwa antyfraudowa mogła powiązać sygnały przeglądarki z tą weryfikacją. Referencje create i check dokumentują pełny zestaw żądań bez klucza idempotentności i bez własnego nagłówka, więc ponowione create nie jest dla Ciebie bezpieczne. W Bird robi to nagłówek Idempotency-Key.
Zestawy kanałów pokrywają się tylko częściowo. Bird dostarcza przez e-mail, SMS, WhatsApp i Telegram; kanały Prelude RCS, Viber, Zalo, voice i silent nie mają odpowiednika w Bird. Numer, do którego Prelude docierał przez Viber lub Zalo, tutaj przechodzi na SMS, co jest kwestią współczynnika dostarczalności wartą zmierzenia w pilocie, a nie odkrywania przy pełnym wolumenie.

Zmapuj wywołanie check

Oba endpointy check przyjmują odbiorcę i kod bez ID weryfikacji, więc to wywołanie przenosi się niemal bez zmian. Różnią się odpowiedzi:
Prelude statusBird
successsuccess: true
failuresuccess: false, reason: incorrect_code
expired_or_not_foundsuccess: false, reason: expired lub 404
(brak bezpośredniej wartości)success: false, reason: attempts_exhausted
Prelude łączy "wrong code" i "out of attempts" w failure; Bird rozdziela je i zwraca obok attempts_remaining, żebyś mógł pokazać użytkownikowi, ile prób mu zostało. Weryfikacja, która już została rozstrzygnięta, zwraca 404 zamiast statusu, więc zapisz pierwszą ostateczną odpowiedź zamiast sprawdzać ponownie.

Co się dzieje z warstwą ryzyka

Odpowiedź create Prelude zawiera werdykt routingu: status o wartości success, retry, challenged, blocked lub shadow_blocked, z reason i risk_factors w przypadku odmowy, oraz method wskazujący wybrany kanał. Odpowiedź create Bird to sama weryfikacja. Nie ma werdyktu do rozgałęzienia, nie ma obiektu sygnałów do wysłania ani odpowiednika shadow block, więc integracja warunkująca rejestracje werdyktem Prelude potrzebuje własnej decyzji przed wywołaniem Bird.
To, co Bird oferuje z tego obszaru, jest węższe i w większości dotyczy konfiguracji: włączanie per kraj, żeby wyłączyć kierunki, których nigdy nie obsługujesz, limity wysyłek i sprawdzeń opisane w Zabezpieczeniach przed nadużyciami oraz sam plan kanałów. Jeśli ochrona przed pompowaniem ruchu była powodem wyboru Prelude, oszacuj tę lukę przed zaplanowaniem migracji.

Przenieś callbacki

Prelude wysyła status dostarczenia na callback_url ustawiany per weryfikacja. Bird dostarcza do endpointów zarejestrowanych przez Twój obszar roboczy, z których każdy subskrybuje wybrane typy zdarzeń, więc URL nie trafia do ciała żądania. Wskaż typy zdarzeń, których potrzebuje Twój handler: verify.verification.created, verify.verification.verified i verify.verification.failed dla sesji oraz verify.attempt.sent, verify.attempt.delivered i verify.attempt.undelivered dla każdego wysłania kodu weryfikacyjnego. Nie ma symbolu wieloznacznego, który je zastępuje. Weryfikuj podpisy zgodnie ze Standard Webhooks. Ładunki zdarzeń znajdziesz w Zdarzenia Verify.

Przełącz ruch

Reguła przełączenia z głównego przewodnika obowiązuje bez zmian: kodu wydanego przez Prelude nie można zweryfikować przez Bird, więc przełącz się na poziomie wywołania create i kieruj każde check do tego dostawcy, który wydał daną weryfikację, aż ostatnia wygaśnie. Ponieważ oba API identyfikują po odbiorcy, rozgałęzienie to jeden warunek wokół istniejących miejsc wywołania, a nie przepisywanie kodu.
Podczas pilota obserwuj konwersję równolegle z dostarczalnością. Prelude routuje per żądanie po szerszym zestawie kanałów; Bird routuje według kolejności kanałów ustawionej per kraj. Jeśli konwersja na danym rynku spadnie, zmień kolejność kanałów tego kraju, zanim wyciągniesz wnioski o migracji.

Następne kroki