Template com arquivo no cabeçalho

Templates oficiais da Meta podem ter um cabeçalho de documento, imagem ou vídeo. O arquivo não faz parte do template aprovado: ele vai em cada envio, e pode ser diferente para cada destinatário.

É assim que se manda uma fatura em PDF por cliente, um comprovante, um boleto ou uma etiqueta de envio.

• O número precisa ser da API Oficial da Meta (provider: "cloud_api"). Números conectados por QR Code não enviam templates.
• O template precisa estar aprovado (status: "APPROVED") e ter sido criado com cabeçalho de mídia. O cabeçalho é definido na criação do template, no painel — não dá para adicionar um arquivo a um template de texto.
• O arquivo precisa estar numa URL pública. A Meta baixa o endereço pelos servidores dela; URL protegida por login, VPN ou IP liberado não funciona. Use um link assinado de validade longa se o arquivo for sensível.

Os limites de tamanho e de formato são os da Meta, não nossos.

GET /whatsapp/templates devolve os components do template como a Meta os publica. Procure o componente HEADER e leia o format:

curl "https://app.syncro.chat/api/v1/whatsapp/templates?status=APPROVED" \
  -H "X-API-Key: crm_SUA_CHAVE_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 do HEADER	O que mandar
TEXT ou ausente	nada — o cabeçalho é texto fixo
DOCUMENT	header_media_url apontando para o arquivo (PDF, por exemplo)
IMAGE	header_media_url apontando para a imagem
VIDEO	header_media_url apontando para o vídeo

Template com cabeçalho de mídia sem header_media_url é recusado com 422 antes de qualquer envio.

O envio usa o mesmo endpoint de sempre: POST /leads/{id}/send-whatsapp-template, com permissão whatsapp:write. A tabela completa de parâmetros está lá.

Uma fatura diferente por cliente

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

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

Para disparar em lote, repita a chamada por destinatário trocando o header_media_url. É o único caminho que permite um arquivo por contato — o disparo em massa do painel usa a mesma mídia para a campanha inteira.

Sobre o header_media_filename

Sem ele, o contato vê o nome que a Meta conseguir deduzir da URL — que costuma ser o identificador do arquivo. Com ele, vê o nome que você escolher:

Sem header_media_filename	Com
8842.pdf	Fatura-Julho-2026.pdf

Em cabeçalho IMAGE e VIDEO o campo é ignorado: a Meta não exibe nome de arquivo nesses tipos.

A chave é o número do {{N}} no corpo aprovado do template:

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

Uma lista na ordem também é aceita e equivale ao mapa acima:

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

Duas regras da Meta que valem lembrar, porque ela recusa o envio inteiro quando são violadas:

• variável não pode ir vazia;
• variável não pode conter quebra de linha.

Se o template tiver cabeçalho de texto com variável ({{1}} dentro do HEADER), passe esse valor na chave header_1, para não disputar a posição com o corpo:

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

HTTP	Corpo	O que fazer
422	skip_reason: "header_media_required", com header_format	O template exige arquivo no cabeçalho. Mande header_media_url
422	Envio de template requer instancia Cloud API.	O número é QR Code. Use um número da API Oficial
422	Lead sem telefone cadastrado.	O lead precisa ter telefone
502	Provedor retornou erro: … com raw	A Meta recusou. O raw traz o erro original dela

Exemplo do 422 de cabeçalho:

{
  "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"
}

Esse erro vem antes do envio e antes de a conversa ser criada — uma integração em laço pode tentar de novo sem sujar o inbox.

• Não aceita upload do arquivo. Só URL pública; não há multipart/form-data nem base64. O arquivo fica hospedado no seu lado.
• Não envia documento fora de template. POST /leads/{id}/send-whatsapp só aceita type: "text" e type: "image".
• Não cria templates. A criação, com o cabeçalho de mídia e o arquivo de exemplo que a Meta exige na aprovação, é feita no painel.