Pular para o conteúdo

Início rápido

Da conta criada até a primeira mensagem enviada e o primeiro evento recebido no seu servidor, em cinco passos.

Ver em Markdown

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:

bashConfira a chave
curl -s https://api.apiwpp.com/me -H "Authorization: Bearer $API_KEY"
200
{
  "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.

bashCriar conexão e buscar o QR
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"
200
{ "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.

bashDefinir o segredo
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):

bashTestar o endpoint
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'"}'
200
{ "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).

bashVer na referê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"}'
202
{ "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):

jsNode.js
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):

jsonmessage.incoming
{
  "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:

jsonmessage.delivery
{
  "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:

jsNode.js · receptor de webhooks
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.

StatusO que houveO que fazer
401A chave está ausente, errada, revogada ou expiradaConfira o cabeçalho e crie uma chave nova, se preciso
403Falta um escopo à chave (a mensagem diz qual)Crie uma chave com o escopo que falta
404O recurso não existe ou não é seu (as duas respostas são idênticas)Confira os ids: $TENANT_ID e $CONNECTION_ID
402number_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ênciaApague uma conexão ou contrate mais números; regularize a assinatura no painel
400 no envioA conexão ainda não está open, o to não é um destinatário válido (invalid_recipient) ou falta o conteúdoEspere o status: open; corrija o corpo
429Um limite foi atingido: requisições por IP, a cota do plano ou os destinatários novos do númeroEspere 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

Esta página ajudou? · Atualizado em 29 set 2026