Pular para o conteúdo
D-APITestar grátis

api oficial · templates

Templates WhatsApp API oficial gerenciados pelo painel do seu SaaS

Deixe o seu cliente criar e disparar templates WhatsApp API oficial sem entrar no WhatsApp Manager: criação, status de revisão, exclusão e envio com variáveis, mídia e botões, tudo por rota REST.

SaaS testa 14 dias com o time técnico ajudando na integração.

conexões na D-API
1.875
de uptime garantido em contrato
99,9%
datacenters no Brasil
4
por ligação de WhatsApp na API não-oficial
R$ 0
  • Ciclo completo por API

    Criar, listar aprovados, listar todos com status de revisão e excluir. O seu editor de templates conversa com a D-API e a D-API com a Meta.

  • Mídia de header sem upload manual

    Para IMAGE, VIDEO ou DOCUMENT, mande a amostra por URL ou base64. A D-API faz o upload na Meta e monta o header_handle.

  • Variáveis e botões no envio

    bodyVariables, headerVariable, headerMedia e buttons[] por índice. O backend monta os components da Graph API para você.

Templates WhatsApp API oficial são as mensagens pré-aprovadas pela Meta que uma empresa usa para iniciar conversa fora da janela de 24 horas. Se o seu SaaS vende lembrete de consulta, aviso de cobrança ou atualização de pedido para clientes na API oficial, o template é o que faz a notificação sair. E se o cliente precisa abrir o WhatsApp Manager para criar cada um, a experiência do seu produto para ali. Na D-API o ciclo inteiro roda por API, então o editor de templates pode morar dentro do seu painel.

O ciclo de vida de um template

Um template nasce com um nome, uma categoria e um idioma, vai para a revisão da Meta e só pode ser enviado depois de APPROVED. A aprovação leva de minutos a horas. Cada etapa tem uma rota, sempre a partir do id da conexão oficial, que aceita tanto o id da conexão quanto o id da sessão (as rotas de detalhe estão em WhatsApp Cloud API):

Etapa Rota
Criar e enviar para revisão POST /api/v1/connections/cloud-api/{id}/templates
Listar só os aprovados, para o envio GET /api/v1/connections/cloud-api/{id}/templates
Listar todos, em qualquer status GET /api/v1/connections/cloud-api/{id}/templates/all
Excluir pelo nome DELETE /api/v1/connections/cloud-api/{id}/templates/{name}
Enviar um aprovado POST /api/v1/messages/send/template

A separação entre as duas listagens ajuda a montar as telas. A de aprovados alimenta o seletor de template na hora de disparar. A de todos, com o id e o status de cada item (APPROVED, PENDING, REJECTED), alimenta a tela de gestão, onde o cliente acompanha o que ainda está em análise.

Criar templates a partir do seu editor

A criação é o ponto em que o custo da mensagem é decidido, porque a categoria define a tarifa da Meta. Os campos principais:

  • name: minúsculas, números e underscore, como lembrete_consulta.
  • category: MARKETING, UTILITY ou AUTHENTICATION.
  • language: código de idioma da Meta, como pt_BR.
  • bodyText: o corpo, com marcadores {{1}}, {{2}} para as variáveis.
  • bodyExample: um valor de exemplo para cada marcador, exigido pela Meta na revisão.
  • footerText: rodapé opcional.

Um template de lembrete para um software de clínicas, com header de imagem e dois botões, fica assim:

curl -X POST https://api.d-api.cloud/api/v1/connections/cloud-api/CONNECTION_ID/templates \
  -H "Authorization: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "lembrete_consulta",
    "category": "UTILITY",
    "language": "pt_BR",
    "headerFormat": "IMAGE",
    "headerMediaUrl": "https://seu-saas.com/assets/clinica-fachada.jpg",
    "bodyText": "Olá {{1}}, sua consulta com {{2}} é amanhã às {{3}}.",
    "bodyExample": ["Ana", "Dra. Paula", "14h"],
    "buttons": [
      { "type": "QUICK_REPLY", "text": "Confirmar" },
      { "type": "URL", "text": "Remarcar", "url": "https://seu-saas.com/r/{{1}}", "urlExample": "https://seu-saas.com/r/42" }
    ]
  }'

A resposta traz em data o id do template e o status inicial, normalmente PENDING.

Header com mídia sem passo extra

Na Graph API, um header de mídia exige subir a amostra antes e usar o header_handle que volta. Na D-API esse passo some: com headerFormat em IMAGE, VIDEO ou DOCUMENT, você informa a amostra em headerMediaUrl ou headerMediaBase64 e o backend faz o upload pela API de Resumable Upload da Meta. Para header de texto, use headerFormat: "TEXT", o padrão, com headerText.

Botões aceitos na criação

O array buttons aceita até 10 itens, e a Meta aplica limites por tipo, como um botão de telefone e até dois de URL:

