Como enviar um template pela API oficial do WhatsApp

Resposta curta: o template é identificado pelo nome, e é por isso que nome de template não pode se repetir. Então o envio tem duas etapas. Primeiro você lista os templates da sua conta com GET https://cloud.datafyapi.com.br/templates, para pegar o nome exato, o idioma e o status. Depois você envia pelo mesmo endpoint de qualquer mensagem, POST https://cloud.datafyapi.com.br/v1/{phone_number_id}/messages, com "type": "template" e um objeto template contendo nome, idioma e os componentes que carregam as variáveis. Template sai fora da janela de 24 horas, e cada mensagem entregue é cobrada pela Meta. O caso que mais dá erro é o template com imagem no cabeçalho: a imagem cadastrada na criação é só exemplo, e no envio você precisa mandar uma imagem de novo.

Principais pontos

• Liste antes de enviar. GET /templates devolve nome, idioma, categoria e status de cada modelo, sem precisar do waba_id.
• O envio usa o endpoint de mensagens, com type igual a template. Não existe rota separada para template.
• Template com imagem no cabeçalho exige a imagem no envio. Sem ela, a Meta devolve erro pedindo a imagem.
• Enviar template não abre a janela de 24 horas. Ela abre quando a pessoa responde.
• A Meta cobra por mensagem entregue, pela categoria. Resposta com identificador não é entrega nem cobrança.

Antes: por que o nome importa tanto

No corpo do envio você não passa o identificador numérico do template: você passa o nome. Por isso a Meta não deixa dois templates com o mesmo nome na conta, e por isso o nome não aceita espaço. Se você criou o modelo pelo painel e digitou o nome com acento ou espaço, o erro aparece na criação, não no envio. O passo a passo da criação está aqui.

Também precisa bater o idioma. O mesmo nome pode existir em vários idiomas, e o envio escolhe a variante pelo código que você manda, por exemplo pt_BR.

Passo 1: descobrir os seus identificadores

Se você só tem o token, comece por aqui. É o endpoint que devolve os valores que o resto das chamadas pede:

GET https://cloud.datafyapi.com.br/me
Authorization: Bearer sk_live_xxx

{
  "cliente_id": "uuid-do-cliente",
  "phone_number_id": "106540352242922",
  "waba_id": "366634483210360",
  "business_id": "123456789"
}

Guarde o phone_number_id: ele entra no caminho do envio. O waba_id só é necessário se você for usar as rotas do espelho em vez das simplificadas.

Passo 2: listar os templates

A rota simplificada dispensa o waba_id e é a mais curta para o dia a dia:

GET https://cloud.datafyapi.com.br/templates
Authorization: Bearer sk_live_xxx

{
  "data": [
    {
      "name": "confirmacao_agendamento",
      "status": "APPROVED",
      "category": "UTILITY",
      "language": "pt_BR",
      "id": "4206368849626155"
    }
  ],
  "paging": {}
}

Sem parâmetros, a chamada traz todos os templates da conta, com o status de cada um. Isso é o que você quer na primeira vez, porque é assim que você descobre quais já estão aprovados e quais continuam em análise.

Pelo espelho, dá para filtrar. Útil quando a conta tem dezenas de modelos e você quer conferir um só:

GET https://cloud.datafyapi.com.br/v1/{waba_id}/message_templates?name=entrega_em_andamento&limit=5
Authorization: Bearer sk_live_xxx

Os parâmetros aceitos são fields, name e limit. Tirando os filtros, volta a lista completa.

Como enviar mensagens de templates pela API oficialCanal DATA7 · 8 min · assistir no YouTube

Passo 3: montar o corpo do envio

O endpoint é o mesmo de texto, imagem ou áudio. O que muda é o type e o objeto template:

POST https://cloud.datafyapi.com.br/v1/{phone_number_id}/messages
Authorization: Bearer sk_live_xxx
Content-Type: application/json

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "5511999999999",
  "type": "template",
  "template": {
    "name": "confirmacao_agendamento",
    "language": { "code": "pt_BR" },
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "Israel Henrique" }
        ]
      }
    ]
  }
}

Três coisas a observar:

• components só carrega o que tem variável. Um template com corpo fixo e nenhum parâmetro pode ir sem components.
• A ordem dos parameters é a ordem das variáveis no corpo do template. O primeiro parâmetro preenche a primeira variável, e assim por diante.
• Botões de resposta rápida não entram no envio. Eles fazem parte do modelo aprovado e chegam junto, sem você precisar declarar nada.

O token vai sempre no cabeçalho. Passar ?access_token= na URL, como aparece em exemplos da documentação da Meta, não funciona na Datafy. Como o espelho funciona.

A resposta confirma que a requisição foi aceita e traz o identificador da mensagem. Não confirma entrega.

Passo 4: o template com imagem no cabeçalho

Aqui está o erro que praticamente todo mundo pega na primeira vez, e o motivo é razoável: se o template aprovado já tem uma imagem, parece lógico que o envio não precise de imagem nenhuma. Não é assim. A imagem cadastrada na criação é só exemplo, para a Meta analisar o modelo. No envio, o cabeçalho precisa vir preenchido.

Um assistente de IA erra exatamente nesse ponto, respondendo que o cabeçalho é fixo e dispensa a imagem. Mandando assim, a Meta devolve erro dizendo que é preciso informar a imagem. Com a imagem no corpo, passa:

POST https://cloud.datafyapi.com.br/v1/{phone_number_id}/messages
Authorization: Bearer sk_live_xxx
Content-Type: application/json

