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.
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.
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"}'{ "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:
curl -s https://api.apiwpp.com/connections/$CONNECTION_ID/qr \
-H "Authorization: Bearer $API_KEY"{ "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)
}
}import os
import time
import qrcode # pip install qrcode[pil]
import requests
BASE = "https://api.apiwpp.com"
HEADERS = {"Authorization": f"Bearer {os.environ['API_KEY']}"}
def wait_for_pairing(connection_id, show_qr):
while True:
res = requests.get(f"{BASE}/connections/{connection_id}/qr", headers=HEADERS, timeout=30)
if res.status_code == 503:
time.sleep(int(res.headers.get("Retry-After", "5")))
continue
res.raise_for_status()
body = res.json()
if body["status"] == "open":
return
if body["status"] in ("passkey_required", "close"):
raise RuntimeError(f"Pareamento parado: {body['status']}")
if body["qr"]:
show_qr(qrcode.make(body["qr"]))
time.sleep(3)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:
{
"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:
status | O que quer dizer | O que fazer |
|---|---|---|
connecting | Abrindo o socket ou esperando o QR ser escaneado (qr preenchido) | Mostrar o QR code |
open | Pareada e conectada: pode enviar e receber | Nada |
close | Sem socket ativo: desconectada, sessão encerrada ou pareamento interrompido | Conectar de novo |
passkey_required | O QR foi escaneado, mas o WhatsApp pediu uma passkey ao celular | Veja 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_requiredemGET /connections/{id}/qr, também depois de um reinício; - envia
connection.statuscom{ "status": "close", "reason": "passkey_required" }, semphoneNumber.
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.
- Comece o pareamento como no QR code (crie a conexão ou conecte de novo) e espere o
qraparecer emGET /connections/{id}/qr: o código só pode ser pedido enquanto o QR code está na tela. - 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). - 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. - 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"}'const res = await fetch(`https://api.apiwpp.com/connections/${connectionId}/pairing-code`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ phone: '+5511900000001' }),
})
if (res.status === 409 || res.status === 429) {
const retryAfter = res.headers.get('retry-after') // segundos, quando vier
const { error } = await res.json() // already_paired, not_pairing ou pairing_code_too_soon
throw new Error(`${error}; tente de novo em ${retryAfter ?? '?'} s`)
}
if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`)
const { code, expiresAt } = await res.json()
console.log(`Digite ${code.slice(0, 4)}-${code.slice(4)} até ${new Date(expiresAt).toISOString()}`){ "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.
| Resposta | Quando |
|---|---|
200 | O código, o número que ele conecta (phone, em E.164) e até quando ele vale (expiresAt) |
400 | phone não é um número no formato internacional |
402 subscription_inactive | A assinatura da organização está parada |
409 not_pairing | A 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_paired | A conexão já está pareada com um número, ou um pareamento está terminando: faça logout para conectar outro |
429 pairing_code_too_soon | Um 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_provider | O provedor da conexão não oferece pareamento por código |
503 | A 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 pareamento | Por hora | Por dia | Destinatários novos por 24 horas |
|---|---|---|---|
| Até 6 horas | 5 | 20 | 5 |
| 6 a 24 horas | 10 | 50 | 10 |
| 1 a 3 dias | 20 | 100 | 20 |
| 3 a 7 dias | 30 | 150 | 30 |
| 7 a 14 dias | 45 | 200 | 50 |
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
| Chamada | Efeito |
|---|---|
POST /connections/{id}/disconnect | Fecha a conexão e guarda a sessão: reconecte sem QR code |
POST /tenants/{id}/connections/{connId}/connect | Reconecta com a sessão guardada, ou começa um pareamento se não houver sessão |
POST /connections/{id}/logout | Sai 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:
reason | willReconnect | O que fazer |
|---|---|---|
transient | true | Nada: a plataforma tenta de novo sozinha e avisa com open |
restart_required | true | Nada: a plataforma reinicia o socket sozinha |
replaced | false | Outra sessão assumiu o lugar desta: conecte de novo |
qr_not_scanned | false | Ninguém escaneou o QR a tempo: conecte de novo e mostre o QR |
logged_out | false | O aparelho foi desconectado pelo celular: conecte de novo e pareie com um QR novo |
manual | false | A 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
- Enviar mensagens: texto, mídia, localização, templates e a fila.
- Webhooks e assinatura: receber e verificar os eventos,
connection.statusincluído. - Projetos e conexões: o projeto, as conexões dele e o limite de números.