Início rápido
Da conta criada até a primeira mensagem enviada e o primeiro evento recebido no seu servidor, em cinco passos.
1Crie uma chave de API
No painel, abra Chaves de API, escolha o projeto e crie uma chave com as permissões de que o seu sistema precisa. Para este guia: Ler conexões (connections:read), Gerenciar conexões (connections:write, para ver o QR code), Enviar mensagens (messages:send) e Configurar webhooks (webhooks:write). A chave (wag_live_…) aparece uma única vez: guarde-a num cofre de segredos, nunca no código.
Envie a chave em toda requisição, como Authorization: Bearer wag_live_… ou como X-Api-Key: wag_live_…. Confira com GET /me, que responde a organização, os escopos e os projetos que a chave alcança:
curl -s https://api.apiwpp.com/me -H "Authorization: Bearer $API_KEY"{
"kind": "apiKey",
"user": null,
"organization": { "id": "2d5e8a1b-4c7f-4e9a-8b3d-6f0a2c4e8b1d", "name": "Clínica Sorriso", "slug": "clinica-sorriso" },
"role": null,
"scopes": ["connections:read", "connections:write", "messages:send", "webhooks:write"],
"tenantIds": ["3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61"],
"apiKey": { "id": "7c1e9a2b-5d3f-4a6e-8b0c-1d2e3f4a5b6c", "expiresAt": null }
}Uma resposta 401 quer dizer que a chave está ausente, errada, revogada ou expirada; uma 403, que falta um escopo (a mensagem diz qual). Os detalhes estão em Autenticação.
2Pareie o número
Crie a conexão no projeto; a resposta traz o connectionId, o $CONNECTION_ID dos próximos exemplos. Cada conexão ocupa um dos números que a sua organização contratou até ser apagada: além deles, a resposta é 402 com code: number_limit_reached. Depois, consulte o QR code da conexão.
curl -s -X POST https://api.apiwpp.com/connections \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"tenantId": "'$TENANT_ID'"}'
curl -s https://api.apiwpp.com/connections/$CONNECTION_ID/qr \
-H "Authorization: Bearer $API_KEY"{ "qr": "2@k8Jd0Qf3mX1pT7vZ9sLr4eYw6nHc2bGa,…", "status": "connecting" }Enquanto o status for connecting, o qr traz o conteúdo do QR code: mostre-o como imagem e escaneie no celular, em WhatsApp › Aparelhos conectados › Conectar um aparelho. Se preferir a imagem pronta, GET /tenants/{id}/connections/{connId}/qr devolve o mesmo QR code como data URL PNG, no campo qrCode. Quando o status passar a open, o número está pronto.
Escanear o QR code conecta um número à conexão, então só uma chave com connections:write recebe o qr; com só connections:read, ele vem null, e o status continua visível.
3Assine os webhooks
Defina um segredo de assinatura para o projeto. A partir daí, toda entrega de webhook traz os cabeçalhos X-Sales-Timestamp e X-Sales-Signature, uma assinatura HMAC-SHA256 que o seu servidor confere antes de confiar no evento. Gere o segredo e guarde-o no cofre do servidor que recebe os webhooks (por exemplo, como WHATSAPP_WEBHOOK_SECRET) antes de enviá-lo, porque a API nunca o devolve.
WEBHOOK_SECRET=$(openssl rand -hex 32)
echo "$WEBHOOK_SECRET"
curl -s -X PATCH https://api.apiwpp.com/tenants/$TENANT_ID \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"webhookSecret": "'$WEBHOOK_SECRET'"}'A resposta é o projeto, com "hasWebhookSecret": true e nunca o segredo. Se o valor se perder, defina um novo do mesmo jeito. Veja a referência de PATCH /tenants/{id} para o que mais a sua chave pode mudar no projeto.
Antes do primeiro evento real, teste o endpoint: POST /tenants/webhook-test envia a ele um evento ping assinado, com os mesmos cabeçalhos e o mesmo limite de 10 segundos das entregas reais, e não salva nada. Com o tenantId e o webhookBaseUrl salvo do projeto, o ping usa o token, os cabeçalhos e o segredo que o projeto já tem (o exemplo usa jq para ler o endereço):
WEBHOOK_URL=$(curl -s https://api.apiwpp.com/tenants/$TENANT_ID \
-H "Authorization: Bearer $API_KEY" | jq -r .webhookBaseUrl)
curl -s -X POST https://api.apiwpp.com/tenants/webhook-test \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"webhookBaseUrl": "'$WEBHOOK_URL'", "tenantId": "'$TENANT_ID'"}'{ "ok": true, "status": 200, "latencyMs": 184, "error": null }O status é o que o seu servidor respondeu (null quando nenhuma resposta voltou) e o error vale "timeout" quando os 10 segundos passaram.
4Envie uma mensagem
A conexão precisa estar open; antes disso, a resposta é 400. A resposta 202 quer dizer que a mensagem entrou na fila do número; o envio acontece em seguida, no ritmo que protege o número (veja Limites de envio). O clientRef é o seu identificador do envio: repetir a requisição com ele não duplica a mensagem (veja Idempotência).
curl -s -X POST https://api.apiwpp.com/connections/$CONNECTION_ID/send \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"to": "5511988887777", "message": "Olá! Sua consulta está confirmada.", "clientRef": "pedido-1234"}'{ "jobId": "c2a4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f", "scheduledAt": 1790251205000, "position": 1 }O to é o telefone com o código do país (só os dígitos contam), o scheduledAt é o horário previsto do envio em milissegundos unix e o position é o lugar na fila. Repetir o mesmo clientRef na mesma conexão, dentro de 7 dias, responde 200 com o job original e "duplicate": true, sem enfileirar de novo. O mesmo envio em Node.js 18 ou mais novo (fetch nativo; salve como enviar.mjs):
const response = await fetch(`https://api.apiwpp.com/connections/${process.env.CONNECTION_ID}/send`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
to: '5511988887777',
message: 'Olá! Sua consulta está confirmada.',
clientRef: 'pedido-1234',
}),
})
const body = await response.json()
if (!response.ok) {
// Todo erro traz { error }; decida pelo status HTTP, não pelo texto
throw new Error(`Envio recusado (${response.status}): ${body.error}`)
}
// 202: entrou na fila agora; 200 com duplicate: true: esse clientRef já estava na fila
console.log(body.jobId, body.duplicate === true ? 'repetido' : 'novo')5Receba os eventos
A apiwpp envia um POST ao webhookBaseUrl do projeto para cada evento: mensagens recebidas (message.incoming), o status das mensagens enviadas (message.delivery), mudanças da conexão (connection.status) e os demais. Todos chegam no mesmo envelope; data depende do type. Esta é uma mensagem recebida (sem o campo raw, a mensagem original do WhatsApp):
{
"type": "message.incoming",
"connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
"tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
"externalId": "shop-42",
"timestamp": "2026-09-25T12:00:00.000Z",
"data": {
"from": "[email protected]",
"to": "5511900000001:[email protected]",
"jid": "[email protected]",
"phone": "+5511988887777",
"resolvedPhone": "5511988887777",
"body": "Olá! Tem horário amanhã às 10h?",
"timestamp": 1790337600
}
}E esta é a mensagem do passo 4 entregue no celular do destinatário. O clientRef vem junto, então você sabe de qual envio se trata; o status passa por sent, delivered e read, ou vira failed:
{
"type": "message.delivery",
"connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
"tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
"externalId": "shop-42",
"timestamp": "2026-09-24T12:00:07.000Z",
"data": {
"messageId": "3EB0C767D26A1D8A3F52",
"status": "delivered",
"recipient": "5511988887777",
"clientRef": "pedido-1234",
"jid": "[email protected]",
"phone": "+5511988887777"
}
}Verifique a assinatura, responda 2xx em até 10 segundos e processe o evento depois. A entrega é feita pelo menos uma vez: o mesmo evento pode chegar de novo, então aplique cada um de forma idempotente, e ignore os tipos que você não conhece (o ping do passo 3 inclusive). Um receptor mínimo em Node.js com Express:
import { createHmac, timingSafeEqual } from 'node:crypto'
import express from 'express'
const SECRET = process.env.WHATSAPP_WEBHOOK_SECRET
if (!SECRET) throw new Error('WHATSAPP_WEBHOOK_SECRET não está definido')
function isSigned(rawBody, timestamp, signature) {
if (!/^\d+$/.test(timestamp ?? '') || !signature) return false
// Rejeite entregas com mais de 300 segundos de diferença do seu relógio
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false
const mac = createHmac('sha256', SECRET).update(`${timestamp}.`).update(rawBody).digest('hex')
const expected = Buffer.from(`sha256=${mac}`)
const received = Buffer.from(signature)
return expected.length === received.length && timingSafeEqual(expected, received)
}
const app = express()
// express.raw: a assinatura é calculada sobre os bytes do corpo, nunca sobre o JSON já convertido
app.post('/whatsapp/events', express.raw({ type: 'application/json' }), (req, res) => {
if (!isSigned(req.body, req.get('X-Sales-Timestamp'), req.get('X-Sales-Signature'))) {
return res.sendStatus(401)
}
const event = JSON.parse(req.body.toString('utf8'))
res.sendStatus(204) // responda logo e processe fora da requisição
setImmediate(() => handle(event))
})
function handle(event) {
switch (event.type) {
case 'message.incoming':
console.log('recebida de', event.data.phone ?? event.data.jid, event.data.body)
break
case 'message.delivery':
console.log(event.data.clientRef, event.data.status)
break
default:
break // tipos novos ou o ping: ignore
}
}
app.listen(3000)Se algo der errado
Todo erro chega como JSON com o campo error; alguns trazem também um code. Decida pelo status HTTP e pelo code, nunca pelo texto da mensagem.
| Status | O que houve | O que fazer |
|---|---|---|
401 | A chave está ausente, errada, revogada ou expirada | Confira o cabeçalho e crie uma chave nova, se preciso |
403 | Falta um escopo à chave (a mensagem diz qual) | Crie uma chave com o escopo que falta |
404 | O recurso não existe ou não é seu (as duas respostas são idênticas) | Confira os ids: $TENANT_ID e $CONNECTION_ID |
402 | number_limit_reached: a organização já usa todos os números contratados. subscription_inactive: o período de teste acabou ou uma fatura venceu e passou da carência | Apague uma conexão ou contrate mais números; regularize a assinatura no painel |
400 no envio | A conexão ainda não está open, o to não é um destinatário válido (invalid_recipient) ou falta o conteúdo | Espere o status: open; corrija o corpo |
429 | Um limite foi atingido: requisições por IP, a cota do plano ou os destinatários novos do número | Espere o tempo do Retry-After, quando vier, e repita com o mesmo clientRef |
Todos os códigos estão em Erros e em Códigos de erro.
Próximos passos
- Enviar mensagens: mídia, localização, templates e a fila.
- Webhooks e assinatura: os eventos, as novas tentativas e o reenvio de entregas.
- Erros: o que cada status HTTP significa e quando tentar de novo.
- LID e contact.resolved: remetentes que chegam sem telefone.
- Referência da API: todas as operações, com os parâmetros, as respostas e exemplos em cURL, Node.js, PHP e Python.