# Início rápido

Fonte: https://apiwpp.com/docs/inicio-rapido
Seção: Começando
Atualizado em: 2026-09-29

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

> **Antes de começar**
>
> A sua conta no painel pertence a uma **organização**. Cada **projeto** (o `tenant` da API) é um sistema seu, com o próprio endereço de webhook, e cada **conexão** é um número de WhatsApp desse projeto. Por enquanto, o projeto é criado pela nossa equipe, junto com o endereço que recebe os webhooks dele (`webhookBaseUrl`, uma URL https pública): peça pelo suporte e anote o `id` do projeto. Os números você cria pela API, até a quantidade que a sua organização contratou.
>
> Nos exemplos, `$API_KEY` é a sua chave, `$TENANT_ID` é o projeto e `$CONNECTION_ID` é a conexão. O endereço base é `https://api.apiwpp.com`.

## 1. Crie 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.

_[Imagem: Screenshot: criar chave de API no painel]_

Envie a chave em toda requisição, como `Authorization: Bearer wag_live_…` ou como `X-Api-Key: wag_live_…`. Confira com [`GET /me`](https://apiwpp.com/docs/api/conta/quem-esta-chamando), que responde a organização, os escopos e os projetos que a chave alcança:

**Confira a chave**

```bash
curl -s https://api.apiwpp.com/me -H "Authorization: Bearer $API_KEY"
```

Resposta `200`

```json
{
  "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](https://apiwpp.com/docs/autenticacao).

## 2. Pareie 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.

**Criar conexão e buscar o QR**

```bash
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"
```

Resposta `200`

```json
{ "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`](https://apiwpp.com/docs/api/projetos/qr-code-como-imagem) 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.

> **Dica**
>
> Sem câmera por perto? Use o [código de pareamento](https://apiwpp.com/docs/api/conexoes/codigo-de-pareamento) de 8 caracteres. O passo a passo completo, com os outros status, está em [Parear um número](https://apiwpp.com/docs/guias/parear-um-numero).

## 3. Assine 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.

**Definir o segredo**

```bash
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}`](https://apiwpp.com/docs/api/projetos/atualizar-projeto) para o que mais a sua chave pode mudar no projeto.

Antes do primeiro evento real, teste o endpoint: [`POST /tenants/webhook-test`](https://apiwpp.com/docs/api/projetos/testar-webhook) 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):

**Testar o endpoint**

```bash
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'"}'
```

Resposta `200`

```json
{ "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.

## 4. Envie 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](https://apiwpp.com/docs/guias/limites-de-envio)). O `clientRef` é o seu identificador do envio: repetir a requisição com ele não duplica a mensagem (veja [Idempotência](https://apiwpp.com/docs/guias/idempotencia)).

```bash
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"}'
```

Resposta `202`

```json
{ "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`):

**Node.js**

```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')
```

## 5. Receba 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):

**message.incoming**

```json
{
  "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": "5511988887777@s.whatsapp.net",
    "to": "5511900000001:7@s.whatsapp.net",
    "jid": "5511988887777@s.whatsapp.net",
    "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`:

**message.delivery**

```json
{
  "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": "5511988887777@s.whatsapp.net",
    "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:

**Node.js · receptor de webhooks**

```js
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)
```

> **Dica**
>
> Calcule a assinatura sobre os bytes do corpo exatamente como chegaram e rejeite um `X-Sales-Timestamp` a mais de 300 segundos do seu relógio. Toda entrega também traz o `X-Webhook-Token` do projeto. O guia [Webhooks e assinatura](https://apiwpp.com/docs/guias/webhooks-e-assinatura) traz o código de verificação em outras linguagens, as novas tentativas e o reenvio de entregas.

## 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](https://apiwpp.com/docs/guias/erros) e em [Códigos de erro](https://apiwpp.com/docs/referencia/codigos-de-erro).

## Próximos passos

- [Enviar mensagens](https://apiwpp.com/docs/guias/enviar-mensagens): mídia, localização, templates e a fila.
- [Webhooks e assinatura](https://apiwpp.com/docs/guias/webhooks-e-assinatura): os eventos, as novas tentativas e o reenvio de entregas.
- [Erros](https://apiwpp.com/docs/guias/erros): o que cada status HTTP significa e quando tentar de novo.
- [LID e contact.resolved](https://apiwpp.com/docs/guias/lid-e-contact-resolved): remetentes que chegam sem telefone.
- [Referência da API](https://apiwpp.com/docs/api): todas as operações, com os parâmetros, as respostas e exemplos em cURL, Node.js, PHP e Python.
