Verifica a tu primer cliente

Bird Verify confirma que un cliente controla una dirección de correo electrónico o un número de teléfono. Pides a Bird que envíe un código de verificación de un solo uso. Tu cliente lo introduce en tu aplicación y preguntas a Bird si coincide. Bird genera y entrega el código, y aplica la expiración y los límites de intentos. Tu aplicación nunca recibe ni almacena el código generado.

Este quickstart verifica tu propia dirección de correo electrónico, lo que no requiere configuración. Bird envía los códigos por correo electrónico a través de su remitente compartido Bird Verify, así que no necesitas dominio ni saldo. Después de añadir fondos a SMS, verificar un número de teléfono usa las mismas dos llamadas.

1. Crea una clave API

En el dashboard, ve a Platform tools > API keys y crea una clave. Las claves están asociadas a una región y tienen el formato bk_us1_... o bk_eu1_...; la región del prefijo te indica a qué host API debes llamar: https://us1.platform.bird.com o https://eu1.platform.bird.com.

La página API Keys en el dashboard de Bird, con las claves listadas con su prefijo enmascarado, sus alcances y su último uso

La clave completa se muestra una sola vez, en el momento de creación. Cópiala en un lugar seguro y luego expórtala para los ejemplos de envío:

Ejemplo de código

export BIRD_API_KEY="bk_us1_..."

2. Envía un código

Crea una verificación para la dirección que quieres confirmar. El único campo obligatorio es to. Usa tu propia dirección de correo electrónico para que puedas leer el código. Instala el Bird SDK para tu lenguaje siguiendo su quickstart de SDK.

En las pestañas de SDK, reemplaza la clave API de ejemplo y user@example.com antes de ejecutar el código. CLI usa tu inicio de sesión, y la pestaña 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" }
  }'

Si tu clave empieza con bk_eu1_, llama a https://eu1.platform.bird.com en su lugar.

Bird acepta la solicitud y comienza a enviar el código:

Ejemplo 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"
}

No necesitas guardar un ID de verificación: la comprobación en el paso 3 se identifica por el mismo destinatario. El correo llega desde Bird Verify <otp@verify.bird.com> con el asunto "Your verification code" y un código de seis dígitos; el propio mensaje indica cuándo expira. La longitud del código, la duración, el límite de intentos y el tiempo de espera para reenvío son configuraciones del espacio de trabajo, y configuración de verificación lista los valores predeterminados y los rangos.

3. Comprueba el código

Toma el código de tu bandeja de entrada y envíalo, identificado por el mismo destinatario:

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"
  }'

Un código correcto devuelve success: true, y la verificación incluida cambia a verified:

Ejemplo 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 añadir este flujo a un registro, ten en cuenta estos resultados:

Una comprobación fallida devuelve HTTP 200. La respuesta contiene success: false, un reason (incorrect_code, expired o attempts_exhausted), y un contador attempts_remaining mientras queden intentos. Gestiona este resultado en tu aplicación. La verificación falla permanentemente cuando agota sus intentos de comprobación.
Una verificación se resuelve una sola vez. Cuando alcanza verified (o falla o expira), volver a comprobarla devuelve un 404. Toma la primera respuesta definitiva como la respuesta. Si tu cliente necesita un código nuevo, vuelve a llamar al endpoint de creación con el mismo destinatario: se reutiliza la verificación en curso y se envía un código nuevo cuando haya pasado el tiempo de espera para reenvío.

Cada verificación que creas aparece en la página Verifications con su estado, destinatario, canal y tiempos. El código generado no aparece.

La página de Verifications con verificaciones listadas con columnas de estado, ID de verificación, destinatario, canal, costo y fecha de creación

Verifica un número de teléfono en su lugar

Para verificar por SMS, pon un número de teléfono en to en formato E.164 en lugar de una dirección de correo electrónico:

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"
    }
  }'

La comprobación es idéntica: reemplaza email con el mismo phone_number. El envío telefónico consume el saldo SMS de tu espacio de trabajo, y el país de destino determina la ruta. Bird intenta WhatsApp primero en la mayoría de países y SMS primero en algunos. Configuración por país muestra y configura los canales disponibles y su orden para cada destino. Remitentes y marca muestra lo que llega en cada canal.

Contacta al usuario por ambos canales

No tienes que elegir un solo canal. Incluye tanto un email como un phone_number en to, y Bird genera un plan de entrega a partir de tu configuración por país, que muestra los canales disponibles y su orden para cada destino. Bird sigue ese plan hasta que se acepta un envío. Si más tarde la entrega falla por completo, Bird envía un código nuevo por el siguiente canal. Comprueba el código con el mismo objeto to que usaste para crear la verificación. Tu cliente introduce el código que le haya llegado.

Próximos pasos

Envío de verificaciones: opciones, estados, reenvíos, configuraciones y límites en detalle.
Configuración por país: habilita países y establece el orden de canales por país.
Remitentes y marca: cómo se ven los mensajes con el código y cómo enviar correo desde tu propio dominio.
Referencia API de Verify: el esquema completo de solicitud y respuesta.
Verifica números de teléfono en el registro: un video que integra el mismo flujo en una tienda web

Continúa con la documentación, guías y ejemplos de este tema.

Prueba el ejercicio y obtén un resumen de implementación

Verifica a tu primer cliente

1. Crea una clave API

2. Envía un código

3. Comprueba el código

Verifica un número de teléfono en su lugar

Contacta al usuario por ambos canales

Próximos pasos

Recursos relacionados