Las plantillas son los mensajes aprobados por Meta que te dejan escribirle a un cliente de WhatsApp fuera de la ventana de 24 horas: confirmaciones, recordatorios, "tu pedido va en camino". Se crean en el panel, en Plantillas (ver Plantillas de WhatsApp); por la API las listas y las envías.
Necesitas WhatsApp API:
Las plantillas viven en tu cuenta de WhatsApp API (la conexión oficial de Meta, ver WhatsApp API). Si solo tienes WhatsApp Web (QR), GET /api/v1/templates devuelve una lista vacía y enviar una plantilla responde 400 con WHATSAPP_API_NOT_CONFIGURED. Para esas cuentas usa el envío de texto normal.
Un mismo endpoint sirve para cualquier conversación, sin importar su canal:
| La conversación sale por | Qué se envía | delivery_mode |
|---|---|---|
| WhatsApp API | La plantilla aprobada, con encabezado, pie y botones | template |
| WhatsApp Web (QR), Instagram, Facebook o chat web | Solo el cuerpo de la plantilla como texto normal, con las variables ya reemplazadas. El encabezado, el pie y los botones no se envían | text_fallback |
Listar plantillas aprobadas
GET /api/v1/templates
Scope: messages:send_template
Devuelve las plantillas con estado APPROVED de tu cuenta de WhatsApp API (la principal, si tienes más de una).
curl https://api.yolani.co/api/v1/templates \
-H "Authorization: Bearer yol_TU_TOKEN"
Respuesta:
{
"success": true,
"data": [
{
"name": "confirmacion_cita",
"language": "es_MX",
"category": "UTILITY",
"body": "Hola {{1}}, tu cita para {{2}} quedó confirmada el {{3}}.",
"header_format": null,
"header_text": null,
"footer": "Estética Aurora",
"buttons": [
{
"type": "URL",
"text": "Ver mi cita",
"url": "https://esteticaaurora.mx/citas/{{1}}",
"phoneNumber": null,
"urlHasVariable": true,
"example": "https://esteticaaurora.mx/citas/2291"
}
]
}
]
}
header_format dice qué lleva el encabezado (por ejemplo TEXT, IMAGE, VIDEO o DOCUMENT), o viene null si no tiene. Ojo: los campos de cada botón van en camelCase (phoneNumber, urlHasVariable), a diferencia del resto de la API. Los botones con urlHasVariable: true y los de tipo COPY_CODE (código de cupón) piden su valor en button_params al enviar.
Enviar una plantilla
POST /api/v1/conversations/:id/messages/template
Scope: messages:send_template
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
template_name | string | Sí | Nombre exacto de la plantilla |
language | string | No | Idioma (ej. es_MX). Si no lo mandas, se usa la primera plantilla con ese nombre |
body_params | string[] | Si el cuerpo tiene variables | Valores de {{1}}, {{2}}... en orden. Tienen que ser exactamente tantos como variables, y ninguno vacío |
header_param | string | Si el encabezado lo pide | El valor de la variable del encabezado de texto, o la URL pública del archivo si el encabezado es imagen, video o documento. Solo con delivery_mode: "template" |
button_params | string[] | Si algún botón lo pide | Valores de los botones con URL variable o código de cupón, en el orden en que aparecen. Solo con delivery_mode: "template" |
client_request_id | string | No | Un id tuyo para no duplicar el envío si reintentas. Solo aplica cuando se envía como texto |
curl -X POST https://api.yolani.co/api/v1/conversations/913/messages/template \
-H "Authorization: Bearer yol_TU_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"template_name": "confirmacion_cita",
"language": "es_MX",
"body_params": ["Lucía", "tinte y corte", "sábado 25 a las 11:00"],
"button_params": ["2291"]
}'
Respuesta (201), enviada como plantilla:
{
"success": true,
"data": {
"message_id": 15300,
"conversation_id": 913,
"channel": "whatsapp",
"delivery_mode": "template",
"status": "sent"
}
}
Respuesta cuando la conversación es de un canal sin plantillas (se mandó como texto):
{
"success": true,
"data": {
"message_id": 15301,
"conversation_id": 927,
"channel": "instagram",
"delivery_mode": "text_fallback",
"status": "sent"
}
}
Ejemplo: confirmar una cita
async function confirmarCita(conversationId, nombre, servicio, fecha, idCita) {
const response = await fetch(
`https://api.yolani.co/api/v1/conversations/${conversationId}/messages/template`,
{
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.YOLANI_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
template_name: 'confirmacion_cita',
language: 'es_MX',
body_params: [nombre, servicio, fecha],
button_params: [String(idCita)],
client_request_id: `cita-${idCita}-confirmacion`,
}),
},
);
return response.json();
}
import os
import requests
def confirmar_cita(conversation_id, nombre, servicio, fecha, id_cita):
response = requests.post(
f"https://api.yolani.co/api/v1/conversations/{conversation_id}/messages/template",
headers={"Authorization": f"Bearer {os.environ['YOLANI_API_KEY']}"},
json={
"template_name": "confirmacion_cita",
"language": "es_MX",
"body_params": [nombre, servicio, fecha],
"button_params": [str(id_cita)],
},
timeout=30,
)
return response.json()
Errores propios de plantillas
| HTTP | Código | Motivo |
|---|---|---|
| 400 | WHATSAPP_API_NOT_CONFIGURED | Tu cuenta no tiene WhatsApp API conectada |
| 400 | WABA_CREDENTIALS_MISSING | Tu WhatsApp API perdió sus credenciales: vuelve a conectarlo desde Canales |
| 404 | TEMPLATE_NOT_FOUND | No hay una plantilla con ese template_name (y ese language, si lo mandaste) |
| 400 | TEMPLATE_NOT_APPROVED | La plantilla existe pero Meta todavía no la aprueba, o la rechazó |
| 400 | TEMPLATE_PARAMS_MISMATCH | Faltan, sobran o vienen vacíos valores de body_params |
| 400 | TEMPLATE_HEADER_PARAM_REQUIRED | El encabezado tiene una variable y no mandaste header_param |
| 400 | TEMPLATE_HEADER_MEDIA_REQUIRED | El encabezado es imagen, video o documento y header_param no es una URL http(s) |
| 400 | TEMPLATE_HEADER_UNSUPPORTED | Las plantillas con encabezado de ubicación todavía no se pueden enviar |
| 400 | TEMPLATE_BUTTON_PARAMS_MISMATCH | Faltan, sobran o vienen vacíos valores de button_params |
Ver también Errores y límites para los códigos generales de la API.