> ## Documentation Index > Fetch the complete documentation index at: https://docs.synax.app.br/llms.txt > Use this file to discover all available pages before exploring further. # Enviar template de WhatsApp > Dispare um template aprovado da Meta por uma automação externa, com a conversa registrada no Synax. ## 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 `--`. 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 ```bash theme={null} 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 ```json theme={null} { "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`: ```json theme={null} { "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 1. Em "Conteúdo do cabeçalho", escolher **Mídia** → **Imagem** / **Vídeo** / **Documento**. 2. Fazer upload do arquivo que será enviado em todo disparo. 3. **Não usar variável** (`{{1}}`) no header — variável força modo dynamic, que não é suportado nesta v1. 4. Enviar o template para aprovação na Meta. 5. 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 ```bash theme={null} # 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" }' ``` ```bash theme={null} # 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!" }' ``` ```bash theme={null} # 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.