{
  "messaging_product": "whatsapp",
  "to": "5511999999999",
  "type": "template",
  "template": {
    "name": "promocao_hamburguer",
    "language": { "code": "pt_BR" },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": { "link": "https://files.datafyapi.com.br/exemplo/hamburguer.png" }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "Israel Henrique" }
        ]
      }
    ]
  }
}

Nas palavras de Israel Henrique, CTO da Datafy: "essa imagem que a gente colocou aqui, ela só é para criar o template. Ela seria um exemplo. Na hora você vai ter que enviar outra."

De onde tirar o link da imagem. A aba de mídias do painel resolve isso sem servidor: você sobe o arquivo e recebe um link pronto para usar no link do cabeçalho. Os arquivos ficam lá por 30 dias, e depois disso é preciso subir de novo. Como enviar mídia pela API.

O tamanho. A imagem usada no cabeçalho precisou ser quadrada, de 500 por 500, tanto na criação do modelo quanto no envio. Vale a ressalva: é comportamento observado no editor e no envio, e não localizamos essa exigência na documentação pública da Meta.

O que acontece depois do envio

A resposta do POST diz que a Meta aceitou a requisição. O que aconteceu de verdade chega pelo webhook de status:

Use o identificador devolvido no envio para casar os eventos com a mensagem. E lembre que uma mensagem pode voltar HTTP 200 e falhar depois: é exatamente o que acontece quando alguém tenta mandar mensagem livre com a janela fechada.

O template não abre a janela de 24 horas

Template é o que permite falar com quem não te mandou mensagem nas últimas 24 horas. O que ele não faz é liberar mensagens livres para aquela pessoa:

Quem renova o prazo é o cliente. Resposta de atendente, de bot ou de automação não aumenta a janela, e cada cliente tem a sua. Na prática, guarde na sua base o horário da última mensagem recebida de cada pessoa e confira esse horário antes de escolher entre mensagem de serviço e template, inclusive quando o envio ficou esperando numa fila.

Quanto custa cada envio

A Meta cobra por mensagem entregue, pela categoria do template e pelo país do destinatário. As três categorias existem porque a finalidade da mensagem é diferente, e é a finalidade que define a categoria: marketing apresenta produto ou campanha, utilidade informa o andamento de algo que o cliente já pediu, sem oferta comercial, e autenticação entrega código de uso único.

E a janela muda a conta em um caso:

Vale a atenção de sempre: a Meta avalia o conteúdo completo do template e pode reclassificar como marketing o que foi cadastrado como utilidade. Quando isso acontece, o custo por mensagem entregue sai de R$ 0,035 para R$ 0,32 sem aviso. Os valores são referência para planejamento, dependem da tabela vigente e da moeda de cobrança, e não têm relação com o plano da Datafy.

Os limites de envio, em duas camadas

Quando o envio deixa de ser um teste e passa a ser uma lista, dois limites diferentes entram em jogo:

As duas camadas valem ao mesmo tempo, e são independentes: respeitar o limite da Datafy não dispensa o da Meta. Existe ainda um limite por par entre a empresa e um mesmo destinatário, e a Meta não publica o valor. Para listas grandes, o caminho é um laço com controle de ritmo, ou a aba Disparos do painel. Como fazer disparo em massa.

Perguntas frequentes

Como descubro o nome exato do template?

Com GET https://cloud.datafyapi.com.br/templates, que devolve nome, idioma, categoria e status de todos os modelos da conta.

Preciso mandar a imagem se o template já tem uma no cabeçalho?

Precisa. A imagem do modelo é só exemplo para a análise da Meta. Sem a imagem no corpo do envio, a resposta é erro pedindo a imagem.

Existe um endpoint separado para template?

Não. É o mesmo POST /v1/{phone_number_id}/messages de qualquer mensagem, com type igual a template.

Posso enviar template para quem nunca falou comigo?

Pode, e é para isso que template existe. Mas a política comercial do WhatsApp exige que a pessoa tenha fornecido o número e dado opt-in, e cada mensagem entregue é cobrada.

Uma IA consegue montar o corpo do envio?

Consegue, porque o formato é o da documentação da Meta. Troque o começo da URL pelo endereço da Datafy, use o seu token no cabeçalho, e confira o caso da imagem no cabeçalho, em que a resposta dela costuma estar errada.

Recebi HTTP 200. A mensagem chegou?

Não necessariamente. O 200 confirma que a requisição foi aceita. A entrega, ou a falha, chega no webhook de status, e é a mensagem entregue que a Meta cobra.

Os botões do template precisam ir no envio?

Botões de resposta rápida e de URL fixa fazem parte do modelo aprovado e vão junto. Só entram em components quando o próprio botão tem parâmetro variável.

Resumo para a sua integração

Faça na ordem: GET /me para pegar o phone_number_id, GET /templates para pegar o nome e o idioma exatos, e o primeiro envio para o seu próprio número, com o template mais simples que você tiver aprovado. Depois disso, teste o template com imagem no cabeçalho, porque é ali que o corpo muda.

No código, guarde o nome e o idioma do template como configuração, nunca escritos direto na chamada em vários lugares: quando um modelo é reprovado e você cria outro com nome novo, é uma linha para trocar. E trate a resposta do envio como recibo de requisição, não de entrega: quem diz o que aconteceu é o webhook de status.

Leia também

• Como criar um template de WhatsApp passo a passo
• Como fazer disparo em massa na API oficial
• Como enviar mídia pela API oficial do WhatsApp
• Como a Datafy API funciona: um espelho da Cloud API