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.

1. Crea una clave API

En el panel, ve a Platform tools > Claves API y crea una clave con el alcance sms:write, que cubre el envío y la lectura de mensajes. Las claves están asociadas a una región y tienen el formato bk_us1_... o bk_eu1_.... La región en el prefijo indica qué host API llamar: https://us1.platform.bird.com o https://eu1.platform.bird.com.

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:

export BIRD_API_KEY="bk_us1_..."

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:

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 quickstart de SDK.

En las pestañas de SDK, reemplaza la clave API de ejemplo y reemplaza +14155550100 con tu número móvil en formato E.164. La pestaña 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 msg = await bird.sms.send({
  to: "+14155550100",
  template: { slug: "bird_otp_verification", parameters: { code: "493021" } },
});

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

from bird import APIError, Bird

with Bird(api_key="bk_XXXXXXXXXXXXXXXXXXXXXXXX") as client:
    try:
        message = client.sms.send(
            to="+14155550100",
            template="bird_otp_verification",
            parameters={"code": "493021"},
        )
        print(message.id, message.status)
    except APIError as err:
        print("send failed:", 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)
	}

	msg, err := client.Sms.Send(context.Background(), bird.SmsSendParams{
		To:         "+14155550100",
		Template:   "bird_otp_verification",
		Parameters: map[string]any{"code": "493021"},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Status)
}

<?php

declare(strict_types=1);

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

use MessageBird\Bird;

$bird = new Bird('bk_XXXXXXXXXXXXXXXXXXXXXXXX');

$message = $bird->sms->send(
    to: '+14155550100',
    template: 'bird_otp_verification',
    parameters: ['code' => '493021'],
);

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

bird sms send \
  --parameters '{"code":"493021"}' \
  --template bird_otp_verification \
  --to +14155550100

curl -X POST https://us1.platform.bird.com/v1/sms/messages \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155550100",
    "template": {
      "slug": "bird_otp_verification",
      "parameters": { "code": "493021" }
    }
  }'

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);

from bird import APIError, Bird

with Bird(api_key="bk_XXXXXXXXXXXXXXXXXXXXXXXX") as client:
    try:
        message = client.sms.get("SMS_MESSAGE_ID")
        print(message.id, message.status)
    except APIError as err:
        print("read failed:", 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)
	}

	var msg bird.SMSMessage
	if err := client.Get(context.Background(), "/v1/sms/messages/SMS_MESSAGE_ID", &msg); err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Status)
}

<?php

declare(strict_types=1);

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

use MessageBird\Bird;

$bird = new Bird('bk_XXXXXXXXXXXXXXXXXXXXXXXX');

$message = $bird->sms->get('SMS_MESSAGE_ID');

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

bird sms get SMS_MESSAGE_ID

curl https://us1.platform.bird.com/v1/sms/messages/SMS_MESSAGE_ID \
  -H "Authorization: Bearer $BIRD_API_KEY"

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 del wallet no cubre el mensaje. Recarga el wallet y envía de nuevo.
• 403 InsufficientScope: la clave API no tiene el scope sms. Edita los scopes 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.
• Sender IDs 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.