Sign inGet Started

Envía tu primer SMS

Envía un mensaje de texto a tu propio teléfono con Bird SMS y luego consulta el mensaje para ver si se entregó. Esta guía rápida usa una plantilla integrada, que proporciona el texto, la categoría y un remitente compartido que Bird selecciona para el destino. No necesitas un ID de remitente ni un registro de remitente.

Antes de empezar, asegúrate de que la billetera de tu organización tenga fondos. Los envíos de SMS se cobran de la billetera, y Bird rechaza un envío que el saldo no pueda cubrir con 402 WalletInsufficientBalance. Métodos de pago y billetera explica cómo recargarla.

Si aún no tienes cuenta, el registro autoservicio crea una desde una terminal con la CLI o con curl, sin navegador. Si tu código llama a la MessageBird API en rest.messagebird.com, esa API y sus claves de acceso son independientes de la API de esta guía rápida. Si vienes de MessageBird explica cómo se relacionan las cuentas, y Migrar SMS desde Bird Connectivity Platform asigna cada campo de la antigua llamada de envío.

1. Crea una clave API

En el panel, ve a Platform tools > API keys y crea una clave con el alcance sms:write, que cubre el envío y la lectura de mensajes. Una clave con solo ese alcance no puede habilitar países de destino de SMS, cambiar los límites de gasto diario de SMS ni añadir fondos: Controles de agentes enumera qué limita a una clave de envío. Las claves están asociadas a una región y tienen el formato bk_us1_... o bk_eu1_.... La región del prefijo indica a qué host de API llamar: https://us1.platform.bird.com o https://eu1.platform.bird.com.

Página de claves API en el panel de Bird, con las claves listadas junto a su prefijo enmascarado, alcances y última fecha de uso

Desde una terminal, bird api-keys create en la Bird CLI emite la misma clave. Para emitir una clave se necesita el alcance api_keys:write, y un inicio de sesión de CLI solo puede asignar a una clave los alcances que tiene él mismo. Este inicio de sesión también solicita sms_management:write, que necesitas en el paso 2. Si creaste la cuenta desde una terminal con bird auth create-org, omite la línea de inicio de sesión: la credencial que guardó el registro ya tiene estos alcances, y un nuevo inicio de sesión la sustituye por otra más limitada.

Ejemplo de código
bird auth login --scope api_keys:write --scope sms:write --scope sms_management:write
bird api-keys create --name "SMS quickstart key" --scope sms:write

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

Ejemplo de código
export BIRD_API_KEY="bk_us1_..."

Mientras BIRD_API_KEY esté definida, la CLI usa la clave en lugar de tu inicio de sesión. Esta clave no puede cambiar los destinos de SMS, así que ejecuta el comando CLI del paso 2 en una shell donde la variable no esté definida.

2. Habilita el país de destino

Bird envía SMS solo a los países habilitados en tu espacio de trabajo. Un envío a cualquier otro país falla con 422 SMSDestinationNotEnabled. Habilita el país de tu número de teléfono en SMS > Destinations. Si ya aparece como habilitado, continúa con el paso 3.

Desde una terminal, el Bird CLI hace el mismo cambio. Pasa el código ISO de dos letras del país, por ejemplo US para Estados Unidos. Si tu inicio de sesión de CLI no tiene acceso a la configuración de SMS, el comando imprime el comando bird auth login que lo añade:

Ejemplo de código
bird sms destinations update --destination US=true

Los agentes conectados al servidor MCP usan la herramienta sms_destinations_update. La API pública no tiene operación para destinos. Un cambio puede tardar hasta un minuto en aplicarse a los envíos.

3. Envía el mensaje

Envía la plantilla bird_otp_verification integrada a tu teléfono. Se muestra como "493021 is your verification code. Do not share it." con el valor code que pases. Instala el Bird SDK para tu lenguaje siguiendo su guía rápida de SDK.

En las pestañas de SDK, sustituye la clave API de ejemplo y sustituye +14155550100 por tu número móvil en formato E.164. La CLI usa tu inicio de sesión, o BIRD_API_KEY mientras esa variable esté definida, y la pestaña de cURL usa BIRD_API_KEY.

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

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

const msg = await bird.sms.send({
  to: "+14155550100",
  template: { slug: "bird_otp_verification", parameters: { code: "493021" } },
});

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

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

La API responde con 202 Accepted y el mensaje. Su id empieza por sms_ y su status es accepted: Bird tiene el mensaje y lo entrega de forma asíncrona. Guarda el id para el siguiente paso. El mensaje llega desde el remitente compartido que Bird seleccionó para tu país.

4. Comprueba el estado de entrega

Consulta el mensaje por su ID. Una lectura justo después del envío puede devolver 404 hasta que el mensaje sea visible en el endpoint de lectura, lo que ocurre poco después del 202. Vuelve a leerlo un momento después. Sustituye SMS_MESSAGE_ID por el id del paso 3, y la clave API de ejemplo en las pestañas de SDK por la tuya. El SDK de Go no tiene un método tipado para leer un mensaje SMS, así que la pestaña de Go llama a la ruta API mediante el método de solicitud client.Get del SDK.

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

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

const msg = await bird.sms.get("SMS_MESSAGE_ID");

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

El campo status indica dónde está el mensaje:

  • accepted: Bird tiene el mensaje y aún no lo ha entregado a un operador.
  • sent: el operador tiene el mensaje, y sent_at registra cuándo Bird se lo entregó.
  • delivered: el operador confirmó la entrega, y delivered_at registra cuándo.
  • undelivered, failed, rejected o expired: el mensaje no llegó al teléfono. last_error indica el motivo, y Errores de entrega explica cada uno.

Consulta periódicamente hasta que el estado deje de ser accepted o sent, o suscríbete a los eventos de SMS para recibir cada cambio por webhook. Cada mensaje también aparece en la página Messages con su línea de tiempo de eventos.

Corregir un envío fallido

  • 422 SMSDestinationNotEnabled: el país del destinatario no está habilitado para tu espacio de trabajo. Habilítalo como en el paso 2, espera hasta un minuto y envía de nuevo.
  • 402 WalletInsufficientBalance: el saldo de la billetera no cubre el mensaje. Recarga la billetera y envía de nuevo.
  • 403 InsufficientScope: la clave API no tiene el alcance sms. Edita los alcances de la clave o crea una clave con sms:write.

Próximos pasos

  • Enviar SMS: envía tu propio texto con un remitente y una categoría, en lotes y con reintentos seguros.
  • IDs de remitente de SMS: elige un remitente para cada país y regístralo donde el país lo exija.
  • Plantillas de SMS: el catálogo de plantillas integradas y sus variables.
  • Eventos de SMS: los tipos de evento y la entrega por webhook de cada cambio de estado.
  • Referencia de SMS API: el esquema completo de solicitud y respuesta.

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