Template con archivo en el encabezado

Los templates oficiales de Meta pueden tener un encabezado de documento, imagen o video. El archivo no forma parte del template aprobado: va en cada envío y puede ser distinto para cada destinatario.

Así se manda una factura en PDF por cliente, un comprobante, un recibo o una etiqueta de envío.

• El número debe ser de la API Oficial de Meta (provider: "cloud_api"). Los números conectados por Código QR no envían templates.
• El template debe estar aprobado (status: "APPROVED") y haber sido creado con encabezado de medios. El encabezado se define en la creación del template, en el panel — no se puede agregar un archivo a un template de texto.
• El archivo debe estar en una URL pública. Meta lo descarga desde sus servidores; una URL protegida por login, VPN o lista de IPs no funciona. Usa un enlace firmado de larga validez si el archivo es sensible.

Los límites de tamaño y formato son los de Meta, no nuestros.

GET /whatsapp/templates devuelve los components del template tal como Meta los publica. Busca el componente HEADER y lee el format:

curl "https://app.syncro.chat/api/v1/whatsapp/templates?status=APPROVED" \
  -H "X-API-Key: crm_TU_CLAVE_AQUI"

{
  "success": true,
  "data": [
    {
      "id": 10,
      "name": "fatura_mensal",
      "language": "pt_BR",
      "category": "UTILITY",
      "status": "APPROVED",
      "variables": ["1", "2"],
      "components": [
        { "type": "HEADER", "format": "DOCUMENT" },
        { "type": "BODY", "text": "Olá {{1}}, sua fatura vence em {{2}}." }
      ]
    }
  ]
}

format del HEADER	Qué mandar
TEXT o ausente	nada — el encabezado es texto fijo
DOCUMENT	header_media_url apuntando al archivo (un PDF, por ejemplo)
IMAGE	header_media_url apuntando a la imagen
VIDEO	header_media_url apuntando al video

Un template con encabezado de medios sin header_media_url se rechaza con 422 antes de cualquier envío.

El envío usa el endpoint de siempre: POST /leads/{id}/send-whatsapp-template, con el permiso whatsapp:write. La tabla completa de parámetros está allí.

Una factura distinta por cliente

curl -X POST https://app.syncro.chat/api/v1/leads/123/send-whatsapp-template \
  -H "X-API-Key: crm_TU_CLAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": 10,
    "variables": { "1": "João", "2": "30/07" },
    "header_media_url": "https://tudominio.com/facturas/8842.pdf",
    "header_media_filename": "Factura-Julio-2026.pdf"
  }'

{
  "success": true,
  "conversation_id": 99,
  "message_id": 457,
  "provider_msg_id": "wamid.xyz456",
  "template_name": "fatura_mensal"
}

Para disparar en lote, repite la llamada por destinatario cambiando el header_media_url. Es el único camino que permite un archivo por contacto — el disparo masivo del panel usa el mismo medio para toda la campaña.

Sobre el header_media_filename

Sin él, el contacto ve el nombre que Meta logre deducir de la URL — que suele ser el identificador del archivo. Con él, ve el nombre que elijas:

Sin header_media_filename	Con
8842.pdf	Factura-Julio-2026.pdf

En encabezados IMAGE y VIDEO el campo se ignora: Meta no muestra nombre de archivo en esos tipos.

La clave es el número del {{N}} en el cuerpo aprobado del template:

{ "variables": { "1": "João", "2": "30/07" } }

Una lista en orden también se acepta y equivale al mapa de arriba:

{ "variables": ["João", "30/07"] }

Dos reglas de Meta que vale recordar, porque rechaza el envío entero cuando se violan:

• una variable no puede ir vacía;
• una variable no puede contener salto de línea.

Si el template tiene encabezado de texto con variable ({{1}} dentro del HEADER), pasa ese valor en la clave header_1, para que no dispute la posición con el cuerpo:

{ "variables": { "header_1": "Julho", "1": "João", "2": "30/07" } }

HTTP	Cuerpo	Qué hacer
422	skip_reason: "header_media_required", con header_format	El template exige archivo en el encabezado. Manda header_media_url
422	Envio de template requer instancia Cloud API.	El número es Código QR. Usa un número de la API Oficial
422	Lead sem telefone cadastrado.	El lead debe tener teléfono
502	Provedor retornou erro: … con raw	Meta lo rechazó. El raw trae su error original

Ejemplo del 422 de encabezado:

{
  "success": false,
  "message": "O template \"fatura_mensal\" tem cabecalho de document e exige `header_media_url` com a URL publica do arquivo.",
  "skip_reason": "header_media_required",
  "header_format": "DOCUMENT"
}

Este error llega antes del envío y antes de que se cree la conversación — una integración en bucle puede reintentar sin ensuciar el inbox.

• No acepta subida del archivo. Solo URL pública; no hay multipart/form-data ni base64. El archivo queda alojado de tu lado.
• No envía documentos fuera de template. POST /leads/{id}/send-whatsapp solo acepta type: "text" y type: "image".
• No crea templates. La creación, con el encabezado de medios y el archivo de ejemplo que Meta exige en la aprobación, se hace en el panel.