Orchestrazione dei canali

In anteprima

Parti dalle nostre impostazioni predefinite. Sovrascrivi solo ciò che ti serve.

Configura in:

Disponibilità dei canali, regole sui mittenti e normative variano da paese a paese, e gestirle correttamente richiede anni di lavoro. Bird le fornisce come configurazione di base per paese: quali canali funzionano dove, quali mittenti sono consentiti e impostazioni predefinite sensate per i codici. Le tue impostazioni si sovrappongono. Modifichi una cosa per un paese; tutto ciò che non tocchi ricade sul livello sottostante. Questo è il routing per paese come risorsa API di primo livello, il controllo che la maggior parte delle API di verifica non offre.

verify.ts

200 · pending

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });

// Send the code, then check it by recipient.
await bird.verify.verifications.create({
  to: { phone_number: "+15551234567" },
}).safe();

const { data } = await bird.verify.verifications.check({
  to:   { phone_number: "+15551234567" },
  code: userInput,
}).safe();

verify.ts

200 · pending

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });

// Send the code, then check it by recipient.
await bird.verify.verifications.create({
  to: { phone_number: "+15551234567" },
}).safe();

const { data } = await bird.verify.verifications.check({
  to:   { phone_number: "+15551234567" },
  code: userInput,
}).safe();

Erediti le impostazioni predefinite di Bird, poi costruisci su di esse.

Ogni verifica sulla Bird Verify API risolve le proprie impostazioni attraverso una cascata. Alla base c'è una configurazione per paese che Bird mantiene grazie ad anni di gestione di email e SMS — quindi prima ancora di configurare qualsiasi cosa, una verifica viene già instradata in modo sensato in ogni paese. La tua configurazione e le sovrascritture per paese si sovrappongono, e un'opzione per singola richiesta può regolare una singola chiamata. Non parti mai da zero e gestisci solo le decisioni che vuoi davvero prendere.

La cascata dei valori.

Il livello più alto che imposta un valore prevale; tutto ciò che lasci non impostato ricade sul livello sottostante.

01
Opzioni per richiesta.
I campi nella chiamata di creazione (lunghezza del codice, preferenza di canale, locale) prevalgono per quella singola verifica. La sovrascrittura più leggera e locale.
02
Le tue sovrascritture per paese.
Modifica l'ordine dei canali o un mittente per un paese. Una sovrascrittura si fonde: agisce sui campi che imposti, e il resto di quel paese continua a ereditare dal livello sottostante.
03
Le tue impostazioni predefinite di configurazione.
Il piano e le regole dei codici a livello di app — ordine dei canali, lunghezza del codice, TTL e tentativi che desideri ovunque non hai impostato una sovrascrittura per paese.
04
Base per paese di Bird.
Il livello di base: le impostazioni predefinite per paese di Bird, derivate dalla gestione di email e SMS su larga scala. Tutto ciò che lasci non impostato ricade su questo livello, così una verifica si risolve sempre in un piano sensato.

Sovrascrivi un paese, eredita il resto.

Imposta il tuo piano una volta, poi intervieni solo sui paesi che richiedono qualcosa di diverso. Qui il Brasile parte con WhatsApp, poi SMS; tutti gli altri paesi continuano a ricadere sulle tue impostazioni predefinite e sulla base di Bird.

orchestration.ts

200

// Your app-wide default plan.
await bird.verify.verifications.configurations.update("vfc_login", {
  channels: [
    { channel: "email", state: "enabled" },
    { channel: "sms", state: "enabled" },
  ],
}).safe();

// Override one country; the rest inherits.
await bird.verify.verifications.configurations.countries.upsert("vfc_login", "BR", {
  channels: [
    { channel: "whatsapp", state: "enabled" },
    { channel: "sms", state: "enabled" },
  ],
}).safe();

Ciò che una verifica risolve.

Un numero brasiliano con questa configurazione si risolve attraverso la cascata. La sovrascrittura BR ordina WhatsApp poi SMS, entrambi sono disponibili, e la verifica riporta il piano ordinato che utilizzerà, con il suo id tipizzato vrf_.

resolved.ts

200

const { data } = await bird.verify.verifications.create({
  configuration_id: "vfc_login",
  to: { phone_number: "+5511998765432" }, // Brazil
}).safe();

// Resolved through the cascade + availability/kill-switch ceilings:
// {
//   id:           "vrf_01k2m9q8e7fh3v0b7m4d2a9xzt",
//   status:       "pending",
//   channels:     [{ channel: "whatsapp" }, { channel: "sms" }],
//   last_channel: "whatsapp"
// }

Due limiti superiori si trovano sopra la cascata.

La cascata decide le impostazioni predefinite. Due gate decidono cosa è consentito — limitano il piano risolto anziché fornire valori che ricadono verso il basso:

