Envie Templates Aprovados do WhatsApp Business API (WABA)

Canais WABA (WhatsApp Business API oficial da Meta) só podem iniciar uma conversa fora da janela de 24 horas usando um template de mensagem previamente aprovado pela Meta. Estes três endpoints enviam um template pelo canal WABA conectado ao seu ApiID. Todas as requisições exigem o cabeçalho Authorization: Bearer {BearerToken}.

Os templates precisam ser criados e aprovados previamente no Gerenciador de Negócios da Meta (ou no painel do PanÐá Zap, quando disponível). Estes endpoints apenas disparam um template já aprovado — eles não criam ou editam templates.

Defina validateNumber: false ao enviar para canais WABA. A normalização automática do 9º dígito brasileiro pode fazer o número final não bater com o cadastrado no WhatsApp Business, criando um contato/ticket duplicado.

Estrutura Comum do `templateData`

Os três endpoints abaixo compartilham a mesma estrutura de templateData, que segue o formato da API oficial da Meta (Cloud API) para o objeto de mensagem de template:

{
  "messaging_product": "whatsapp",
  "to": "5515998566622",
  "type": "template",
  "template": {
    "name": "hello_world",
    "language": {
      "code": "en_US"
    }
  }
}

Campo	Tipo	Obrigatório	Descrição
`messaging_product`	string	Sim	Sempre `"whatsapp"`.
`to`	string	Sim	Número do destinatário — deve ser idêntico ao campo `number` da requisição.
`type`	string	Sim	Sempre `"template"`.
`template.name`	string	Sim	Nome exato do template já aprovado pela Meta.
`template.language.code`	string	Sim	Código de idioma do template — por exemplo, `en_US`, `pt_BR`. Deve corresponder ao idioma configurado na aprovação do template.
`template.components`	array	Não	Componentes dinâmicos do template (cabeçalho, corpo, botões) com os parâmetros de substituição — obrigatório apenas quando o template aprovado contém variáveis. Siga o formato de `components` da Cloud API da Meta.

Enviar Template Simples

Envia um template sem substituição de variáveis — ideal para templates estáticos como confirmações e saudações.

POST https://{BaseUrl}/v2/api/external/{ApiID}/template

{
  "number": "5515998566622",
  "isClosed": false,
  "validateNumber": false,
  "templateData": {
    "messaging_product": "whatsapp",
    "to": "5515998566622",
    "type": "template",
    "template": {
      "name": "hello_world",
      "language": { "code": "en_US" }
    }
  }
}

Campo	Tipo	Obrigatório	Descrição
`number`	string	Sim	Número do WhatsApp do destinatário (formato `5511999999999`).
`isClosed`	boolean	Não	Fecha o ticket automaticamente após o envio.
`validateNumber`	boolean	Não	Recomendado `false` para canais WABA — veja o aviso acima.
`templateData`	object	Sim	Objeto de template no formato da Cloud API da Meta, descrito acima.

Enviar Template com Corpo Dinâmico

Variante usada quando o template aprovado contém variáveis no corpo da mensagem (por exemplo, {{1}}, {{2}}). Os valores de substituição vão em templateData.template.components.

POST https://{BaseUrl}/v2/api/external/{ApiID}/templateBody

{
  "number": "5515998566622",
  "isClosed": false,
  "validateNumber": false,
  "templateData": {
    "messaging_product": "whatsapp",
    "to": "5515998566622",
    "type": "template",
    "template": {
      "name": "order_confirmation",
      "language": { "code": "pt_BR" },
      "components": [
        {
          "type": "body",
          "parameters": [
            { "type": "text", "text": "Maria" },
            { "type": "text", "text": "12345" }
          ]
        }
      ]
    }
  }
}

Os mesmos campos de Enviar Template Simples se aplicam; a diferença fica em templateData.template.components, que carrega os parâmetros posicionais usados para preencher as variáveis do corpo aprovado pela Meta.

Enviar Template de Marketing

Variante recomendada para templates da categoria Marketing (promoções, novidades, campanhas). Usa a mesma estrutura de templateData das duas rotas anteriores, incluindo components quando o template tiver variáveis ou botões dinâmicos (por exemplo, um botão de URL com sufixo variável).

POST https://{BaseUrl}/v2/api/external/{ApiID}/templateMarketingBody

{
  "number": "5515998566622",
  "isClosed": false,
  "validateNumber": false,
  "templateData": {
    "messaging_product": "whatsapp",
    "to": "5515998566622",
    "type": "template",
    "template": {
      "name": "hello_world",
      "language": { "code": "en_US" }
    }
  }
}

Use esta rota especificamente para templates categorizados como Marketing no Gerenciador de Negócios da Meta. Ela aplica as regras de janela e custo específicas dessa categoria de template.

Resposta de Sucesso

Os três endpoints retornam o mesmo formato:

{
  "success": true,
  "data": {
    "message": "Message sent successfully",
    "ticketId": 123
  }
}

Campo	Tipo	Descrição
`success`	boolean	`true` quando o template foi aceito para envio pela Meta.
`data.message`	string	Confirmação legível por humanos.
`data.ticketId`	integer	ID do ticket (novo ou reaproveitado) no qual a mensagem de template foi registrada.

Primeiros Passos

Mensagens

Mensagens Interativas

Tickets e Contatos

Campanhas e CRM

Canais e Recursos

Organização e Produtividade

Dados e Relatórios

Administração da Plataforma

Webhooks e Eventos

Envie Templates Aprovados do WhatsApp Business API (WABA)

Estrutura Comum do `templateData`

Enviar Template Simples

Enviar Template com Corpo Dinâmico

Enviar Template de Marketing

Resposta de Sucesso

​Estrutura Comum do templateData

​Enviar Template Simples

​Enviar Template com Corpo Dinâmico

​Enviar Template de Marketing

​Resposta de Sucesso

Estrutura Comum do `templateData`

Enviar Template Simples

Enviar Template com Corpo Dinâmico

Enviar Template de Marketing

Resposta de Sucesso