Envío de mensajes de WhatsApp

Un envío mínimo

const msg = await bird.whatsapp.send({
  to: "+15551234567",
  template: {
    slug: "bird_otp",
    components: [{ type: "body", parameters: [{ type: "text", text: "123456" }] }],
  },
});
console.log(msg.id, msg.status);

msg = client.whatsapp.send(
    to="+31612345678",
    template="bird_otp",
    language="en",
    components=[{"type": "body", "parameters": [{"type": "text", "text": "123456"}]}],
)
print(msg.id, msg.status)

code := "123456"
msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
	To:       "+15551234567",
	Template: "bird_otp",
	Language: "en",
	Components: []bird.WhatsAppMessageTemplateComponent{{
		Type:       "body",
		Parameters: &[]bird.WhatsAppMessageTemplateComponentParameter{{Type: "text", Text: &code}},
	}},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)

$message = $bird->whatsapp->send(
    to: '+15551234567',
    template: 'bird_otp',
    language: 'en',
    components: [
        (new WhatsAppMessageTemplateComponent())
            ->setType('body')
            ->setParameters([
                (new WhatsAppMessageTemplateComponentParameter())->setType('text')->setText('123456'),
            ]),
    ],
);
echo $message->getId(), ' ', $message->getStatus();

bird whatsapp send \
  --components '[{"parameters":[{"text":"1234","type":"text"}],"type":"body"},{"parameters":[{"text":"1234","type":"text"}],"type":"button"}]' \
  --language en \
  --template bird_otp \
  --to +31612345678

curl -X POST "https://{region}.platform.bird.com/v1/whatsapp/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+31612345678",
    "template": {
      "slug": "bird_otp",
      "language": "en",
      "components": [
        {
          "type": "body",
          "parameters": [
            {
              "type": "text",
              "text": "1234"
            }
          ]
        },
        {
          "type": "button",
          "parameters": [
            {
              "type": "text",
              "text": "1234"
            }
          ]
        }
      ]
    }
  }'

La ventana de servicio al cliente

Construir el payload

Destinatario

Plantilla

• slug (obligatorio): el slug de la plantilla, por ejemplo bird_order_confirmation. Debe coincidir con una plantilla de tu catálogo (letras minúsculas, dígitos y guiones bajos).
• language: la etiqueta de idioma de la plantilla, por ejemplo en o pt-BR. Omítelo para enviar el idioma predeterminado de la plantilla; indicar un idioma que la plantilla no tiene devuelve un 422 que lista los disponibles. El mensaje aceptado repite el idioma resuelto.
• components: los valores que llenan las variables de la plantilla (consulta Componentes y parámetros). Omítelo para una plantilla sin variables.

Componentes y parámetros

{
  "components": [
    { "type": "body", "parameters": [{ "type": "text", "text": "481920" }] },
    { "type": "button", "parameters": [{ "type": "text", "text": "481920" }] }
  ]
}

Categoría y remitente

• Una plantilla gestionada por Bird (su slug empieza con bird_) se envía desde el número que Bird mantiene para esa categoría, así que omite from. Indicarlo devuelve un 422 WhatsAppSenderNotAllowed.
• Todo lo demás indica su propio remitente en from: un mensaje de servicio de cualquier tipo y cualquier plantilla creada por tu espacio de trabajo. El número debe pertenecer a tu espacio de trabajo. Omitirlo devuelve un 422 WhatsAppSenderRequired, y un número desde el que el espacio de trabajo no puede enviar devuelve un 422 WhatsAppSenderNotFound. Además, una plantilla creada por ti debe estar en la misma WhatsApp Business Account que el número, o el envío devuelve un 422 WhatsAppSenderWABAMismatch.

Mensajes de servicio

• text: { "body": "..." }, hasta 4096 caracteres. Añade "preview_url": true para mostrar una vista previa de enlace de la primera URL en body.
• image, video, audio, sticker, document: cada uno toma una URL https pública que WhatsApp descarga en el momento del envío (url), así que una URL firmada debe seguir vigente tras el envío. Una URL http se rechaza directamente. WhatsApp descarga el archivo, así que una URL a la que no puede acceder, una que sirve un tipo no compatible o un archivo que supera el límite de tamaño para su tipo se acepta y luego falla, con media_rejected en el last_error del mensaje y la razón propia de WhatsApp en description. image, video y document también aceptan un caption opcional; document también acepta un filename opcional; audio acepta un flag voice opcional para renderizar como nota de voz.
• location: { "latitude": ..., "longitude": ... } (ambos obligatorios, grados decimales) más name y address opcionales.
• contact_cards: un array de hasta cinco contactos compartidos en un mensaje. El name de cada tarjeta necesita formatted_name más al menos otra parte (first_name, last_name, middle_name, prefix o suffix); phone_numbers, emails, urls y addresses aceptan hasta diez entradas cada uno, y org y birthday (como YYYY-MM-DD) son opcionales. Un phone_number en E.164 le da a esa tarjeta un botón que abre un chat con él.
• interactive: texto del cuerpo más algo para tocar, en uno de seis tipos: botones de respuesta, un menú de lista, un botón de enlace, un carrusel multimedia o un botón único que pide al destinatario su ubicación o su número de teléfono. Mensajes interactivos cubre la estructura de cada tipo, las respuestas que genera un toque y los límites.

{
  "to": "+16505551234",
  "from": "+13124495648",
  "text": { "body": "Your order shipped: https://example.com/track/A1B2C3", "preview_url": true }
}

Citar un mensaje

{
  "to": "+16505551234",
  "from": "+13124495648",
  "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
  "text": { "body": "Yes, that slot is still free." }
}

Etiquetas y metadatos

• tags: hasta 20 etiquetas { "name": ..., "value": ... } estructuradas para dimensiones de baja cardinalidad por las que filtras e informas (una campaña, una variante de experimento). Los nombres y valores aceptan letras ASCII, dígitos, guion bajo y guion; los nombres tienen un máximo de 32 caracteres y son únicos dentro de un envío, los valores de 64. Filtra la lista de mensajes por etiqueta (?tag=campaign o ?tag=campaign:launch-week), y la página de Métricas desglosa la entrega por etiqueta.
• metadata: un objeto JSON arbitrario, hasta 2 KB serializado, para contexto por envío que no necesitas como dimensión de filtro (un ID de pedido interno, una referencia de sesión).

{
  "tags": [{ "name": "campaign", "value": "order-confirmations" }],
  "metadata": { "order_id": "ord_8271" }
}

Referencia de campos

El modelo asíncrono: qué significa 202

Reintentar de forma segura

Recibir la respuesta

Costo y facturación

Note: a service message carries no Meta share until September 30th 2026, and neither does a utility template delivered inside an open customer service window. From October 1st 2026 Meta charges for both, except inside a 72-hour free entry point window, and with 1,000 free service messages per business phone number per month: October 2026 pricing changes.

• En el 202, cost es null. Nada se ha cobrado.
• Después del procesamiento, transaction_amount está establecido y amount es igual a él. passthrough_amount permanece null.
• Después de un acuse delivered o read aplicable, un cargo de Meta registrado correctamente completa passthrough_amount, y amount refleja los componentes registrados.

Próximos pasos

• Mensajes de servicio: envía texto, multimedia y contenido interactivo dentro de la ventana de servicio al cliente
• Plantillas: elige una plantilla y proporciona sus variables
• Recibir mensajes de WhatsApp: lee respuestas y obtén multimedia entrante
• Webhooks de estado de mensajes: recibe actualizaciones de entrega y fallos
• Idempotencia: reintenta de forma segura con el encabezado Idempotency-Key