type Campos
QUICK_REPLY text
URL text, url, e urlExample quando a URL tem {{1}}
PHONE_NUMBER text, phoneNumber
COPY_CODE example
FLOW text, flowId, flowAction (NAVIGATE ou DATA_EXCHANGE), navigateScreen, icon
PAYMENT_REQUEST text, paymentSetting com pixDynamicCode.code

O PAYMENT_REQUEST guarda o código Pix na definição do template. Para SaaS de cobrança, isso permite um template de aviso de vencimento que já leva o botão de pagamento.

Enviar um template aprovado

Com o template aprovado, o envio usa name e language exatamente como vieram da listagem. As variáveis seguem a ordem dos marcadores:

curl -X POST https://api.d-api.cloud/api/v1/messages/send/template \
  -H "Authorization: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "CONNECTION_ID",
    "to": "5511999999999",
    "template": {
      "name": "lembrete_consulta",
      "language": "pt_BR",
      "headerMedia": { "type": "image", "url": "https://seu-saas.com/assets/clinica-fachada.jpg" },
      "bodyVariables": ["Ana", "Dra. Paula", "14h"],
      "buttons": [{ "index": 1, "subType": "url", "text": "42" }]
    }
  }'

Dentro de template, o envio aceita:

  • bodyVariables: valores dos marcadores do corpo.
  • headerVariable ou headerMedia: variável de texto do header ou mídia, por url ou base64.
  • buttons[]: parâmetros de botão por index, a posição no template a partir de 0, com subType url (o sufixo que substitui o {{1}}), copy_code (couponCode), flow (flowToken, flowActionData), order_details ou payment_request (orderDetails, com valor em reais). Resposta rápida não recebe parâmetro.
  • components: escape bruto no formato da Graph API, repassado como está.

Duas respostas de erro valem tratamento no seu código. Mandar components e buttons juntos devolve 400 com TEMPLATE_COMPONENTS_CONFLICT, porque os dois montam a mesma lista. E enviar template por uma conexão não oficial devolve 400 com NOT_CLOUD_API: na não oficial a empresa já conversa com texto livre, e o template é exigência só da Cloud API.

Template da Meta e mensagem com botões CTA

O nome “template” aparece também em POST /api/v1/interactive/send/template, e vale separar os dois para o seu time não confundir. Essa rota envia uma mensagem com botões de URL e de ligação montada na hora, sem aprovação prévia, e funciona nas duas modalidades. Na API oficial ela só vale dentro da janela de 24 horas: o primeiro botão de URL vira botão nativo, e os demais entram no texto como “Título: valor”.

Use o template da Meta para iniciar conversa e a mensagem interativa para responder dentro da janela com botões. O artigo sobre mensagens interativas pela API cobre listas, carrossel e os outros formatos.

Categoria certa, fatura previsível

Como a categoria nasce na criação, o seu editor é o melhor lugar para evitar surpresa na fatura do cliente. A Meta revisa a categoria na aprovação, e um template de utilidade com cupom de desconto tende a ser tratado como marketing. No Brasil, a diferença entre as duas categorias é grande: R$ 0,3217 por mensagem de marketing entregue contra R$ 0,0350 por mensagem de utilidade (fonte: Meta, tabela vigente em 1º de outubro de 2026). Mostrar esse efeito ao lado do seletor de categoria ajuda o cliente a escrever templates com um propósito só. O artigo quanto custa a API oficial do WhatsApp traz a tabela completa.

Por onde começar

Comece pela listagem de todos os templates, que já dá ao cliente uma tela de gestão útil no primeiro dia. Depois adicione a criação com os campos básicos e o envio com bodyVariables, e só então os botões e a mídia de header. Os esquemas completos de cada rota estão na documentação da D-API.

Time D-API. Atualizado em .

Perguntas frequentes

Dá para editar um template aprovado pela API?

Não. A D-API permite listar, criar e excluir templates, sem edição. Para mudar o texto, crie um template com outro nome e, se quiser, exclua o antigo.

Como meu SaaS fica sabendo que um template foi aprovado ou rejeitado?

O status de aprovação chega como message_template_status_update nas conexões com webhookMode meta_passthrough. Em qualquer modo, a rota de listar todos os templates mostra o status atual de cada um.

Criar um template com nome repetido sobrescreve o anterior?

Não. A D-API repassa o erro da Meta, sem idempotência própria. Trate o nome como chave única por WABA no seu editor.

Outro parceiro conectado no mesmo número impede o envio de template?

Não. Na Meta, templates podem ser enviados por qualquer parceiro, sendo dono da conversa ou não, e enviar um template não muda o dono.

A tarifa da Meta depende do template?

Depende da categoria, definida na criação do template e revisada pela Meta na aprovação. A cobrança cai na WABA do seu cliente, e não na conta da D-API.

A gente também é SaaS

SaaS liberado pelo time testa 14 dias grátis, com um grupo de onboarding em que o time técnico da D-API acompanha a integração no seu produto.

Continue por aqui

Liberar seu teste grátis

Responda rapidinho e o time libera seu teste pelo WhatsApp, com o time técnico ajudando na integração.

Seus dados são usados só pra liberar o teste. Sem spam.