Verifique seu primeiro cliente

Bird Verify confirma que alguém controla um endereço de e-mail ou número de telefone. Você pede a Bird para enviar um código de verificação de uso único. A pessoa digita o código no seu app, e você pergunta a Bird se houve correspondência. Bird gera e entrega o código, e aplica expiração e limites de tentativas. Seu app nunca recebe nem armazena o código gerado.

Este quickstart verifica seu próprio endereço de e-mail, sem exigir nenhuma configuração. Bird envia códigos por e-mail por meio do remetente compartilhado Bird Verify, então você não precisa de domínio nem saldo. Após adicionar fundos a SMS, verificar um número de telefone usa as mesmas duas chamadas.

1. Crie uma chave API

No dashboard, acesse Developers > Chaves API e crie uma chave. As chaves têm escopo por região e se parecem com bk_us1_... ou bk_eu1_...; a região no prefixo indica qual host API chamar: https://us1.platform.bird.com ou https://eu1.platform.bird.com.

A página de chaves API no dashboard Bird, listando chaves com prefixo mascarado, escopos e hora do último uso

A chave completa é exibida uma única vez, no momento da criação. Copie-a em um lugar seguro e depois exporte-a para os exemplos de envio:

Exemplo de código

export BIRD_API_KEY="bk_us1_..."

2. Envie um código

Crie uma verificação para o endereço que você quer confirmar. O único campo obrigatório é to. Use seu próprio endereço de e-mail para poder ler o código. Instale o Bird SDK para a sua linguagem seguindo o quickstart SDK.

Nas abas SDK, substitua a chave API de exemplo e o user@example.com antes de executar o código. A aba CLI usa seu login, e a aba cURL usa BIRD_API_KEY.

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

const bird = new BirdClient({ apiKey: "bk_XXXXXXXXXXXXXXXXXXXXXXXX" });

const verification = await bird.verify.verifications.create({
  to: { email: "user@example.com" },
});

console.log(verification.id, verification.status);

from bird import APIError, Bird

with Bird(api_key="bk_XXXXXXXXXXXXXXXXXXXXXXXX") as client:
    try:
        verification = client.verify.verifications.create(
            to={"email": "user@example.com"},
        )
        print(verification.id, verification.status)
    except APIError as err:
        print("could not start the verification:", err)

package main

import (
	"context"
	"fmt"
	"log"

	bird "github.com/messagebird/bird-sdk-go"
	"github.com/messagebird/bird-sdk-go/option"
)