Disponibilità per paese. Puoi abilitare solo i canali che Bird offre effettivamente in un paese. Abilitarne uno che non supportiamo lì è un no-op, non un errore silenzioso — la disponibilità è un'intersezione, mai una sovrascrittura.

Kill-switch globale. Quando un provider ha un incidente, Bird può disattivare un canale ovunque contemporaneamente. La tua configurazione non viene toccata; il piano risolto passa semplicemente al canale successivo, e si ripristina quando il blocco viene rimosso.

Routing che configuri tu, non un ticket da aprire.

Risolto per ogni verifica, restituito nella risposta.

01
Route per paese, in base al numero.
Il paese viene derivato dal numero E.164 del destinatario — non devi specificarlo. Imposta una route per un paese e questa sovrascrive l'ordine e i mittenti in quel paese.
02
Attiva e disattiva i canali.
Ogni canale ha uno stato attivo/disattivo, così puoi disattivarne uno per un paese senza perdere la sua posizione nel piano.
03
Il piano risolto è nella risposta.
Ogni verifica riporta i canali ordinati a cui si è risolta, così ciò che la cascata ha deciso non è mai un mistero.
04
Il failover automatico è in fase di rilascio.
L'avanzamento guidato dalla consegna attraverso il piano (provare il canale successivo quando uno non arriva) è in fase di rilascio man mano che lo stato di consegna viene reso disponibile. Il piano è già risolto e restituito oggi.

FAQ sull'orchestrazione dei canali

Cos'è la cascata di configurazione?+

È il modo in cui vengono risolte le impostazioni di una verifica: prima le opzioni per singola richiesta, poi le personalizzazioni per paese, poi i valori predefiniti della configurazione, infine la base per paese di Bird. Il livello più alto che imposta un valore ha la priorità, e tutto ciò che non viene specificato ricade sul livello inferiore — così configuri solo ciò che vuoi modificare.

Cosa mi offre la base per paese di Bird?+

Un punto di partenza sensato in ogni paese senza alcuna configurazione: quali canali vale la pena provare, quali mittenti sono consentiti e impostazioni predefinite ragionevoli per i codici, mantenute da Bird grazie ad anni di gestione di email e SMS. Costruisci sopra questa base anziché doverla riscoprire da zero.

Una personalizzazione per paese sostituisce l'intero piano?+

No — viene unita. Imposti i campi che differiscono per quel paese e il resto continua a ereditare dalla tua configurazione e dalla base di Bird, quindi una personalizzazione è una modifica piccola e mirata, non una ri-specificazione completa.

Posso abilitare un canale che Bird non offre in un paese?+

No. La disponibilità per paese è un limite massimo, non un valore predefinito: puoi abilitare solo ciò che Bird supporta in quel paese. Abilitare un canale non disponibile è un'operazione senza effetto anziché un errore silenzioso, quindi un piano non può mai promettere un canale che non è effettivamente in grado di inviare.

Come viene determinato il paese?+

Dal numero di telefono E.164 del destinatario, al momento della risoluzione. Non passi un paese; Bird lo ricava e applica il percorso corrispondente. L'email è indipendente dal paese.

Da chi vedono arrivare il codice i miei utenti?+

Authifly, il brand di verifica di Bird. È l'identità su ogni codice che i tuoi utenti ricevono: le email arrivano da otp@verify.authifly.com o dal tuo dominio verificato, mentre SMS e WhatsApp portano il brand Authifly. authifly.com è una pagina pubblica che rassicura i destinatari sul fatto che Authifly invia codici monouso legittimi per conto di un'azienda. Bird è la piattaforma su cui costruisci; Authifly è ciò che il destinatario vede.

Il resto della piattaforma Verify

Un'unica API, un unico set di chiavi. Esplora le altre funzionalità.

SMS OTPCodici monouso via SMS, con copertura globale e limiti di frequenza integrati.Email OTPVerifica via email sulla rete che già gestisce la tua posta transazionale.WhatsApp OTPCodici su WhatsApp come canale ordinabile nello stesso piano.Voice OTPIn fase di rilascio: un codice vocale per telefoni fissi e utenti difficili da raggiungere.Anti-abuso e sicurezza del codiceCodici con hash, limiti per destinatario, blocco dopo tentativi falliti e roadmap antifrode.Panoramica Verify APILa Verify API completa: crea o riprova, verifica per destinatario e configurazione per paese.

Il controllo per paese che nessun'altra API di verifica ti offre.

L'orchestrazione è una funzionalità di Bird Verify: i canali, il codice e i limiti sono inclusi, sugli stessi due endpoint.

Esplora la piattaforma Verify Inizia ora