Documentación
Sign inGet started
Comenzar
Guías
Referencia de API
SDKs
CLI
Base de conocimientos
Registro de cambios

Crear plantillas de WhatsApp

El catálogo administrado de Bird cubre los casos habituales, pero una plantilla con tus propias palabras debe crearse en una cuenta WhatsApp Business Account que hayas conectado. Esta página explica cómo crear una; Plantillas de WhatsApp cubre cómo explorar y enviar las que ya existen.
Tres aspectos definen todo el flujo:
  • Una plantilla contiene versiones, y una versión contiene una entrada por idioma. Lo que realmente se envía es un idioma de una versión, no la plantilla.
  • El contenido se escribe en un borrador. Una plantilla tiene como máximo un borrador abierto, y nada de lo que contiene llega a WhatsApp hasta que lo envías.
  • La aprobación llega por idioma. Un idioma puede aprobarse mientras otro de la misma versión es rechazado.

Antes de empezar

Necesitas un número propio conectado, que es lo que le da a tu espacio de trabajo una cuenta WhatsApp Business Account en la que crear plantillas. Una cuenta que no hayas conectado es rechazada, y también lo es editar una de las plantillas bird_ integradas de Bird: esas viven en la cuenta propia de Bird, así que duplica una en la tuya.
Crear una plantilla de authentication requiere además un negocio verificado; utility y marketing no lo necesitan. Consulta Plantillas de authentication para ese requisito.
Crea una plantilla en el dashboard en WhatsApp > Templates, con la bird CLI, o a través del servidor MCP. El dashboard sigue los mismos pasos que describe esta página; los ejemplos más adelante usan la CLI.

En el dashboard

New template ofrece dos formas de empezar. Start with a template abre la galería, la ruta más rápida: elige una que ya diga casi lo que necesitas, incluida una de Bird, y la copia queda en tu cuenta como borrador abierto.
La galería de plantillas en el dashboard de Bird: una cuadrícula de tarjetas de plantilla, cada una con una vista previa del mensaje y etiquetada con su nombre, slug, estado, categoría e idiomas, junto a filtros por origen de plantilla, categoría e idioma
Start from scratch pide la categoría, un nombre y un idioma predeterminado antes de abrir el editor. Una plantilla de marketing también elige un tipo de mensaje. El nombre se convierte en el slug, y el slug y la categoría son las dos opciones que no puedes cambiar después.
El paso Create a new template en el dashboard de Bird: mosaicos de categoría Marketing, Utility y Authentication sobre un campo Name y un selector Default language, con un botón Create template
El editor escribe un idioma a la vez: la barra lateral lista los idiomas de la plantilla con el estado de revisión de cada uno, la columna central contiene el contenido, y la vista previa del teléfono renderiza el mensaje con valores de ejemplo sustituidos.
El editor de plantillas en el dashboard de Bird para la plantilla de utilidad Order update: English marcado como Approved junto a Dutch en la barra lateral de idiomas, y una vista previa del teléfono con el mensaje renderizado y sus botones Track order y Contact support
El editor cambia de forma según la plantilla. Un carousel añade una pestaña por tarjeta junto al mensaje, y cada tarjeta debe repetir la estructura de la tarjeta 1: el mismo formato de encabezado y los mismos botones en el mismo orden.
El editor de plantillas en el dashboard de Bird para una plantilla de marketing tipo carousel: pestañas Message, Card 1, Card 2 y Card 3 sobre el cuerpo del mensaje, con una sección Variable samples debajo, junto a una vista previa del teléfono que muestra el mensaje seguido de tarjetas de imagen deslizables, cada una con un botón Show me
Una plantilla de authentication no tiene editor de mensaje. WhatsApp escribe el texto, así que el editor ofrece solo los dos ajustes con los que lo genera: Add security recommendation y Code expiration (minutes).
El editor de plantillas en el dashboard de Bird para una plantilla de authentication: un panel Authentication settings con un interruptor Add security recommendation y un campo Code expiration (minutes), junto a una vista previa del teléfono con el mensaje de código de verificación que escribe WhatsApp, con su botón Copy code
Save as draft guarda tu trabajo sin contactar a WhatsApp. Submit for review congela la versión y la envía a WhatsApp. El submit de la CLI, más abajo, realiza la misma congelación.

Dos formas de empezar

Duplicar una plantilla existente

Un duplicado lleva el contenido del origen como borrador abierto y no llama a WhatsApp ninguna vez, así que nada se envía hasta que tú lo decidas. Dos cosas sobre una copia conviene saber antes de hacerla:
  • La categoría se hereda y no se puede cambiar. Si necesitas una categoría diferente, empieza desde cero.
  • Puedes reducir los idiomas, nunca añadirlos. Una plantilla del catálogo con 70 idiomas no tiene que convertirse en 70 idiomas tuyos: elige el subconjunto que realmente vas a mantener. Pedir un idioma que el origen no tiene se rechaza con E15060, y la respuesta indica cuáles no coincidieron. Añade más idiomas a la copia después.
El subconjunto de idiomas es un array, así que va en el cuerpo de la solicitud en lugar de un flag:
Ejemplo de código
bird whatsapp templates duplicate bird_order_confirmation --body-file copy.json
Ejemplo de código
{
  "waba": "102290129340398",
  "slug": "acme_order_update",
  "include_languages": ["en", "es-ES"],
  "default_language": "en"
}
Omite include_languages y la copia toma todos los idiomas del origen. Omite default_language y la copia conserva el predeterminado del origen cuando tu subconjunto aún lo incluye; de lo contrario toma el primero de los idiomas de la copia por etiqueta canónica, que no es necesariamente el primero que listaste, así que defínelo explícitamente si importa.

