Wysyłanie weryfikacji

Weryfikacja użytkownika wymaga dwóch wywołań. POST /v1/verify/verifications wysyła kod weryfikacyjny na adres e-mail lub numer telefonu. POST /v1/verify/verifications/check przesyła wartość wpisaną przez użytkownika i zwraca informację, czy się zgadza. Bird generuje kod, nie zwraca go w odpowiedzi API i egzekwuje czas ważności oraz limity prób.

Wyślij kod

Najmniejsze prawidłowe żądanie to odbiorca to:

const verification = await bird.verify.verifications.create({
  to: { phone_number: "+15551234567" },
});
console.log(verification.id, verification.status);

verification = client.verify.verifications.create(to={"phone_number": "+15551234567"})
print(verification.id, verification.status)

verification, err := client.Verify.Verifications.Create(context.Background(), bird.VerifyVerificationsCreateParams{
	To: bird.VerificationTo{PhoneNumber: bird.String("+15551234567")},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(verification.Id, *verification.Status)

$verification = $bird->verify->verifications->create(
    (new VerificationCreateRequest())->setTo((new VerificationTo())->setPhoneNumber('+15551234567')),
);
echo $verification->getId(), ' ', $verification->getStatus();

bird verify verifications create --body-file - <<'JSON'
{
  "to": {
    "phone_number": "+15551234567"
  },
  "metadata": {
    "correlation_id": "signup-7f3a"
  }
}
JSON

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

Użyj regionalnego hosta (https://us1.platform.bird.com lub https://eu1.platform.bird.com) z pasującym kluczem bk_{region}_....

Odbiorca

to identyfikuje odbiorcę za pomocą email, phone_number w formacie E.164 lub obu naraz. Adres e-mail umożliwia dostarczenie e-mailem. Numer telefonu jest rozwiązywany na kanały dostępne w kraju docelowym, w kolejności ustawionej w konfiguracji krajowej. Większość krajów próbuje WhatsApp przed SMS, niektóre próbują najpierw SMS; Telegram następuje po obu w platformowej kolejności awaryjnej. Gdy podasz oba adresy, nieudana próba może przejść na inny dostępny kanał.

Opcje

options nadpisuje ustawienia tylko dla tego żądania:

• code_length: długość kodu weryfikacyjnego dla tej weryfikacji, od 4 do 8 cyfr, nadpisująca wartość domyślną.
• channels: zmień kolejność lub zawęź kanały dostarczania dla tego żądania. Wymień nazwy kanałów (sms, whatsapp, email, telegram) w kolejności prób; pominięty kanał nie jest używany, a nazwa spoza rozwiązanego planu odbiorcy jest ignorowana. Tą drogą nie dodasz nowego kanału, a jedynie przytniesz lub zmienisz kolejność tego, na co pozwala odbiorca i konfiguracja krajowa. Lista, która nie zostawia żadnego użytecznego kanału, kończy żądanie błędem 422.
• language: tag BCP 47, np. fr lub pt-BR, który wybiera wbudowane tłumaczenie wiadomości z kodem. Pomiń go, a język zostanie dobrany na podstawie numeru telefonu odbiorcy; zobacz Język wiadomości.

Metadane

metadata to obiekt dowolnej formy zwracany przy każdym odczycie; użyj go do przekazania własnego identyfikatora użytkownika lub referencji sesji. Wybór nadawcy i ustawienia weryfikacji nie są częścią żądania: pochodzą z konfiguracji obszaru roboczego zarządzanej w dashboardzie (zobacz Ustawienia weryfikacji).

Odpowiedź

{
  "id": "vrf_01ky7q1fdze3695yvyz7z9nm3a",
  "status": "pending",
  "reason": null,
  "to": { "phone_number": "+15551234567" },
  "channels": [{ "channel": "whatsapp" }, { "channel": "sms" }],
  "last_channel": "whatsapp",
  "expires_at": "2026-07-23T14:55:58Z",
  "verified_at": null,
  "created_at": "2026-07-23T14:45:58Z",
  "updated_at": "2026-07-23T14:45:58Z"
}

channels to uporządkowany plan dostarczania, do którego ta weryfikacja została rozwiązana (odbiorca telefoniczny wyświetla swoje kanały telefoniczne w kolejności prób), a last_channel wskazuje, dokąd trafił ostatni kod. expires_at określa, kiedy weryfikacja wygaśnie, jeśli nie nadejdzie poprawny kod; ponowne wysyłki nie wydłużają tego czasu.

Język wiadomości

Wiadomości Bird SMS, e-mail i współdzielonego nadawcy WhatsApp są dostępne w 40 wbudowanych tłumaczeniach. Niestandardowy nadawca WhatsApp korzysta z zatwierdzonych języków wybranego szablonu uwierzytelniania. Telegram generuje własną treść wiadomości, więc to ustawienie nie ma tam wpływu.

Bez options.language język pochodzi z numeru telefonu odbiorcy. Numer francuski dostaje francuski, a numer japoński dostaje japoński, bez konieczności wskazywania tego. Weryfikacja bez numeru telefonu wysyła po angielsku, podobnie jak weryfikacja, której kraj nie ma tłumaczenia.

Ustaw options.language, aby wybrać język samodzielnie, na przykład dopasowując go do języka wybranego przez użytkownika w Twojej aplikacji zamiast kraju jego numeru:

{
  "to": { "phone_number": "+15551234567" },
  "options": { "language": "es" }
}

Tag bez własnego wbudowanego tłumaczenia przechodzi na język bazowy, a następnie na angielski: en-GB wysyła po angielsku, pt-BR wysyła po portugalsku. Odrzucany jest tylko nieprawidłowo sformułowany tag, z błędem 422. Oto wbudowane tłumaczenia, o które możesz poprosić, wszystkie dostępne na SMS i e-mailu, a wszystkie oprócz mongolskiego na współdzielonym nadawcy WhatsApp w Bird:

Autorytatywną listą jest dokumentacja referencyjna create-verification.

Język jest ustalany w momencie utworzenia weryfikacji, więc ponowne wysłanie lub przełączenie na inny kanał dociera w tym samym języku co pierwsza wiadomość. Ponowne wywołanie create dla tego samego odbiorcy z innym language ponownie wykorzystuje trwającą weryfikację i nie zmienia jej.

Tłumaczenie użyte przy wysyłce może się różnić od wysłanego tagu, jeśli nastąpiło przejście na język zastępczy. Otwórz weryfikację na stronie Verifications, aby to sprawdzić: każda próba pokazuje użyty język jako tag Template. Współdzielony nadawca WhatsApp w Bird nie ma szablonu dla mongolskiego (mn), więc dla tego języka wysyła po angielsku, podczas gdy SMS i e-mail zachowują mongolski. Twój własny szablon WhatsApp stosuje swoje zatwierdzone języki i politykę językową; język, którego nie może wysłać, może spowodować niepowodzenie próby WhatsApp.

Możesz wybrać język dla każdego żądania, ale nie możesz przekazać treści wiadomości w tym żądaniu. Niestandardowy nadawca WhatsApp używa treści wybranego szablonu uwierzytelniania. Senders and branding przedstawia dostępne opcje nadawców i tekst wiadomości Bird.

Sprawdź kod

Prześlij to, co wpisał użytkownik, do POST /v1/verify/verifications/check, identyfikując żądanie tym samym odbiorcą; identyfikator weryfikacji nie jest potrzebny. Podaj dokładnie ten zestaw to, z którym utworzyłeś weryfikację: weryfikacji utworzonej z oboma adresami nie znajdziesz, podając tylko jeden z nich.

const result = await bird.verify.verifications.check({
  to: { phone_number: "+15551234567" },
  code: "123456",
});
console.log(result.success);

result = client.verify.verifications.check(
    to={"phone_number": "+15551234567"}, code="123456"
)
print(result.success)

result, err := client.Verify.Verifications.Check(context.Background(), bird.VerifyVerificationsCheckParams{
	To:   bird.VerificationTo{PhoneNumber: bird.String("+15551234567")},
	Code: "123456",
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(*result.Success)

$result = $bird->verify->verifications->check(
    (new VerificationCheckRequest())
        ->setTo((new VerificationTo())->setPhoneNumber('+15551234567'))
        ->setCode('123456'),
);
echo $result->getSuccess() ? 'verified' : 'failed';

bird verify verifications check 123456 --phone-number +15551234567

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

Odpowiedź informuje, czy kod się zgadza:

{
  "success": false,
  "reason": "incorrect_code",
  "attempts_remaining": 4,
  "verification": {
    "id": "vrf_01ky7q1fdze3695yvyz7z9nm3a",
    "status": "pending",
    "reason": null,
    "to": { "phone_number": "+15551234567" },
    "channels": [{ "channel": "whatsapp" }, { "channel": "sms" }],
    "last_channel": "whatsapp",
    "expires_at": "2026-07-23T14:55:58Z",
    "verified_at": null,
    "created_at": "2026-07-23T14:45:58Z",
    "updated_at": "2026-07-23T14:46:38Z"
  }
}

Obsłuż dwa zachowania odpowiedzi:

• Nieprawidłowy kod zwraca 200. Traktuj success: false z reason (incorrect_code, expired, attempts_exhausted) jako normalną odpowiedź. attempts_remaining informuje, ile prób pozostało. Obsługę błędów zarezerwuj dla niepowodzeń żądania.
• Zakończonej weryfikacji nie można sprawdzić ponownie. Gdy weryfikacja osiągnie dowolny stan końcowy, kolejne sprawdzenia zwracają 404. Zapisz pierwszy ostateczny wynik zamiast sprawdzać ponownie.

Jeśli użytkownik poprosił o nowy kod, wywołaj ponownie endpoint create z tym samym odbiorcą: trwająca weryfikacja zostanie ponownie wykorzystana, a nie zastąpiona. Gdy minie czas oczekiwania na ponowne wysłanie (domyślnie 60 sekund), wysyłany jest nowy kod; w trakcie tego okresu wywołanie zwraca aktywną weryfikację bez ponownego wysyłania. Każdy kod wysłany w ramach aktywnej weryfikacji pozostaje ważny, dopóki weryfikacja nie zostanie rozwiązana lub nie wygaśnie, więc użytkownik może wpisać dowolny, który dotarł.

Wyślij kod innym kanałem

Gdy użytkownik zgłosi, że kod w ogóle nie dotarł, POST /v1/verify/verifications/next-channel przesuwa weryfikację na następny kanał w planie i wysyła tam nowy kod. To jest endpoint pod przyciskiem "I didn't receive my code": Twoja aplikacja decyduje o zmianie kanału zamiast czekać na sygnał o statusie dostarczenia.

Identyfikuj żądanie tym samym odbiorcą, z którym utworzyłeś weryfikację, tak jak przy sprawdzaniu:

const verification = await bird.verify.verifications.nextChannel({
  to: { phone_number: "+15551234567" },
});
console.log(verification.last_channel);

verification = client.verify.verifications.next_channel(
    to={"phone_number": "+15551234567"}
)
print(verification.last_channel)

verification, err := client.Verify.Verifications.NextChannel(context.Background(), bird.VerifyVerificationsNextChannelParams{
	To: bird.VerificationTo{PhoneNumber: bird.String("+15551234567")},
})
if err != nil {
	log.Fatal(err)
}
if verification.LastChannel != nil {
	fmt.Println(*verification.LastChannel)
}

$verification = $bird->verify->verifications->nextChannel(
    (new VerificationNextChannelRequest())->setTo((new VerificationTo())->setPhoneNumber('+15551234567')),
);
echo $verification->getLastChannel();

bird verify verifications next-channel --phone-number +15551234567

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

Odpowiedzią jest weryfikacja, gdzie last_channel wskazuje kanał, na który trafił nowy kod. Każdy wcześniej wysłany kod pozostaje ważny, więc wiadomość, która dotrze z opóźnieniem, nadal może zostać sprawdzona.

Dwie rzeczy odróżniają to od ponownego wysłania:

• Okres oczekiwania na ponowne wysłanie nie obowiązuje. Celowe przełączenie kanału to inna czynność niż prośba o ten sam kanał ponownie, więc wysyłka następuje natychmiast.
• Przesuwa się tylko kanał. Czas wygaśnięcia, budżet prób i identyfikator weryfikacji pozostają bez zmian.

Użyj ponownego wysłania, gdy użytkownik chce kolejnej próby na kanale, który działa, a tego endpointu, gdy problemem wydaje się sam kanał. Numer telefonu z planem WhatsApp, potem SMS, przechodzi na SMS; odbiorca z tylko jednym dostępnym kanałem nie ma dokąd przejść.

Cztery odpowiedzi wymagają obsługi zamiast prostego ponowienia:

Każdy kod wysłany przez ten endpoint jest rozliczany tak samo jak każda inna wysyłka Verify; zobacz Koszty i rozliczenia.

Statusy

Weryfikacja ma status pending, dopóki nie przejdzie w stan końcowy, a reason wskazuje przyczynę:

reason to otwarty enum. Zachowaj nierozpoznaną wartość zamiast traktować odpowiedź jako nieprawidłową.

Odbicie, odrzucenie przez operatora lub przekroczenie limitu czasu dostarczenia mogą pozostawić sesję w stanie oczekiwania, ponieważ odbiorca może nadal mieć ważny kod. Samo wyczerpanie planu dostarczenia nie oznacza, że sesja się nie powiodła. Warunki niepowodzenia opisuje sekcja Zdarzenia Verify.

Śledzenie weryfikacji w dashboardzie

Strona Verifications wyświetla wszystkie weryfikacje utworzone w obszarze roboczym, z możliwością filtrowania według statusu. Każdy wiersz otwiera dane odbiorcy, plan kanałów, ostatni kanał, czas wygaśnięcia i weryfikacji oraz metadane. Wygenerowany kod nie jest wyświetlany.

Ustawienia weryfikacji

Strona Configure konfiguruje cykl weryfikacji w obszarze roboczym. Każde pole pokazuje obowiązującą wartość: Twoje nadpisanie, jeśli je ustawiłeś, lub domyślną wartość platformy Bird.

• Duration: jak długo kod pozostaje ważny. Domyślnie 10 minut; od 1 minuty do 999 minut.
• Maximum Retries: ile prób sprawdzenia kodu przed niepowodzeniem weryfikacji ze statusem attempts_exhausted. Domyślnie 5; od 1 do 10.
• Retry Delay: okres oczekiwania przed wysłaniem nowego kodu do tego samego odbiorcy. Domyślnie 60 sekund; od 0 do 3600.

Długość kodu nie jest polem na tej stronie: domyślnie kody mają 6 cyfr, numeryczne, a options.code_length ustawia od 4 do 8 cyfr na żądanie.

Zabezpieczenia przed nadużyciami

Niezależnie od Twoich ustawień Verify wymusza limity platformy, aby ruch OTP nie mógł być wykorzystywany jako broń, czy to przeciwko Twojemu portfelowi (pumping SMS), czy przeciwko skrzynce ofiary:

• 5 wysyłek na adres na kroczącą godzinę, łącznie z tworzeniem i ponownym wysyłaniem weryfikacji. Gdy to zawiera oba adresy, każdy ma własny budżet.
• 10 sprawdzeń na zestaw adresów odbiorcy na minutę, oprócz limitu prób samej weryfikacji.

Plan kanałów, a nie limit godzinowy, ogranicza zmiany kanałów. Każde wywołanie przesuwa się ściśle do przodu, więc jedna weryfikacja wysyła co najwyżej raz na każdy pozostały kanał.

Osiągnięcie limitu zwraca 429; wstrzymaj się i spróbuj ponownie po okresie wskazanym w nagłówku Retry-After. Ogólne limity żądań Twojego konta są osobne i skalowane według planu; zobacz Limity żądań.

Bezpieczne ponawianie

Wszystkie trzy endpointy przyjmują nagłówek Idempotency-Key. Wysyłaj unikalną wartość dla każdego logicznego żądania. Po przekroczeniu limitu czasu lub zerwanym połączeniu ponowienie z tym samym kluczem odtwarza oryginalną odpowiedź. Odtworzenie nie wysyła kolejnego kodu ani nie zużywa kolejnej próby sprawdzenia i zawiera nagłówek Idempotency-Replay. Format klucza i czas przechowywania opisuje sekcja Idempotentność.

Koszt i rozliczenia

Rozliczenie dotyczy każdego wysłanego kodu. Każdy wysłany kod jest pobierany z Twojego portfela według stawki kanału dla danego celu. Ponowna wysyłka lub przejście na inny kanał dodaje jedną opłatę za wysyłkę. Opłata własna Bird jest pobierana w trakcie przetwarzania wysyłki i obowiązuje niezależnie od tego, czy kod dotrze; w przypadku SMS i WhatsApp opłata od strony trzeciej następuje po dostarczeniu wiadomości. Darmowe trasy i sprawdzenia nie kosztują nic; wysyłka odrzucona przed rozliczeniem nie jest pobierana. Saldo i doładowania opisuje sekcja Metody płatności i portfel.

Telegram rozlicza się w innym momencie wysyłki. Zanim wiadomość zostanie wysłana, Telegram jest pytany, czy numer może ją odebrać; opłata jest naliczana, gdy odpowiedź brzmi tak, według stałej stawki na całym świecie, a numer, którego nie da się osiągnąć, jest darmowy i przechodzi do następnego kanału bez naliczania opłat. Opłata za Telegram oznacza więc, że wiadomość została przyjęta do dostarczenia, a nie że dotarła: kod, który nie zostanie dostarczony, pozostaje naliczony, a weryfikacja ponownie płaci za kanał, na który przechodzi. Jeśli nie chcesz tej drugiej opłaty, usuń Telegram z kolejności kanałów dla tych krajów na stronie Countries.

Następne kroki