# Migracja Verify z Prelude

Ta strona mapuje API weryfikacji Prelude v2 na Bird Verify. Postępuj zgodnie z [głównym przewodnikiem migracji](/docs/guides/verify/migrate) 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`](/docs/api/reference/create-verification) oraz [`POST /v1/verify/verifications/check`](/docs/api/reference/create-verification-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.

```text
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 robi                        | Prelude                                                                          | Bird                                                                                                                    |
| ------------------------------ | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Odbiorca                       | `target.type` + `target.value`                                                   | `to.phone_number` lub `to.email`                                                                                        |
| Długość kodu                   | `options.code_size`                                                              | `options.code_length`                                                                                                   |
| Preferencja kanału             | `options.preferred_channel`, `options.channels`                                  | `options.channels`, w przeciwnym razie skonfigurowana kolejność danego kraju                                            |
| Korelacja                      | `metadata.correlation_id`                                                        | `metadata`                                                                                                              |
| Callbacki dostarczenia         | `options.callback_url`                                                           | webhook obszaru roboczego subskrybujący wybrane typy zdarzeń verify                                                     |
| Własny kod weryfikacyjny       | `options.custom_code`                                                            | brak odpowiednika                                                                                                       |
| Lokalizacja                    | `options.locale`                                                                 | `options.language`                                                                                                      |
| Tożsamość nadawcy              | `options.sender_id`                                                              | wybierz nadawcę zarządzanego przez Bird lub należącego do obszaru roboczego według kanału lub kraju, nie według żądania |
| Szablon wiadomości             | `options.template_id`, `options.variables`                                       | brak odpowiednika per żądanie; wybierz zatwierdzony szablon uwierzytelniania WhatsApp w konfiguracji Verify             |
| Autouzupełnianie na Androidzie | `options.app_realm`                                                              | brak odpowiednika                                                                                                       |
| Sygnały ryzyka                 | `signals` (IP, urządzenie, fingerprint)                                          | nieobsługiwane                                                                                                          |
| Bezpieczne ponowienia          | brak klucza idempotentności ani nagłówka w referencji create i check             | nagłówek `Idempotency-Key`                                                                                              |
| Korelacja sygnałów             | `dispatch_id`, "the identifier of the dispatch that came from the front-end SDK" | brak odpowiednika: Bird nie przyjmuje sygnałów                                                                          |
| Kontrola fallbacku             | `options.max_auto_fallbacks`, `options.force_challenge`                          | plan 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`](/docs/guides/idempotency).

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 `status`              | Bird                                           |
| ----------------------------- | ---------------------------------------------- |
| `success`                     | `success: true`                                |
| `failure`                     | `success: false`, `reason: incorrect_code`     |
| `expired_or_not_found`        | `success: 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](/docs/guides/verify/sending-verifications#abuse-guardrails) 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](https://www.standardwebhooks.com). Ładunki zdarzeń znajdziesz w [Zdarzenia Verify](/docs/guides/verify/events).

## Przełącz ruch

[Reguła przełączenia](/docs/guides/verify/migrate#5-cut-over-one-code-lifetime-at-a-time) 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

- [Wysyłanie weryfikacji](/docs/guides/verify/sending-verifications): pełny kontrakt obu wywołań, statusy i limity
- [Konfiguracja krajowa](/docs/guides/verify/countries): kolejność i dostępność kanałów per kraj
- [Nadawcy i branding](/docs/guides/verify/senders): co odbiorca widzi na każdym kanale
- [Zdarzenia Verify](/docs/guides/verify/events): zdarzenia, na które przechodzi Twój konsument callbacków

## Related resources

- [Verify phone numbers at signup](/learn/series/verify-phone-numbers-at-signup) (video)
- [What does OTP mean? One-time passwords explained](/explained/verify/what-does-otp-mean) (answer)
- [Customer verification](/verify-api) (product)
- [Build your first integration](/learn/paths/integration) (course)

[Get an implementation brief](/learn/workspace?topic=verify)