Empezar desde cero

Crear una plantilla requiere un slug, una cuenta, una categoría y un idioma predeterminado:
Ejemplo de código
bird whatsapp templates create order_update \
  --waba 102290129340398 \
  --category utility \
  --default-language en
El slug y la categoría son permanentes. WhatsApp deriva su propio nombre de plantilla a partir del slug, y ni este ni la categoría pueden cambiarse después; uno diferente implica una plantilla nueva. El prefijo bird_ está reservado para el catálogo de Bird. La categoría que elijas no es necesariamente la que determina el precio de un envío: Meta aplica su propia categoría por idioma y puede cambiarla, y el precio se rige por la categoría de Meta.

Escribir cada idioma

Abre el borrador y luego escribe un idioma a la vez:
Ejemplo de código
bird whatsapp templates versions create order_update
bird whatsapp templates versions languages set order_update <version-id> en --body-file en.json
Abrir un borrador se puede repetir sin riesgo: una plantilla solo tiene uno, así que esto devuelve el que ya está abierto en lugar de crear un segundo. La plantilla también lo reporta como draft_version_id.
Escribir un idioma lo reemplaza completo, no lo fusiona. El archivo lleva el components completo de ese idioma cada vez, así que lee el idioma primero y escríbelo entero; enviar solo el bloque que cambiaste elimina el resto.
Cada variable necesita un valor de ejemplo. WhatsApp revisa el mensaje con los valores completados, no la plantilla, así que un bloque con marcadores y sin parámetros de ejemplo se rechaza al enviar, no al escribir.

Verificar y luego enviar

Valida antes de congelar nada. Un envío de solo validación ejecuta todas las comprobaciones en todos los idiomas y reporta cada problema en un solo paso, sin enviar nada a WhatsApp:
Ejemplo de código
bird whatsapp templates versions submit order_update <version-id> --validate-only
Lee valid y errors; cada error nombra el idioma, el campo y el código con el que fallaría un envío real. Luego envía de verdad eliminando el flag. Eso congela el borrador como una versión inmutable y responde 202. Usa una clave de idempotencia diferente para la verificación y el envío, ya que reutilizar una clave con un cuerpo modificado se rechaza.
Solo los idiomas cuyo contenido difiere de su copia aprobada van a WhatsApp. Uno que ya coincide conserva su aprobación, así que un envío donde nada cambió se resuelve inmediatamente sin nada que consultar. No se abre un borrador de reemplazo después: la siguiente ronda de ediciones empieza creando un borrador de nuevo.
Una ejecución limpia de solo validación no predice la decisión de WhatsApp. WhatsApp no ofrece forma de preguntar por adelantado, así que aún puede rechazar contenido que pasó todas las verificaciones locales.

Seguimiento de la revisión

La aprobación llega después y por idioma. El pending_version_id de la plantilla permanece activo mientras algún idioma no esté resuelto, y la lista por idioma lleva cada veredicto:
  • approved permite enviar. available_languages en la plantilla es exactamente lo que un envío puede resolver en este momento.
  • rejected, submit_failed, paused necesitan una edición en un borrador nuevo. WhatsApp acepta una edición a un idioma pausado, y reenviar es lo que lo desbloquea.
  • disabled, limit_exceeded, in_appeal rechazan una edición directamente; solo necesitan relectura hasta que WhatsApp los mueva.
El status propio de la plantilla es un agregado: active significa que al menos un idioma es enviable, no todos.

Enviar lo que creaste

Una plantilla creada por ti se envía a través del mismo endpoint que cualquier otra, con una diferencia respecto al catálogo de Bird: debes indicar from, y tiene que ser un número en la misma cuenta WhatsApp Business Account que la plantilla. Un remitente en una cuenta diferente se rechaza 422 E15023 antes de cobrar nada.
Una plantilla puede exigir un idioma del destinatario a través de language_source_required. De lo contrario, on_missing_language controla si la resolución falla o puede usar un idioma base aprobado o default_language. Prueba la política configurada contra los available_languages aprobados de la plantilla; un predeterminado no aprobado no es enviable. Los valores que proporcionas deben llenar los marcadores del idioma que realmente se resuelva, así que lee el contenido de ese idioma antes de enviar. Consulta Enviar mensajes de WhatsApp para el payload completo.

Aspectos a tener en cuenta

  • La versión más reciente no es la que se envía. La lista de versiones muestra las más recientes primero e incluye cualquier borrador abierto, así que la primera fila a menudo es un borrador o una versión aún en revisión. La plantilla nombra la versión en servicio como live_version_id; una plantilla sin versión activa no se puede enviar.
  • Un idioma en revisión rechaza una escritura. WhatsApp lo retiene hasta que la revisión termine, así que una edición durante pending falla en lugar de encolarse.
  • Una fila de lista no lleva contenido. Listar plantillas las encuentra y muestra su estado del ciclo de vida; leer lo que realmente dice una requiere una lectura de versión.
  • Eliminar es irrecuperable. Descartar un idioma, eliminar un borrador y eliminar una plantilla requieren una confirmación explícita, y eliminar una plantilla detiene todos los envíos con ese slug.

Próximos pasos

Recursos relacionados

Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.

Comprender el conceptoWhat is a WhatsApp message template?Explorar la funcionalidadWhatsApp templatesSeguir la ruta de aprendizajeBuild your first integration
Prueba el ejercicio y obtén un resumen de implementación