Plantillas de WhatsApp
Los envíos de WhatsApp iniciados por la empresa usan una plantilla preaprobada. Una plantilla contiene texto fijo y variables, así que un envío solo aporta valores como un código OTP o un número de pedido.
Bird incluye un catálogo gestionado, registra su contenido en WhatsApp y lo envía desde los números propios de Bird; sus slugs comienzan con bird_. Un espacio de trabajo que haya conectado un número propio también puede crear plantillas en su propia WhatsApp Business Account. La página Templates muestra todas las plantillas que el espacio de trabajo puede enviar y cómo se renderiza cada una.
Explorar plantillas en el panel
Abre Templates en WhatsApp > Templates. Your templates contiene las plantillas que creó este espacio de trabajo; All templates añade el catálogo gestionado por Bird. Busca por nombre o filtra por estado y categoría, y alterna entre la cuadrícula de tarjetas y la vista de lista con el botón junto a los filtros.
En la vista de lista, cada fila muestra los campos que necesitas para elegir y enviar una plantilla:
- Status: indica si la plantilla se puede enviar en general. Las plantillas del catálogo gestionado muestran active; una plantilla propia muestra en qué punto está su aprobación. Revisa la lista de idiomas para confirmar que el idioma necesario está disponible.
- Name: la etiqueta visible, con el slug de la plantilla debajo. Envía con el slug.
- Languages: los idiomas en los que está registrada la plantilla, por ejemplo inglés y neerlandés.
- Category: authentication, utility o marketing. La categoría determina cómo WhatsApp trata el mensaje, desde qué número Bird envía una plantilla gestionada y, junto con el país de destino, el precio.
- WABA: Bird-managed para plantillas del catálogo. Una plantilla propia muestra la WhatsApp Business Account que la contiene y solo envía desde un número de esa misma cuenta.
- Updated: cuándo cambió la plantilla por última vez.
Haz clic en una fila para abrir el detalle de la plantilla.
Qué contiene una plantilla
La vista de detalle renderiza el cuerpo del mensaje, las variables y los botones en una previsualización con estilo WhatsApp.
El detalle también incluye un ejemplo de cURL para POST /v1/whatsapp/messages, usando el host regional y los valores de ejemplo de la plantilla. Reemplaza la clave API, el destinatario y los valores de las variables antes de enviar.
El ejemplo es la forma más rápida de ver la estructura que un envío debe cumplir. A través de la API, el mismo contenido proviene de la versión de la plantilla (Leer el contenido de una plantilla).
Listar plantillas desde la API
GET /v1/whatsapp/templates devuelve un catálogo paginado por cursor. La solicitud requiere acceso de lectura a whatsapp_management. Usa HTTP o un método de solicitud directa de SDK.
type Templates = { data: Array<{ slug: string; status: string }> };
const templates = await bird.request<Templates>({
method: "GET",
path: "/v1/whatsapp/templates",
});templates = client.get("/v1/whatsapp/templates")var out struct {
Data []struct {
Slug string `json:"slug"`
Status string `json:"status"`
} `json:"data"`
}
if err := client.Get(context.Background(), "/v1/whatsapp/templates", &out); err != nil {
log.Fatal(err)
}$templates = $bird->get('/v1/whatsapp/templates');curl https://us1.platform.bird.com/v1/whatsapp/templates \
-H "Authorization: Bearer $BIRD_API_KEY"Cada entrada identifica la plantilla, su categoría y sus idiomas disponibles. Lee la versión activa por separado para obtener el contenido del mensaje.
Ejemplo de código
{
"available_languages": ["en", "es", "pt-BR", "..."],
"category": "authentication",
"default_language": "en",
"description": "One-time passcode",
"id": "wat_01ky4x8e4genzb7way45txfkm1",
"languages": {
"en": { "status": "approved" },
"es": { "status": "approved" },
"pt-BR": { "status": "approved" },
"...": "..."
},
"name": "bird_otp",
"on_missing_language": "fail",
"scope": "system",
"slug": "bird_otp",
"status": "active"
}La respuesta de ejemplo abrevia las listas de idiomas de bird_otp.
Los campos de los que depende un envío:
- slug: el identificador usado en un envío. Los slugs de plantillas gestionadas empiezan con bird_, un prefijo reservado para ellas.
- waba: la WhatsApp Business Account que contiene los idiomas de la plantilla en Meta, y la cuenta a la que debe pertenecer el número del remitente. Ausente en una plantilla gestionada porque Bird administra su cuenta.
- available_languages: idiomas que se pueden enviar. Un idioma en pausa, deshabilitado, archivado o limitado sale de esta lista.
- on_missing_language: qué ocurre cuando el idioma solicitado no está disponible. Las plantillas WhatsApp gestionadas por Bird usan fail, que rechaza el envío en lugar de sustituir por otro idioma.
Estado y estado del idioma
Las plantillas gestionadas por Bird muestran status: active. languages.<tag>.status indica el estado en WhatsApp para un idioma, como approved, paused o disabled.
Una plantilla activa puede tener un idioma no disponible. Usa available_languages para decidir si un idioma se puede enviar.
Leer el contenido de una plantilla
El contenido del mensaje pertenece a un idioma en la versión activa. Lee live_version_id de la plantilla y luego solicita el idioma necesario:
const language = await bird.request({
method: "GET",
path: "/v1/whatsapp/templates/bird_order_confirmation/versions/{version_id}/languages/en",
});language = client.get(
"/v1/whatsapp/templates/bird_order_confirmation/versions/{version_id}/languages/en"
)var language map[string]any
if err := client.Get(context.Background(),
"/v1/whatsapp/templates/bird_order_confirmation/versions/{version_id}/languages/en",
&language); err != nil {
log.Fatal(err)
}$language = $bird->get('/v1/whatsapp/templates/bird_order_confirmation/versions/{version_id}/languages/en');curl https://us1.platform.bird.com/v1/whatsapp/templates/bird_order_confirmation/versions/{version_id}/languages/en \
-H "Authorization: Bearer $BIRD_API_KEY"La referencia de plantilla acepta un slug o un ID wat_. GET …/versions/{version_id}/languages lista los idiomas de la versión sin su contenido.
Ejemplo de código
{
"category": "utility",
"components": [
{
"example_parameters": [
{ "name": "ref", "text": "A1B2C3D4", "type": "text" },
{ "name": "amount", "text": "USD 49.99", "type": "text" }
],
"text": "Your order {{ref}} has been confirmed for a total of {{amount}}. Thanks for shopping with us.",
"type": "body"
}
],
"language": "en",
"status": "approved"
}El components del envío debe coincidir con la plantilla. example_parameters identifica cada marcador de posición. En este ejemplo, los parámetros del cuerpo usan name: "ref" y name: "amount". Una plantilla posicional omite name y toma valores en orden {{n}}. Los botones parametrizados tienen su propio example_parameters.
El category del idioma es la categoría de Meta usada para la tarificación. Puede diferir de la categoría registrada de la plantilla si Meta reclasifica el idioma.
La lista variables de la versión resume cada marcador de posición con su clave, tipo, indicador de obligatoriedad y restricción. Los marcadores con nombre usan sus nombres como claves. Los marcadores posicionales usan su número.
Enviar con una plantilla
Nombra la plantilla en el objeto template del envío y completa sus variables mediante components; consulta Enviar mensajes de WhatsApp para ver el payload completo:
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 +31612345678curl -X POST https://us1.platform.bird.com/v1/whatsapp/messages \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+14155550100",
"template": {
"slug": "bird_otp",
"language": "en",
"components": [
{ "type": "body", "parameters": [{ "type": "text", "text": "481920" }] },
{ "type": "button", "parameters": [{ "type": "text", "text": "481920" }] }
]
}
}'Enviar por categoría
Cada plantilla lleva una de las tres categorías de Meta, y la categoría cambia lo que debes hacer antes de que un envío tenga éxito y lo que cuesta. Crear o copiar una plantilla de autenticación propia requiere un negocio verificado, pero enviar una no: la bird_otp gestionada de Bird reside en la WhatsApp Business Account propia de Bird y se envía sin verificación de tu parte. Las plantillas de marketing siempre se envían desde una WhatsApp Business Account propia, a través de una segunda API de Meta a la que Bird enruta automáticamente. Las plantillas de utilidad tienen los menores prerrequisitos de las tres.
- Plantillas de autenticación: códigos de verificación de un solo uso, el botón de copiar código y la verificación necesaria para crear una
- Plantillas de utilidad: actualizaciones de pedido, recordatorios de cita y avisos de cuenta
- Plantillas de marketing: envíos promocionales, la cuenta de negocio que necesitas y la expectativa de exclusión voluntaria
Siguientes pasos
- Enviar mensajes de WhatsApp: el payload completo de envío en el que encaja el objeto template
- Directrices de plantillas de WhatsApp: las reglas con las que Meta evalúa una plantilla
- Plantillas de autenticación: códigos de verificación de un solo uso y la verificación de negocio necesaria para crear una
- Precios de WhatsApp: cómo la categoría y el destino determinan el precio
Recursos relacionados
Continúa con la documentación, guías y ejemplos de este tema.