Pular para o conteúdo

Parear um número

Conecte um número de WhatsApp por QR code ou por código de pareamento, acompanhe o status da conexão e saiba o que fazer quando o WhatsApp pede uma passkey.

Ver em Markdown

Uma conexão é um aparelho conectado do número, como o WhatsApp Web. Você a pareia uma vez, por QR code ou por um código de 8 caracteres digitado no celular. Depois disso, a sessão fica guardada na apiwpp: reinícios e reconexões não pedem um novo QR code.

1Crie a conexão

POST /connections cria a conexão no projeto e já começa o pareamento. Guarde o connectionId da resposta. O externalId é opcional: é o seu identificador para a conexão (o id do cliente no seu sistema, por exemplo) e volta em todos os webhooks dela. Criar de novo com um externalId que já existe no projeto conecta aquela conexão, sem criar outra.

bashVer na referência
curl -s -X POST https://api.apiwpp.com/connections \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tenantId": "'$TENANT_ID'", "externalId": "loja-42"}'
200
{ "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f", "externalId": "loja-42" }

Cada conexão ocupa um dos números que a sua organização contratou até ser excluída. Além deles, a resposta é 402 com code: number_limit_reached. Com a assinatura parada (o período de teste acabou, ou uma fatura venceu e passou da carência), é 402 com code: subscription_inactive. A conexão também pode ter um proxy próprio desde a criação: veja Proxy e IP dedicado.

2Mostre o QR code

Consulte GET /connections/{id}/qr a cada 2 a 5 segundos enquanto o pareamento estiver na tela:

bashVer na referência
curl -s https://api.apiwpp.com/connections/$CONNECTION_ID/qr \
  -H "Authorization: Bearer $API_KEY"
200
{ "qr": "2@k8Jd0Qf3mX1pT7vZ9sLr4eYw6nHc2bGa,…", "status": "connecting" }

O qr é o conteúdo do QR code, não uma imagem: gere a imagem com uma biblioteca de QR code. O WhatsApp troca o código a cada poucos segundos e um código antigo não pareia, então mostre sempre o mais recente. Com uma chave que só tem connections:read (um sistema de monitoramento, por exemplo), qr vem null e o status continua disponível.

import QRCode from 'qrcode'

const base = 'https://api.apiwpp.com'
const headers = { Authorization: `Bearer ${process.env.API_KEY}` }
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))

