Conectando seu software ao WhatsApp

O API Management é o caminho pelo qual outro sistema — seu software de cobrança, sua loja virtual, seu próprio backend — envia mensagens de WhatsApp pelo WizMessage. Aqui você emite uma chave de API para esse sistema, define qual template aprovado do WhatsApp ele pode enviar e o aponta para um webhook, para que as respostas voltem. Este guia percorre todo o caminho e, em seguida, documenta a API REST que seus desenvolvedores vão chamar.

O painel

Onde ficam suas chaves de API

Todas as chaves que você emitiu aparecem aqui, em API Keys. Cada linha mostra o status da chave, seu prefixo público (a única parte da chave que volta a ser exibida depois que você a cria) e quantas chamadas ela fez hoje. "Manage" abre a chave; o botão de alternância a pausa sem excluí-la.

1. ▶ Onde ficam suas chaves de API
2. ▶ Uma chave que ainda não está pronta

Uma chave que ainda não está pronta

Uma chave sem nenhum template mapeado exibe o selo "Needs setup". Ela consegue se autenticar, mas não consegue enviar mensagens de template enquanto você não mapear um — assim, uma integração pela metade fica visível de imediato, em vez de falhar mais tarde, na hora do envio.

Configuração guiada

Passo 1 — O que você está conectando?

"Connect your software" abre um assistente de quatro passos. Comece dando à chave o nome do sistema que vai usá-la e escolha o preset correspondente. Os presets apenas sugerem nomes de campo razoáveis — o de cobrança sugere invoice_number, amount, due_date, customer_name —, eles não restringem o que você pode mapear.

1. ▶ Passo 1 — O que você está conectando?
2. ▶ Passo 2 — Escolha a mensagem
3. ▶ Passo 3 — Para onde vão as respostas?
4. ▶ Passo 4 — Entre no ar

Passo 2 — Escolha a mensagem

Escolha um dos seus templates aprovados do WhatsApp. Os templates ficam na Meta, não aqui — esta lista é buscada em tempo real na sua conta do WhatsApp conectada, e somente templates APROVADOS podem ser enviados. Este passo é opcional: pule-o se a chave só enviar texto simples e mapeie um template mais tarde.

Passo 3 — Para onde vão as respostas?

Quando alguém responde à sua mensagem, ou quando chega um relatório de entrega, enviamos tudo via POST para uma URL que você controla. Deixe isso desativado se o seu sistema apenas envia. Você pode adicionar depois, na aba Webhooks da chave — nada aqui é permanente.

Passo 4 — Entre no ar

É ao pressionar Next no passo anterior que a chave é de fato criada — esta tela é a confirmação. Copie os três valores agora: a chave de API, o segredo da API e o segredo de assinatura do webhook são exibidos uma única vez e não podem ser recuperados depois. Se você perder o segredo, terá de rotacioná-lo, o que significa atualizar todo sistema que o estivesse usando.

Gerenciando uma chave

Visão geral

Ao abrir uma chave, você cai na aba Overview: o que ela tem permissão de fazer, o quanto está sendo usada e os endpoints que pode chamar. Os números de uso vêm do log de requisições, ou seja, refletem o tráfego real.

1. ▶ Visão geral

Uma chave que ainda precisa de configuração

Uma chave sem template mapeado abre na aba Setup — o mesmo assistente, embutido. Repare que as abas são diferentes das da captura anterior: enquanto a chave não tiver ao menos um template, Templates e Webhooks não são oferecidas, porque ainda não há nada sobre o que elas possam atuar.

1. ▶ Uma chave que ainda precisa de configuração

Templates

Cada card é um template que esta chave pode enviar. O texto do corpo é a mensagem tal como foi aprovada na Meta, e os chips abaixo dele são os nomes das variáveis que o seu sistema vai fornecer. "Try it" envia um teste; "Get code" gera uma requisição pronta em oito linguagens.

1. ▶ Templates
2. ▶ Lendo as variáveis — o ponto que merece atenção redobrada

Lendo as variáveis — o ponto que merece atenção redobrada

Veja o card payment_failed_alert. A mensagem dele vai de {{1}} para {{3}} e depois para {{2}} — os placeholders NÃO estão em ordem numérica no texto. Já os chips abaixo são listados em ordem numérica: customer_name preenche {{1}}, renewal_date preenche {{2}}, plan_name preenche {{3}}. Associe seus valores ao NÚMERO, nunca à ordem em que os placeholders por acaso aparecem na frase. É aí que a maioria das pessoas tropeça em templates traduzidos, em que a ordem das palavras muda os placeholders de lugar.

Os três botões de todo template

"Try it" — envie um teste sem escrever código

O botão de aviãozinho de papel abre este template pré-carregado com valores de exemplo, um por nome de variável. É a forma mais rápida de conferir se um mapeamento está certo antes que seus desenvolvedores encostem nele. Repare no botão de alternância: "Simulate Only" é o padrão e nada sai daqui — o servidor devolve o seu payload como recebeu. Vire para "Send Real Message" e uma mensagem real do WhatsApp vai para o número indicado, e é cobrada.

1. ▶ “Try it” — envie um teste sem escrever código
2. ▶ O que um envio simulado devolve
3. ▶ “Get code” — a requisição, já escrita para você
4. ▶ Trocando de linguagem
5. ▶ “Edit” — mude o que o seu sistema envia
6. ▶ Test API — a mesma ferramenta, qualquer endpoint
7. ▶ Webhooks — recebendo as respostas de volta

O que um envio simulado devolve

