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 refleja el idioma resuelto.
• components: los valores que completan las variables de la plantilla (consulta Componentes y parámetros). Omítelo para una plantilla que no tiene 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 comienza con bird_) se envía desde el número que Bird mantiene para esa categoría, así que omite from. Establecerlo devuelve un 422 WhatsAppSenderNotAllowed.
• Cualquier otro caso nombra 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 ser uno que tu espacio de trabajo posea. Omitirlo devuelve un 422 WhatsAppSenderRequired, y un número desde el que el espacio de trabajo no puede enviar devuelve un 422 WhatsAppSenderNotFound. Una plantilla creada por ti también debe estar en la misma cuenta 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 obtiene en el momento del envío (url), así que una URL firmada debe seguir vigente después del envío. Una URL http se rechaza directamente. WhatsApp obtiene el archivo en sí, así que una URL que no puede alcanzar, una que sirve un tipo no soportado 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 otorga a esa tarjeta un botón que abre un chat con él.
• interactive: texto del cuerpo más algo para pulsar, en uno de seis tipos: botones de respuesta, un menú de lista, un botón de enlace, un carrusel de medios o un botón individual que le pide al destinatario su ubicación o su número de teléfono. Mensajes interactivos cubre la estructura de cada tipo, las respuestas que produce 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 límite 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

• En el 202, cost es null. No se ha calculado ningún importe.
• Después del procesamiento, transaction_amount tiene valor y amount es igual a él. passthrough_amount permanece null.
• Después de un acuse de recibo delivered o read aplicable, un cargo de Meta registrado correctamente completa passthrough_amount, y amount refleja los componentes registrados.

Siguientes pasos

• Mensajes de servicio: los nueve tipos de contenido libre y qué acepta cada uno
• Recibir mensajes de WhatsApp: mensajes entrantes, medios y el webhook whatsapp.received
• ID de usuario con alcance de negocio: dirigirte a un contacto que te escribió sin número de teléfono
• Plantillas: explora el catálogo y consulta las variables de una plantilla
• Idempotencia: reintentos seguros con el encabezado Idempotency-Key