async function waitForPairing(connectionId, showQr) {
  for (;;) {
    const res = await fetch(`${base}/connections/${connectionId}/qr`, { headers })
    if (res.status === 503) {
      // A instância da conexão está mudando: espere o Retry-After
      await sleep(Number(res.headers.get('retry-after') ?? 5) * 1000)
      continue
    }
    if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`)

    const { qr, status } = await res.json()
    if (status === 'open') return
    if (status === 'passkey_required' || status === 'close') throw new Error(`Pareamento parado: ${status}`)
    if (qr) showQr(await QRCode.toDataURL(qr)) // data URL PNG para um <img src>
    await sleep(3000)
  }
}

Se preferir a imagem pronta, GET /tenants/{id}/connections/{connId}/qr responde qrCode como data URL PNG, para usar direto num <img src>, com a mesma regra: null sem connections:write.

3Escaneie no celular

No celular do número, abra WhatsApp › Aparelhos conectados › Conectar um aparelho e aponte a câmera para o QR code.

4Espere o open

Quando o pareamento termina, o status passa a open, o qr volta a null e o projeto recebe o webhook connection.status com o número pareado:

jsonconnection.status
{
  "type": "connection.status",
  "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
  "tenantId": "3f6c2a8e-9d41-4b7a-8c15-2e7d9a0b4c61",
  "externalId": "loja-42",
  "timestamp": "2026-09-29T12:00:00.000Z",
  "data": { "status": "open", "phoneNumber": "5511900000001" }
}

A partir daqui o número envia e recebe mensagens. Se ninguém escanear, os QR codes da tentativa acabam e a conexão fecha com reason: qr_not_scanned: conecte de novo (veja abaixo) para uma nova tentativa.

Os status da conexão

GET /connections/{id}/qr responde um destes status:

statusO que quer dizerO que fazer
connectingAbrindo o socket ou esperando o QR ser escaneado (qr preenchido)Mostrar o QR code
openPareada e conectada: pode enviar e receberNada
closeSem socket ativo: desconectada, sessão encerrada ou pareamento interrompidoConectar de novo
passkey_requiredO QR foi escaneado, mas o WhatsApp pediu uma passkey ao celularVeja a próxima seção

GET /connections lista as conexões dos seus projetos com o status atual, e as rotas de projeto (consultar uma conexão, por exemplo) mostram o status gravado, em minúsculas. Nelas também podem aparecer pending (criada, esperando o QR ser escaneado) e failed (falhou de vez; GET /connections só a lista com includeFailed=true). O histórico das verificações de saúde de cada conexão está em GET /tenants/{id}/connections/{connId}/heartbeats.

Quando o WhatsApp pede uma passkey

Desde meados de 2026, o WhatsApp pede a alguns celulares uma passkey (chave de acesso) logo depois da leitura do QR code. A apiwpp ainda não consegue concluir essa etapa, então o pareamento não termina. A plataforma percebe a situação (o QR foi lido e a conexão não abriu em 60 segundos, ou fechou duas vezes com erro enquanto o QR estava na tela) e:

  • para de gerar QR codes, em vez de ficar em ciclo;
  • responde status: passkey_required em GET /connections/{id}/qr, também depois de um reinício;
  • envia connection.status com { "status": "close", "reason": "passkey_required" }, sem phoneNumber.

A conexão fica parada até ser conectada de novo. Tente mais tarde com POST /tenants/{id}/connections/{connId}/connect, ou use outro número. Números já pareados não são afetados: a passkey só aparece em pareamentos novos.

Pareamento por código

Em vez de escanear o QR code, o dono do número pode digitar no celular um código de 8 caracteres. É útil quando o celular não está perto da tela que mostra o QR.

  1. Comece o pareamento como no QR code (crie a conexão ou conecte de novo) e espere o qr aparecer em GET /connections/{id}/qr: o código só pode ser pedido enquanto o QR code está na tela.
  2. Peça o código com POST /connections/{id}/pairing-code, informando o número que vai ser conectado no formato internacional (código do país primeiro, de 8 a 15 dígitos; +, espaços, traços e parênteses são ignorados).
  3. Digite o código no celular do número: WhatsApp › Aparelhos conectados › Conectar um aparelho › Conectar com número de telefone. O campo separa o código em dois grupos de 4 (K7QX-2M9P), e o celular também recebe um aviso do pedido.
  4. Espere o open, como no QR code.
curl -s -X POST https://api.apiwpp.com/connections/$CONNECTION_ID/pairing-code \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+5511900000001"}'
200
{ "code": "K7QX2M9P", "phone": "+5511900000001", "expiresAt": 1790251365000 }

O código vale até expiresAt, em milissegundos desde 1970. É quando terminam os QR codes dessa tentativa (no máximo cerca de 2,5 minutos depois de o primeiro aparecer), e a conexão passa a mostrar QR codes novos. Depois disso, o código não conecta mais: peça outro. Se faltarem menos de 30 segundos, o pedido é recusado com 409 not_pairing e Retry-After, o tempo até os próximos QR codes aparecerem.

Como cada pedido gera um aviso no celular, uma conexão pode pedir um código a cada 30 segundos, e um mesmo número recebe no máximo 5 códigos por hora, qualquer que seja a conexão que pede.

RespostaQuando
200O código, o número que ele conecta (phone, em E.164) e até quando ele vale (expiresAt)
400phone não é um número no formato internacional
402 subscription_inactiveA assinatura da organização está parada
409 not_pairingA conexão não está pareando com o QR code na tela: conecte de novo e peça o código. Com Retry-After: os QR codes dessa tentativa terminam em menos de 30 segundos; peça de novo depois desse tempo
409 already_pairedA conexão já está pareada com um número, ou um pareamento está terminando: faça logout para conectar outro
429 pairing_code_too_soonUm código foi pedido para a conexão há menos de 30 segundos, ou o número já recebeu 5 códigos na última hora: espere Retry-After segundos
501 unsupported_by_providerO provedor da conexão não oferece pareamento por código
503A instância que roda a conexão está mudando: espere Retry-After segundos

Nos erros com código, o corpo traz error com o código e message com a explicação, como em { "error": "not_pairing", "message": "…" }.

Os primeiros 14 dias de um número

Um número recém-pareado envia mais devagar durante 14 dias e alcança poucas pessoas novas por dia: é nessa fase que o WhatsApp mais restringe quem começa conversas com desconhecidos. Os limites sobem por etapas:

Desde o pareamentoPor horaPor diaDestinatários novos por 24 horas
Até 6 horas5205
6 a 24 horas105010
1 a 3 dias2010020
3 a 7 dias3015030
7 a 14 dias4520050

Nenhuma etapa passa dos limites normais da plataforma. Parear outro número, ou o mesmo depois de um logout, começa o aquecimento de novo. Os detalhes estão em Limites de envio.

Desconectar, reconectar e trocar de número

ChamadaEfeito
POST /connections/{id}/disconnectFecha a conexão e guarda a sessão: reconecte sem QR code
POST /tenants/{id}/connections/{connId}/connectReconecta com a sessão guardada, ou começa um pareamento se não houver sessão
POST /connections/{id}/logoutSai do WhatsApp e apaga a sessão: o próximo pareamento pede um QR code novo. Use para trocar o número
DELETE /tenants/{id}/connections/{connId}Sai do WhatsApp e exclui a conexão, com a sessão, os templates e o histórico. Não pode ser desfeito; se o logout falhar, nada é excluído (409) e você pode tentar de novo

Desconectar, fazer logout e excluir funcionam mesmo com a assinatura parada, para que você sempre possa liberar um número. Criar, conectar, buscar o QR code e pedir o código de pareamento respondem 402 subscription_inactive nesse caso. Todas essas chamadas podem responder 503 com Retry-After enquanto a instância que roda a conexão muda (um reinício, por exemplo): espere e repita.

Para trocar o número de uma conexão: faça logout, conecte de novo e pareie o número novo.

Acompanhe pelo webhook connection.status

Toda mudança da conexão chega como connection.status. Num fechamento, reason diz por quê e willReconnect diz se a plataforma reconecta sozinha:

reasonwillReconnectO que fazer
transienttrueNada: a plataforma tenta de novo sozinha e avisa com open
restart_requiredtrueNada: a plataforma reinicia o socket sozinha
replacedfalseOutra sessão assumiu o lugar desta: conecte de novo
qr_not_scannedfalseNinguém escaneou o QR a tempo: conecte de novo e mostre o QR
logged_outfalseO aparelho foi desconectado pelo celular: conecte de novo e pareie com um QR novo
manualfalseA conexão foi desconectada pela API ou pelo painel: conecte de novo quando quiser
passkey_required—O WhatsApp pediu uma passkey: veja a seção sobre passkey

Os motivos reachout_timelock e reachout_timelock_lifted avisam um bloqueio temporário de novas conversas, que não fecha a conexão; veja Limites de envio.

Próximos passos

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