Plantillas de WhatsApp

Los envíos de WhatsApp iniciados por la empresa usan una plantilla aprobada previamente. Una plantilla contiene texto fijo y variables, de modo que cada envío solo aporta valores como un código de OTP o un número de pedido.

Bird ofrece un catálogo gestionado, registra su contenido en WhatsApp y lo envía desde los números propios de Bird; sus slugs empiezan por bird_. Un espacio de trabajo que haya conectado un número propio también puede crear plantillas en su propia cuenta de WhatsApp Business. La página Plantillas aprobadas muestra todas las plantillas que el espacio de trabajo puede enviar y cómo se representa cada una.

Explorar plantillas en el panel

Abre Approved templates en WhatsApp > Approved templates. Your templates contiene las plantillas creadas por 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 cambia entre la cuadrícula de tarjetas y la vista de lista con el selector situado 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 indican active; una plantilla propia indica en qué punto está su aprobación. Revisa la lista de idiomas para confirmar que el idioma que necesitas está disponible.
Name: la etiqueta visible, con el slug de la plantilla debajo. Envía usando el slug.
Languages: los idiomas en los que está registrada la plantilla, como inglés y neerlandés.
Category: authentication, utility o marketing. La categoría determina cómo trata WhatsApp el mensaje, desde qué número de Bird se envía una plantilla gestionada y, junto con el país de destino, el precio.
WABA: Bird-managed para las plantillas del catálogo. Una plantilla propia muestra la cuenta de WhatsApp Business que la contiene y solo se envía desde un número de esa misma cuenta.
Updated: cuándo se modificó 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 muestra el cuerpo del mensaje, las variables y los botones en una vista previa con el estilo de WhatsApp.

El detalle también ofrece un ejemplo de cURL para POST /v1/whatsapp/messages, con el host regional y los valores de ejemplo de la plantilla. Sustituye la clave de 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 debe tener un envío. A través de la API, el mismo contenido procede 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. Para obtener el contenido del mensaje, lee la versión activa por separado.

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 que se usa en un envío. Los slugs de las plantillas gestionadas empiezan por bird_, un prefijo reservado para ellas.
waba: la cuenta de WhatsApp Business que contiene los idiomas de la plantilla en Meta, y la cuenta a la que debe pertenecer el número remitente. No aparece en una plantilla gestionada porque Bird gestiona su cuenta.
available_languages: los idiomas que se pueden enviar. Un idioma en pausa, desactivado, archivado o limitado sale de esta lista.
on_missing_language: qué ocurre cuando el idioma solicitado no está disponible. Las plantillas de WhatsApp gestionadas por Bird usan fail, que rechaza el envío en lugar de sustituirlo por otro idioma.

Estado y estado del idioma

Las plantillas gestionadas por Bird indican status: active. languages.<tag>.status indica el estado que asigna WhatsApp a un idioma, como approved, paused o disabled.

Una plantilla activa puede tener un idioma no disponible. Usa available_languages para saber si un idioma se puede enviar.

Leer el contenido de una plantilla

El contenido del mensaje pertenece a un idioma de la versión activa. Lee live_version_id de la plantilla y, después, solicita el idioma que necesitas:

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 la plantilla acepta un ID slug o wat_. GET …/versions/{version_id}/languages enumera 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"
}

Un envío rellena estos marcadores de posición por su nombre. example_parameters identifica cada uno. En este ejemplo, el parameters del envío recibe las claves ref y amount. En una plantilla posicional, las claves son sus números, como 1, con dos excepciones: el código de una plantilla de autenticación usa code, y el sufijo numerado de un botón url usa button_url. Los botones con parámetros tienen su propio example_parameters.

El category del idioma es la categoría de Meta que se usa para fijar el precio. 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, su tipo, si es obligatorio y su restricción. Los marcadores con nombre usan su nombre como clave. Los marcadores posicionales usan su número, salvo el código de autenticación (code) y el sufijo de un botón url (button_url). El parameters de un envío recibe estas claves.

Enviar con una plantilla

Indica la plantilla en el objeto template del envío y rellena sus variables mediante parameters; consulta Enviar mensajes de WhatsApp para ver la carga útil completa:

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

msg = client.whatsapp.send(
    to="+15551234567",
    template="bird_otp",
    language="en",
    parameters={"code": "123456"},
)
print(msg.id, msg.status)

msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
	To:         "+15551234567",
	Template:   "bird_otp",
	Language:   "en",
	Parameters: map[string]any{"code": "123456"},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)

$message = $bird->whatsapp->send(
    to: '+15551234567',
    template: 'bird_otp',
    language: 'en',
    parameters: ['code' => '123456'],
);
echo $message->getId(), ' ', $message->getStatus();

bird whatsapp send \
  --language en \
  --parameters '{"code":"123456"}' \
  --template bird_otp \
  --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": "+14155550100",
    "template": {
      "slug": "bird_otp",
      "language": "en",
      "parameters": { "code": "481920" }
    }
  }'

Enviar según la categoría

Cada plantilla tiene una de las tres categorías de Meta, y la categoría determina tanto lo que debes hacer para que un envío se complete como lo que cuesta. Para crear o copiar una plantilla de autenticación propia necesitas una empresa verificada, pero para enviarla no: el bird_otp gestionado de Bird está en la WhatsApp Business Account de Bird y se envía sin que tengas que verificarte. 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 dirige el envío automáticamente. Las plantillas de utilidad son las que menos requisitos previos tienen de las tres.

Plantillas de autenticación: códigos de un solo uso, el botón para copiar el código y el requisito de verificación para crear una
Plantillas de utilidad: actualizaciones de pedidos, recordatorios de citas y avisos de cuenta
Plantillas de marketing: envíos promocionales, la cuenta de empresa que necesitas y la expectativa de ofrecer la baja

Próximos pasos

Enviar mensajes de WhatsApp: la carga útil completa del envío en la que se integra el objeto template
Directrices de plantillas de WhatsApp: las reglas con las que Meta revisa una plantilla
Plantillas de autenticación: códigos de verificación de un solo uso y el requisito de verificación de la empresa para crear una
Precios de WhatsApp: cómo la categoría y el destino determinan el precio

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

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

Recursos relacionados