Enviar template de WhatsApp

Visão geral

O endpoint send-external-template permite que uma automação externa (n8n, Zapier, etc.) dispare um template aprovado do WhatsApp pela API oficial da Meta. A diferença para chamar a Meta diretamente: o Synax registra a conversa e a mensagem, de modo que, se o cliente responder, o agente de IA atende já com o contexto da mensagem enviada.

Autenticação

Use uma chave de API com o escopo Mensagens (messaging). Crie ou edite a chave em Configurações → API e ative o toggle “Mensagens”.

Authorization: Bearer sk_live_sua_chave

Requisição

POST https://api.synax.app.br/functions/v1/send-external-template
Content-Type: application/json

Campo	Tipo	Obrigatório	Descrição
`phone`	string	sim	Telefone do destinatário em E.164 (`+5561999999999`)
`template_name`	string	sim	Nome do template aprovado na Meta
`language_code`	string	sim	Código de idioma do template (`pt_BR`)
`display_text`	string	sim	Texto renderizado pelo caller, gravado em `chat_messages.content` (o agente lê esse texto como contexto). Máx. 4096 caracteres. Não é o resultado do template — é o que o caller quer que apareça no histórico
`body_variables`	string[]	não	Valores das variáveis `{{1}}`, `{{2}}`… do corpo do template. Máx. 30 itens, máx. 1024 caracteres por item
`header_variables`	string[]	não	Valores das variáveis do cabeçalho. Máx. 30 itens, máx. 1024 caracteres por item
`phone_number_id`	string	não	Conta Meta a usar. Omita se a empresa tiver exatamente uma conta Meta conectada. Obrigatório quando há mais de uma — caso contrário a resposta é 422
`contact_name`	string	não	Nome usado só se o contato ainda não existir no CRM. Máx. 255 caracteres
`idempotency_key`	string	não	Evita envio duplicado em retries. Recomendamos `<finalidade>-<contato>-<data>`. Máx. 200 caracteres
`template_header_type`	string	não	Declara o tipo do header de mídia static do template aprovado: `"image"`, `"video"` ou `"document"`. Não envia mídia — a mídia deve estar anexada ao template aprovado na Meta (modo static media header). Quando presente, `chat_messages.type` recebe o valor declarado ao invés de `"text"`. Ver seção “Templates com header de mídia”

Exemplo

curl -X POST "https://api.synax.app.br/functions/v1/send-external-template" \
  -H "Authorization: Bearer sk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+5561999999999",
    "template_name": "feliz_aniversario",
    "language_code": "pt_BR",
    "body_variables": ["João"],
    "display_text": "Feliz aniversário, João! 🎉",
    "idempotency_key": "birthday-2026-05-19-joao"
  }'

Resposta

{
  "success": true,
  "conversation_id": "uuid",
  "message_id": "uuid",
  "whatsapp_message_id": "wamid....",
  "created_conversation": true,
  "idempotent_hit": false
}

Resposta em retry idempotente

Quando o caller envia o mesmo idempotency_key da Tabela 1 em um retry, o Synax detecta a duplicata e devolve a referência da mensagem anterior sem reenviar para a Meta. Note que a resposta tem um shape diferente — whatsapp_message_id e created_conversation não aparecem; em compensação, ganha um campo status:

{
  "success": true,
  "status": "sent",
  "conversation_id": "uuid",
  "message_id": "uuid",
  "idempotent_hit": true
}

success: true + status: "sent" — o envio original foi entregue à Meta.
success: false + status: "pending" — o envio original ainda está em andamento (corrida com a primeira chamada). Considere retentar com backoff curto.
success: false + status: "failed" — o envio original falhou. Trate como erro permanente.

Códigos de status

