A API de OTP para desenvolvedores que precisam que os códigos cheguem.
SMS primeiro, fallback por voz num único atributo, pontuação de fraude no momento do envio, limites de taxa por destinatário. Mesma autenticação, mesma idempotência, mesmos webhooks de qualquer outro canal Bird — porque a mesma equipa de engenharia construiu todos.
import { BirdClient } from "@messagebird/sdk";
const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });
// 1. Start the verification.
const { data: start, error: startErr } = await bird.verifications.start({
to: "+15005550006",
channel: "sms",
fallback: "voice",
expires: "10m",
}).safe();
if (startErr) throw startErr;
// → { id: "ver_8sQ91pZ4...", risk_score: 0.04, status: "pending" }
// 2. Check the code the user typed.
const { data: check, error: checkErr } = await bird.verifications.check({
id: start.id,
code: "482917",
}).safe();
if (checkErr) throw checkErr;
console.log(check.status);
// → "approved"5 minutos do npm install à primeira verificação
Inicie uma verificação na linguagem que já utiliza.
SDKs em todos os principais runtimes. A primeira verificação vai para o número de teste autorizado (+15005550006), para que possa incluir um check no CI antes de falar com uma operadora.
import { BirdClient } from "@messagebird/sdk";
const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });
const { data, error } = await bird.verifications.start({
to: "+15005550006",
channel: "sms",
fallback: "voice",
expires: "10m",
}).safe();Dez etapas entre a chamada de início e o próximo ecrã do utilizador.
Primitivas concretas, nomeadas e auditáveis. Sem conversa vaga sobre "deteção de fraude com IA".
- 01
SMS primeiro, fallback por voz num único atributo
Passe fallback: "voice" no início. Se o SMS não chegar em N segundos, ligamos em vez disso. Sem segunda integração.
- 02
Pontuação de fraude no momento do envio
Cada início devolve um risk_score de 0 a 1. Bloqueie os de alto risco antes de gastar um cêntimo em entrega.
- 03
Limites de taxa por destinatário
Limites configuráveis por número de telefone em tentativas por hora e por dia. Bloqueia ataques de força bruta à sua custa.
- 04
Encaminhamento com reconhecimento de operadora
Escolhemos a rota por operadora e por país em tempo real. A T-Mobile US não é o mesmo fio que a Reliance Jio.
- 05
Códigos gerados no servidor
Nunca vê o código; nunca o expomos na rede à saída. Menos uma superfície de fuga na sua stack.
- 06
TTL configurável
Padrão de 10 minutos, intervalo de 30s a 1h. TTL mais curto = menor superfície de fraude; mais longo = melhor UX móvel.
- 07
Contador de tentativas com bloqueio
Máximo de tentativas por verificação (padrão 5). Após o bloqueio, o check devolve verification_locked para uma UX clara.
- 08
OTP por voz em mais de 40 idiomas
Sintetizado no momento do envio, com sotaque correto por locale. Mesma superfície bird.verifications.start — apenas channel: "voice".
- 09
Webhook em cada mudança de estado
Eventos: verification.created, verification.delivered, verification.checked, verification.expired. Mesmo envelope HMAC.
- 10
Pague apenas quando o código chega
Sem cobrança por verification.failed. O filtro de pontuação de fraude e o reembolso por não-entrega mantêm os custos honestos.
Por que criamos o Verifications
Porque os códigos têm de chegar à primeira tentativa, e não podemos pedir às operadoras com jeitinho.
OTP é o canal onde cada ponto percentual de entrega custa um registo. Operamos SMS há dez anos através de 240 conexões diretas com operadoras, por isso quando um código não chega, sabemos se é a rota, a operadora, o dispositivo ou o filtro de fraude — e redirecionamos em tempo real. Bird Verifications é essa lógica de seleção de rota, mais a pontuação de fraude, mais o fallback por voz, mais o contador de tentativas, exposta como dois endpoints com a mesma autenticação e o mesmo contrato de webhook de qualquer outro canal Bird.
import { BirdClient } from "@messagebird/sdk";
const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });
// 1. Start the verification.
const { data: start, error: startErr } = await bird.verifications.start({
to: "+15005550006",
channel: "sms",
fallback: "voice",
expires: "10m",
}).safe();
if (startErr) throw startErr;
// → { id: "ver_8sQ91pZ4...", risk_score: 0.04, status: "pending" }
// 2. Check the code the user typed.
const { data: check, error: checkErr } = await bird.verifications.check({
id: start.id,
code: "482917",
}).safe();
if (checkErr) throw checkErr;
console.log(check.status);
// → "approved"Cada mudança de estado é um webhook.
Payloads assinados com HMAC, protegidos contra replay, idempotentes. O mesmo envelope em todos os canais Bird — aprenda um, aprendeu todos.
{
"type": "verification.delivered",
"id": "evt_5kQ81y...",
"created_at": "2026-05-19T15:42:01.221Z",
"data": {
"verification_id": "ver_8sQ91pZ4",
"to": "+15005550006",
"channel": "sms",
"carrier": "T-Mobile USA",
"risk_score": 0.04,
"latency_ms": 1421
}
}Agenda de retry: 5s, 30s, 5m, 30m, 2h, 6h, 12h. Dead-letter após a última tentativa; cada evento em dead-letter pode ser reenviado a partir do painel ou API.
verification.createdAceite pela API; prestes a despachar no primeiro canal.verification.deliveredOperadora confirmou a receção no dispositivo do destinatário.verification.checkedO destinatário submeteu um código; o payload inclui aprovado ou negado.verification.fellbackSMS não chegou dentro do prazo; o fallback por voz foi despachado.verification.expiredTTL expirou sem uma verificação bem-sucedida.verification.lockedMáximo de tentativas atingido; chamadas de check subsequentes devolvem verification_locked.verification.failedFalha permanente antes do envio (destinatário inválido, rejeição da operadora).
Se já integrou SMS, já integrou Verifications.
Mesma autenticação, mesma idempotência, mesmo envelope de erro, mesmo formato de webhook. A diferença é que o Verifications gera o código, escolhe a rota, executa o filtro de fraude e trata do fallback — para que não tenha de o fazer.
Verifications.
await bird.verifications.start({
to: "+15005550006",
channel: "sms",
fallback: "voice",
});Uma chamada. Escolhemos o canal, a rota, geramos o código, executamos a verificação de fraude, tratamos do bloqueio.
SMS.
await bird.sms.send({
from: "Bird",
to: "+15005550006",
text: `Your code is ${code}.`,
});O envio direto, para quando quer controlar a geração do código e a política de retry.
A partir de $0,04 por verificação, tudo incluído.
Preço por verificação bem-sucedida, SMS ou voz. Sem cobrança por verification.failed. Descontos por volume aplicam-se automaticamente acima de 100K/mês. Sem taxa de plataforma, sem taxa por utilizador, sem funcionalidades bloqueadas atrás de compromissos anuais.