Envía tu primer mensaje de WhatsApp

Envía un mensaje de WhatsApp a tu propio teléfono con Bird WhatsApp y después consulta el mensaje para confirmar la entrega. Los envíos que inicia la empresa usan una plantilla preaprobada. Esta guía de inicio rápido 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, comprueba que el monedero de tu organización tiene fondos. Los envíos de plantillas de WhatsApp se cargan al 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 el formato 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 página de claves de API en el panel de Bird, con la lista de claves, su prefijo enmascarado, sus ámbitos y la hora del último uso

La clave completa se muestra una sola vez, al crearla. Guárdala en un lugar seguro y después expórtala para los ejemplos de cURL:

Ejemplo de código

export BIRD_API_KEY="bk_us1_..."

2. Envía un mensaje de 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 de inicio rápido de SDK. Si usas la pestaña de Bird CLI, instálala primero (curl -fsSL https://cli.bird.com/install.sh | sh) y autentícate con acceso de escritura (bird auth login --scope whatsapp:write).

En las pestañas de SDK, sustituye la clave de API de ejemplo y sustituye +15551234567 por tu número de móvil en formato E.164. La CLI usa tu sesión iniciada, 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",
    parameters: { ref: "A1B2C3D4", date: "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",
            parameters={"ref": "A1B2C3D4", "date": "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",
		Parameters: map[string]any{"ref": "A1B2C3D4", "date": "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;

$bird = new Bird('bk_XXXXXXXXXXXXXXXXXXXXXXXX');

$message = $bird->whatsapp->send(
    to: '+15551234567',
    template: 'bird_delivery_update',
    parameters: ['ref' => 'A1B2C3D4', 'date' => '10 Jul 2026'],
);

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

bird whatsapp send \
  --parameters '{"date":"10 Jul 2026","ref":"A1B2C3D4"}' \
  --template bird_delivery_update \
  --to +15551234567

curl -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",
      "parameters": {
        "ref": "A1B2C3D4",
        "date": "10 Jul 2026"
      }
    }
  }'

Si tu clave empieza por bk_eu1_, llama a https://eu1.platform.bird.com.

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

Obtén 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 de 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_ID

curl 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, y sent_at registra cuándo.
delivered: WhatsApp ha confirmado la entrega en el dispositivo del destinatario, y delivered_at registra cuándo. Cuando el destinatario lee el mensaje, se rellena read_at y status sigue siendo delivered.
failed o rejected: el mensaje no ha llegado al teléfono. last_error indica el motivo, y Eventos de estado de mensajes enumera los códigos de error.

Consulta 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 mensajes y no dirigen las respuestas entrantes a tu espacio de trabajo; para recibir respuestas, conecta tu propio número. Cada mensaje también aparece en la página Messages con su cronología de eventos.

Soluciona un envío fallido

402 WalletInsufficientBalance: el saldo del monedero no cubre el mensaje. Recarga el monedero y vuelve a enviarlo.
403 InsufficientScope: la clave de API no tiene el ámbito whatsapp. Edita los ámbitos de la clave o crea una clave con whatsapp:write.
422 WhatsAppInvalidRecipient: el número de to no es un número de teléfono E.164 válido. Revisa 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_update y 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 (además de mensajes entrantes si usas tu propio número conectado).
Referencia de WhatsApp API: el esquema completo de solicitud y respuesta.

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

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