HTTP	Significado
200	Enviado com sucesso (`success: true`) ou bloqueado por opt-out (`success: false, reason: "do_not_contact"`). Sempre inspecione o campo `success` no body — não confie só no status HTTP
401	Chave de API ausente ou inválida
403	A chave não tem o escopo `messaging`
404	A empresa não tem conta Meta conectada
405	Método HTTP não suportado — só `POST` é aceito
422 (payload)	Algum campo é inválido (telefone fora do formato E.164, template_name ausente, body_variables com mais de 30 itens, etc.) — não retentar
422 (multi-account)	A empresa tem mais de uma conta Meta conectada — passe `phone_number_id` explicitamente
422 (template)	A Meta rejeitou o template (não aprovado, idioma errado, parâmetros inválidos) — não retentar
500	Erro interno do Synax. Investigar nos logs internos antes de retentar
502	Meta temporariamente indisponível — pode retentar com backoff

Templates com header de mídia

O WhatsApp distingue dois modos de header de mídia em templates:

Modo	Como funciona
Static media header	Mídia (imagem, vídeo ou PDF) é anexada uma única vez na criação do template no Meta Business Manager. Toda mensagem disparada com esse template envia a mesma mídia. No payload do disparo, basta declarar `template_header_type` — o Synax não envia mídia à Meta, ela usa a anexada na aprovação.
Dynamic media header	Cada disparo carrega uma mídia diferente (ex.: foto personalizada por cliente). Não é suportado nesta versão da API. Se você precisar disso, abra um chamado.

Como configurar o template no Meta Business Manager

Em “Conteúdo do cabeçalho”, escolher Mídia → Imagem / Vídeo / Documento.
Fazer upload do arquivo que será enviado em todo disparo.
Não usar variável ({{1}}) no header — variável força modo dynamic, que não é suportado nesta v1.
Enviar o template para aprovação na Meta.
Após aprovado, disparar pela API declarando template_header_type correspondente ao tipo escolhido. Não passar header_variables — esses campos são para headers de texto variável e conflitam com header de mídia.

Limites da Meta (informativos)

Você não precisa pré-validar tamanho/formato no caller — a Meta rejeita no envio se o template aprovado ficar fora dos limites:

Imagem: até 5 MB (.jpg, .png).
Vídeo: até 16 MB (.mp4 H.264 + AAC).
Documento: até 100 MB (.pdf).

Exemplos por tipo de mídia

# Imagem (aniversário com foto padrão)
curl -X POST "https://api.synax.app.br/functions/v1/send-external-template" \
  -H "Authorization: Bearer sk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+5561999999999",
    "template_name": "feliz_aniversario_imagem",
    "language_code": "pt_BR",
    "template_header_type": "image",
    "body_variables": ["João"],
    "display_text": "Feliz aniversário, João! 🎉",
    "idempotency_key": "birthday-2026-05-20-joao"
  }'

# Vídeo (campanha de fim de ano)
curl -X POST "https://api.synax.app.br/functions/v1/send-external-template" \
  -H "Authorization: Bearer sk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+5561999999999",
    "template_name": "campanha_fimano_video",
    "language_code": "pt_BR",
    "template_header_type": "video",
    "display_text": "Veja a mensagem especial da nossa equipe!"
  }'

# Documento (carta padronizada em PDF)
curl -X POST "https://api.synax.app.br/functions/v1/send-external-template" \
  -H "Authorization: Bearer sk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+5561999999999",
    "template_name": "carta_boas_vindas_pdf",
    "language_code": "pt_BR",
    "template_header_type": "document",
    "body_variables": ["Maria"],
    "display_text": "Olá Maria, segue a carta de boas-vindas em anexo."
  }'

Visualização no chat: mensagens disparadas com template_header_type são registradas em chat_messages com type correspondente (image/video/document), mas sem prévia visual — a mídia vive dentro do template aprovado da Meta, não no Storage do Synax. O atendente vê o display_text no histórico; a mídia em si só é visível no WhatsApp do destinatário.

Janela de 24 horas

A API oficial do WhatsApp só permite mensagens iniciadas pelo negócio via templates aprovados. Aprove o template no Meta Business Manager antes de usá-lo aqui. Quando o cliente responde, abre-se uma janela de 24h em que o agente responde normalmente.

​Visão geral

​Autenticação

​Requisição

​Exemplo

​Resposta

​Resposta em retry idempotente

​Códigos de status

​Templates com header de mídia

​Como configurar o template no Meta Business Manager

​Limites da Meta (informativos)

​Exemplos por tipo de mídia

​Janela de 24 horas