Pressionar Send Request no modo Simulate Only devolve a requisição como a plataforma a recebeu, com o status HTTP e o tempo de ida e volta. Leia isso como uma conferência de formato, não como um ensaio geral: confirma que o seu JSON foi interpretado e que a chave foi aceita, mas NÃO valida os nomes das suas variáveis contra o mapeamento e nunca entra em contato com a Meta. Um payload que simula sem erros ainda pode ser recusado de verdade. Para comprovar o mapeamento em si, ative Send Real Message e envie para o seu próprio telefone.

"Get code" — a requisição, já escrita para você

O botão de colchetes angulares gera uma requisição funcional para exatamente este template em oito linguagens: cURL, JavaScript, Node.js, Python, PHP, Ruby, Go e C#. Entregue-a a quem estiver escrevendo a integração. As variáveis aparecem como {{placeholders}} com os nomes do seu mapeamento, e as credenciais ficam como YOUR_API_KEY / YOUR_API_SECRET — este diálogo nunca imprime sua chave real, então o trecho pode ser colado em um chamado sem risco.

Trocando de linguagem

Clique em qualquer linguagem no topo e o trecho é reescrito para ela — a mesma chamada, os mesmos cabeçalhos, o cliente HTTP daquela linguagem. Cada um é gerado na primeira vez que você clica, então um indicador de carregamento rápido na primeira troca é normal. Copy leva o trecho como está: ele é completo, imports e tudo, e se esta chave exigir assinaturas, o passo de assinatura já vem incluído.

"Edit" — mude o que o seu sistema envia

O lápis abre o próprio mapeamento. O mock de celular no topo é a mensagem real com os seus nomes atuais substituídos, então você vê o que o cliente vai ler. Abaixo dele, cada variável detectada pode ser renomeada, reordenada, marcada como obrigatória ou receber um tipo — uma data, um valor monetário, uma imagem. Renomear uma variável a renomeia também no payload da sua API, então um sistema que já envia o nome antigo vai começar a falhar: mude os dois juntos.

Test API — a mesma ferramenta, qualquer endpoint

"Test API", no topo da aba, é o "Try it" sem a trava do template: escolha qualquer um dos três endpoints de envio, troque de template no segundo menu suspenso e edite o corpo à vontade. Use-o para conferir as chamadas cruas de /messages/text ou /messages/template, que não têm card próprio porque não estão presas a nenhum mapeamento. Repare que as variáveis deste template ainda se chamam body_1, body_2, body_3 — é assim que um template não mapeado se parece, e é exatamente isso que o "Edit" existe para resolver.

Respostas

Webhooks — recebendo as respostas de volta

Enviar é só metade de uma integração. Aponte um webhook para o seu próprio endpoint HTTPS e o WizMessage fará POST das mensagens recebidas e das atualizações de entrega para ele. O segredo de assinatura é exibido uma única vez, no momento em que é gerado; verifique-o em cada entrega para ter certeza de que a chamada veio mesmo de nós.

Referência da API REST

Tudo o que vem acima configura a chave. Isto aqui é o que seus desenvolvedores de fato chamam. A URL base é /api/v1/external. Todo endpoint exige os cabeçalhos de autenticação abaixo e está sujeito aos limites de uso da chave.

Autenticação

Envie sua chave de API em toda requisição. Se a chave estiver com "Require signature" ativado, você também precisa assinar a requisição — e uma chave com essa opção ativada rejeita de imediato qualquer chamada sem assinatura.

Nota: As assinaturas só são exigidas quando a chave está com require_signature ativado. Se não estiver, a chave de API sozinha já basta para enviar mensagens — e é exatamente por isso que a chave é um segredo, não um identificador. Trate-a como uma senha: ela é exibida uma única vez, e qualquer pessoa que a tenha em mãos pode enviar mensagens aos seus clientes.

const crypto = require('node:crypto')

const body = JSON.stringify({ to: '+919876543210', message: 'Hello' })
const timestamp = Math.floor(Date.now() / 1000).toString()

const secretHash = crypto.createHash('sha256').update(API_SECRET).digest('hex')
const signature = crypto.createHmac('sha256', secretHash)
	.update(timestamp + '.' + body)
	.digest('hex')

await fetch('https://your-host/api/v1/external/messages/text', {
	method: 'POST',
	headers: {
		'Content-Type': 'application/json',
		'X-API-Key': API_KEY,
		'X-Timestamp': timestamp,
		'X-API-Signature': signature,
	},
	body,
})

Endpoints

Enviando um template mapeado

Este é o payload que faz par com a aba Templates. Você envia as variáveis por NOME — os nomes exibidos como chips no card do template — e a plataforma monta os components da Meta para você. É exatamente esse o objetivo de mapear um template: seu sistema de cobrança não precisa saber nada sobre o formato de components da Meta.

POST /api/v1/external/messages/template/send

{
	"to": "+919876543210",
	"template_name": "payment_failed_alert",
	"language": "en",
	"variables": {
		"customer_name": "Priya Sharma",
		"renewal_date": "12 Aug 2026",
		"plan_name": "Wiz Pro"
	},
	"reference": "invoice-2026-0817"
}

Nota: Os nomes das variáveis precisam corresponder exatamente ao mapeamento — um nome não reconhecido é ignorado, e a falta de um nome obrigatório é rejeitada com um 400. O campo reference é seu: ele é devolvido nos webhooks para que você possa associar um relatório de entrega a um registro no seu próprio sistema.

Limites de uso

Cada chave tem seus próprios limites, visíveis na aba Overview — 60 requisições/minuto e 1.000 mensagens/dia por padrão. As respostas incluem o saldo restante, então reduza o ritmo quando ele estiver baixo, em vez de insistir com novas tentativas até bater na parede.