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, comolembrete_consulta.category:MARKETING,UTILITYouAUTHENTICATION.language: código de idioma da Meta, comopt_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.headerVariableouheaderMedia: variável de texto do header ou mídia, porurloubase64.buttons[]: parâmetros de botão porindex, a posição no template a partir de 0, comsubTypeurl(o sufixo que substitui o{{1}}),copy_code(couponCode),flow(flowToken,flowActionData),order_detailsoupayment_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.