Envía tu primer mensaje de WhatsApp
Envía un mensaje de WhatsApp a tu propio teléfono con Bird WhatsApp y después recupera el mensaje para confirmar la entrega. Los envíos iniciados por la empresa usan una plantilla preaprobada. Esta guía rápida envía desde el catálogo de plantillas gestionadas de Bird (como bird_delivery_update o bird_otp), que usa un remitente de WhatsApp compartido y gestionado por Bird. No necesitas conectar antes una cuenta de WhatsApp Business ni registrar un número.
Antes de empezar, asegúrate de que el monedero de tu organización tenga fondos. Los envíos de plantillas de WhatsApp se cobran del monedero, y Bird rechaza con 402 WalletInsufficientBalance cualquier envío que el saldo no pueda cubrir. En Métodos de pago y monedero se explica cómo recargarlo.
1. Crea una clave de API
En el panel, ve a Platform tools > API keys y crea una clave con el ámbito whatsapp:write, que permite enviar y leer mensajes. Cada clave pertenece a una región y tiene un aspecto como bk_us1_... o bk_eu1_.... La región del prefijo indica a qué host de API debes llamar: https://us1.platform.bird.com o https://eu1.platform.bird.com.
La clave completa se muestra una sola vez, al crearla. Cópiala en un lugar seguro y después expórtala para los ejemplos de cURL:
export BIRD_API_KEY="bk_us1_..."2. Envía un mensaje con plantilla
Envía a tu teléfono la plantilla preaprobada bird_delivery_update del catálogo gestionado de Bird, o usa bird_otp para enviar un código de verificación de un solo uso. Las plantillas gestionadas empiezan por bird_ y se envían desde un número de Bird compartido, así que omites from. Instala el SDK de Bird para tu lenguaje siguiendo su guía rápida de SDK. Si usas la pestaña de Bird CLI, instálala antes (curl -fsSL https://cli.bird.com/install.sh | sh) y autentícate con permisos de escritura (bird auth login --scope whatsapp:write).
En las pestañas de SDK, sustituye la clave de API de ejemplo y reemplaza +15551234567 por tu número de móvil en formato E.164. La CLI usa tu inicio de sesión, 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.whatsapp.send({
to: "+15551234567",
template: {
slug: "bird_delivery_update",
components: [
{
type: "body",
parameters: [
{ type: "text", name: "ref", text: "A1B2C3D4" },
{ type: "text", name: "date", text: "10 Jul 2026" },
],
},
],
},
});
console.log(msg.id, msg.status);from bird import APIError, Bird
with Bird(api_key="bk_XXXXXXXXXXXXXXXXXXXXXXXX") as client:
try:
message = client.whatsapp.send(
to="+15551234567",
template="bird_delivery_update",
components=[
{
"type": "body",
"parameters": [
{"type": "text", "name": "ref", "text": "A1B2C3D4"},
{"type": "text", "name": "date", "text": "10 Jul 2026"},
],
}
],
)
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.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
To: "+15551234567",
Template: "bird_delivery_update",
Components: []bird.WhatsAppMessageTemplateComponent{{
Type: "body",
Parameters: &[]bird.WhatsAppMessageTemplateComponentParameter{
{Type: "text", Name: bird.String("ref"), Text: bird.String("A1B2C3D4")},
{Type: "text", Name: bird.String("date"), Text: bird.String("10 Jul 2026")},
},
}},
})
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;
use MessageBird\Wire\Model\WhatsAppMessageTemplateComponent;
use MessageBird\Wire\Model\WhatsAppMessageTemplateComponentParameter;
$bird = new Bird('bk_XXXXXXXXXXXXXXXXXXXXXXXX');
$message = $bird->whatsapp->send(
to: '+15551234567',
template: 'bird_delivery_update',
components: [
(new WhatsAppMessageTemplateComponent())
->setType('body')
->setParameters([
(new WhatsAppMessageTemplateComponentParameter())->setType('text')->setName('ref')->setText('A1B2C3D4'),
(new WhatsAppMessageTemplateComponentParameter())->setType('text')->setName('date')->setText('10 Jul 2026'),
]),
],
);
echo $message->getId(), ' ', $message->getStatus(), "\n";bird whatsapp send \
--components '[{"parameters":[{"name":"ref","text":"A1B2C3D4","type":"text"},{"name":"date","text":"10 Jul 2026","type":"text"}],"type":"body"}]' \
--template bird_delivery_update \
--to +15551234567curl -X POST https://us1.platform.bird.com/v1/whatsapp/messages \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+15551234567",
"template": {
"slug": "bird_delivery_update",
"components": [
{
"type": "body",
"parameters": [
{ "type": "text", "name": "ref", "text": "A1B2C3D4" },
{ "type": "text", "name": "date", "text": "10 Jul 2026" }
]
}
]
}
}'Si tu clave empieza por bk_eu1_, llama a https://eu1.platform.bird.com en su lugar.
La API responde con 202 Accepted y el mensaje creado. Su id empieza por wam_ y su status es accepted: Bird ha aceptado el mensaje y lo entrega de forma asíncrona. Guarda el id para el siguiente paso.
3. Comprueba el estado de entrega
Recupera el mensaje por su ID de wam_. Sustituye WHATSAPP_MESSAGE_ID por el id del paso 2 y sustituye la clave de API de ejemplo en las pestañas de SDK por la tuya:
import { BirdClient } from "@messagebird/sdk";
const bird = new BirdClient({ apiKey: "bk_XXXXXXXXXXXXXXXXXXXXXXXX" });
const msg = await bird.whatsapp.get("WHATSAPP_MESSAGE_ID");
console.log(msg.id, msg.status);from bird import APIError, Bird
with Bird(api_key="bk_XXXXXXXXXXXXXXXXXXXXXXXX") as client:
try:
message = client.whatsapp.get("WHATSAPP_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)
}
msg, err := client.Whatsapp.Get(context.Background(), "WHATSAPP_MESSAGE_ID")
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->whatsapp->get('WHATSAPP_MESSAGE_ID');
echo $message->getId(), ' ', $message->getStatus(), "\n";bird whatsapp get WHATSAPP_MESSAGE_IDcurl https://us1.platform.bird.com/v1/whatsapp/messages/WHATSAPP_MESSAGE_ID \
-H "Authorization: Bearer $BIRD_API_KEY"El campo status indica en qué punto está el mensaje:
accepted: Bird ha admitido el mensaje y se prepara para entregarlo a WhatsApp.sent: WhatsApp ha aceptado el mensaje ysent_atregistra cuándo.delivered: WhatsApp ha confirmado la entrega en el dispositivo del destinatario ydelivered_atregistra cuándo. Cuando el destinatario lee el mensaje, se rellenaread_atystatussigue siendodelivered.failedorejected: el mensaje no llegó al teléfono.last_errorindica el motivo y Eventos de estado de mensajes enumera los códigos de error.
Consulta el mensaje periódicamente hasta que el estado deje de ser accepted o sent, o suscríbete a los webhooks de WhatsApp para recibir cada cambio de estado de entrega y de lectura (whatsapp.sent, whatsapp.delivered, whatsapp.read, whatsapp.failed). Los números compartidos gestionados por Bird solo envían y no dirigen las respuestas entrantes a tu espacio de trabajo; para recibir respuestas, conecta tu propio número. Cada mensaje aparece también en la página Messages con su cronología de eventos.
Soluciona un envío fallido
402WalletInsufficientBalance: el saldo del monedero no cubre el mensaje. Recarga el monedero y vuelve a enviarlo.403InsufficientScope: la clave de API no tiene el ámbitowhatsapp. Edita los ámbitos de la clave o crea una clave conwhatsapp:write.422WhatsAppInvalidRecipient: el número detono es un número de teléfono E.164 válido. Comprueba el+inicial, el código de país y los dígitos del abonado.
Próximos pasos
- Enviar mensajes de WhatsApp: envía plantillas y mensajes de servicio de formato libre dentro de la ventana de atención al cliente de 24 horas.
- Plantillas de WhatsApp: consulta el catálogo gestionado (
bird_otp,bird_delivery_updatey otras) o crea tus propias plantillas. - Conectar un número de teléfono: usa tu propia cuenta de WhatsApp Business y tu propio número de remitente para que tu espacio de trabajo también pueda recibir respuestas entrantes.
- Webhooks de WhatsApp: recibe confirmaciones de entrega y de lectura (y también mensajes entrantes si usas tu propio número conectado).
- Referencia de WhatsApp API: el esquema completo de solicitudes y respuestas.
Recursos relacionados
Continúa con la documentación, guías y ejemplos de este tema.