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.

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.
bird auth login --scope api_keys:write --scope sms:write --scope sms_management:write
bird api-keys create --name "SMS quickstart key" --scope sms:writeLa 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_..."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:
bird sms destinations update --destination US=trueLos 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);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 +14155550100curl -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_IDcurl 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, ysent_atregistra cuándo Bird se lo entregó.delivered: el operador confirmó la entrega, ydelivered_atregistra cuándo.undelivered,failed,rejectedoexpired: el mensaje no llegó al teléfono.last_errorindica 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
422SMSDestinationNotEnabled: 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.402WalletInsufficientBalance: el saldo de la billetera no cubre el mensaje. Recarga la billetera y envía de nuevo.403InsufficientScope: la clave API no tiene el alcancesms. Edita los alcances de la clave o crea una clave consms: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.
Recursos relacionados
Continúa con la documentación, guías y ejemplos de este tema.