func main() {
	client, err := bird.NewClient(option.WithAPIKey("bk_XXXXXXXXXXXXXXXXXXXXXXXX"))
	if err != nil {
		log.Fatal(err)
	}

	verification, err := client.Verify.Verifications.Create(context.Background(), bird.VerifyVerificationsCreateParams{
		To: bird.VerificationTo{Email: bird.Email("user@example.com")},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(verification.Id, *verification.Status)
}

<?php

declare(strict_types=1);

require __DIR__ . '/../vendor/autoload.php';

use MessageBird\Bird;
use MessageBird\Wire\Model\VerificationCreateRequest;
use MessageBird\Wire\Model\VerificationTo;

$bird = new Bird('bk_XXXXXXXXXXXXXXXXXXXXXXXX');

$verification = $bird->verify->verifications->create(
    (new VerificationCreateRequest())
        ->setTo((new VerificationTo())->setEmail('user@example.com')),
);

echo $verification->getId(), ' ', $verification->getStatus(), "\n";

bird verify verifications create --email user@example.com

curl -X POST https://us1.platform.bird.com/v1/verify/verifications \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": { "email": "user@example.com" }
  }'

Se a sua chave começa com bk_eu1_, chame https://eu1.platform.bird.com em vez disso.

Bird aceita a solicitação e começa a enviar o código:

Exemplo de código

{
  "id": "vrf_01ky7q1fdze3695yvyz7z9nm3a",
  "status": "pending",
  "reason": null,
  "to": { "email": "user@example.com" },
  "channels": [{ "channel": "email" }],
  "last_channel": "email",
  "expires_at": "2026-07-23T14:55:58Z",
  "verified_at": null,
  "created_at": "2026-07-23T14:45:58Z",
  "updated_at": "2026-07-23T14:45:58Z"
}

Não há ID de verificação para armazenar: a conferência no passo 3 é identificada pelo mesmo destinatário. O e-mail chega de Bird Verify <otp@verify.bird.com> com o assunto "Your verification code" e um código de seis dígitos; a própria mensagem informa quando ele expira. Comprimento do código, validade, limite de tentativas e intervalo de reenvio são configurações do espaço de trabalho, e configurações de verificação lista os valores padrão e os intervalos.

3. Confira o código

Pegue o código na sua caixa de entrada e envie-o, identificado pelo mesmo destinatário:

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

const bird = new BirdClient({ apiKey: "bk_XXXXXXXXXXXXXXXXXXXXXXXX" });

const result = await bird.verify.verifications.check({
  to: { email: "user@example.com" },
  code: "123456",
});

console.log(result.success);

from bird import APIError, Bird

with Bird(api_key="bk_XXXXXXXXXXXXXXXXXXXXXXXX") as client:
    try:
        result = client.verify.verifications.check(
            to={"email": "user@example.com"},
            code="123456",
        )
        print(result.success)
    except APIError as err:
        print("could not check the passcode:", err)

package main

import (
	"context"
	"fmt"
	"log"

	bird "github.com/messagebird/bird-sdk-go"
	"github.com/messagebird/bird-sdk-go/option"
)

func main() {
	client, err := bird.NewClient(option.WithAPIKey("bk_XXXXXXXXXXXXXXXXXXXXXXXX"))
	if err != nil {
		log.Fatal(err)
	}

	result, err := client.Verify.Verifications.Check(context.Background(), bird.VerifyVerificationsCheckParams{
		To:   bird.VerificationTo{Email: bird.Email("user@example.com")},
		Code: "123456",
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(*result.Success)
}

<?php

declare(strict_types=1);

require __DIR__ . '/../vendor/autoload.php';

use MessageBird\Bird;
use MessageBird\Wire\Model\VerificationCheckRequest;
use MessageBird\Wire\Model\VerificationTo;

$bird = new Bird('bk_XXXXXXXXXXXXXXXXXXXXXXXX');

$result = $bird->verify->verifications->check(
    (new VerificationCheckRequest())
        ->setTo((new VerificationTo())->setEmail('user@example.com'))
        ->setCode('123456'),
);

echo $result->getSuccess() ? 'verified' : 'not verified', "\n";

bird verify verifications check 123456 --email user@example.com

curl -X POST https://us1.platform.bird.com/v1/verify/verifications/check \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": { "email": "user@example.com" },
    "code": "123456"
  }'

Um código correto retorna success: true, e a verificação incorporada muda para verified:

Exemplo de código

{
  "success": true,
  "reason": null,
  "attempts_remaining": null,
  "verification": {
    "id": "vrf_01ky7q1fdze3695yvyz7z9nm3a",
    "status": "verified",
    "reason": null,
    "to": { "email": "user@example.com" },
    "channels": [{ "channel": "email" }],
    "last_channel": "email",
    "expires_at": "2026-07-23T14:55:58Z",
    "verified_at": "2026-07-23T14:46:47Z",
    "created_at": "2026-07-23T14:45:58Z",
    "updated_at": "2026-07-23T14:46:47Z"
  }
}

Antes de adicionar esse fluxo a um cadastro, considere estes resultados:

Uma conferência malsucedida retorna HTTP 200. A resposta contém success: false, um reason (incorrect_code, expired ou attempts_exhausted) e um contador attempts_remaining enquanto houver tentativas restantes. Faça a ramificação com base nesse resultado na sua aplicação. A verificação falha permanentemente depois de esgotar suas tentativas de conferência.
Uma verificação se resolve uma única vez. Depois que atinge verified (ou falha ou expira), conferi-la novamente retorna um 404. Trate a primeira resposta definitiva como a resposta. Se o usuário precisar de um novo código, chame o endpoint de criação novamente com o mesmo destinatário: a verificação em andamento é reutilizada, e um código novo é enviado assim que o intervalo de reenvio tiver passado.

Toda verificação que você cria aparece na página Verifications com status, destinatário, canal e horário. O código gerado não aparece.

A página Verifications listando verificações com colunas de status, ID de verificação, destinatário, canal, custo e hora de criação

Verifique um número de telefone

Para verificar por SMS, coloque um número de telefone em to no formato E.164 em vez de um endereço de e-mail:

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://{region}.platform.bird.com/v1/verify/verifications" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": {
      "phone_number": "+15551234567"
    },
    "metadata": {
      "correlation_id": "signup-7f3a"
    }
  }'

A conferência é idêntica: substitua email pelo mesmo phone_number. A entrega por telefone consome o saldo SMS do seu espaço de trabalho, e o país de destino determina a rota. Bird tenta WhatsApp primeiro na maioria dos países e SMS primeiro em alguns. Configuração por país exibe e configura os canais disponíveis e a ordem deles para cada destino. Remetentes e identidade visual mostra o que chega em cada canal.

Alcance o usuário em ambos os canais

Você não precisa escolher um canal. Inclua tanto um email quanto um phone_number em to, e Bird resolve um plano de entrega a partir da sua configuração por país, que mostra os canais disponíveis e a ordem deles para cada destino. Bird segue esse plano até que um envio seja aceito. Se a entrega falhar completamente depois, Bird envia um código novo pelo próximo canal. Confira o código com o mesmo objeto to usado para criar a verificação. O usuário digita o código que chegou primeiro.

Próximos passos

Enviando verificações: opções, status, reenvios, configurações e limites em detalhes.
Configuração por país: ative países e defina a ordem dos canais por país.
Remetentes e identidade visual: como são as mensagens de código e como enviar e-mail do seu próprio domínio.
Referência API do Verify: o esquema completo de solicitação e resposta.
Verificar números de telefone no registo: um vídeo que integra o mesmo fluxo em uma loja virtual

Recursos relacionados

Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.

Entenda o conceitoWhat does OTP mean? One-time passwords explained Explore a funcionalidadeCustomer verification Siga o percurso de aprendizagemBuild your first integration

Experimente na prática e obtenha um resumo de implementação