Plantillas

Envía por la API las plantillas aprobadas de tu WhatsApp API (confirmaciones, avisos de cita o de pedido) a cualquier conversación, con envío como texto en los canales que no aceptan plantillas.

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 porQué se envíadelivery_mode
WhatsApp APILa plantilla aprobada, con encabezado, pie y botonestemplate
WhatsApp Web (QR), Instagram, Facebook o chat webSolo el cuerpo de la plantilla como texto normal, con las variables ya reemplazadas. El encabezado, el pie y los botones no se envíantext_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

CampoTipoRequeridoDescripción
template_namestringSíNombre exacto de la plantilla
languagestringNoIdioma (ej. es_MX). Si no lo mandas, se usa la primera plantilla con ese nombre
body_paramsstring[]Si el cuerpo tiene variablesValores de {{1}}, {{2}}... en orden. Tienen que ser exactamente tantos como variables, y ninguno vacío
header_paramstringSi el encabezado lo pideEl 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_paramsstring[]Si algún botón lo pideValores 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_idstringNoUn 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

HTTPCódigoMotivo
400WHATSAPP_API_NOT_CONFIGUREDTu cuenta no tiene WhatsApp API conectada
400WABA_CREDENTIALS_MISSINGTu WhatsApp API perdió sus credenciales: vuelve a conectarlo desde Canales
404TEMPLATE_NOT_FOUNDNo hay una plantilla con ese template_name (y ese language, si lo mandaste)
400TEMPLATE_NOT_APPROVEDLa plantilla existe pero Meta todavía no la aprueba, o la rechazó
400TEMPLATE_PARAMS_MISMATCHFaltan, sobran o vienen vacíos valores de body_params
400TEMPLATE_HEADER_PARAM_REQUIREDEl encabezado tiene una variable y no mandaste header_param
400TEMPLATE_HEADER_MEDIA_REQUIREDEl encabezado es imagen, video o documento y header_param no es una URL http(s)
400TEMPLATE_HEADER_UNSUPPORTEDLas plantillas con encabezado de ubicación todavía no se pueden enviar
400TEMPLATE_BUTTON_PARAMS_MISMATCHFaltan, sobran o vienen vacíos valores de button_params

Ver también Errores y límites para los códigos generales de la API.