Conexão por QR code ou código de pareamento
Conecte um número de WhatsApp à API por QR code ou por um código de 8 caracteres e acompanhe o status da conexão em tempo real pelo webhook.
Atualizado em
Antes de enviar a primeira mensagem, o número precisa estar conectado. Na apiwpp, cada conexão é um número de WhatsApp dentro de um projeto, ligado como aparelho conectado: o mesmo mecanismo que o WhatsApp Web e o aplicativo de desktop usam. Não há cadastro na Meta, aprovação de conta nem espera: você mostra um QR code, o dono do número escaneia pelo celular e a conexão abre.
Esse fluxo funciona tanto no painel da apiwpp quanto dentro do seu próprio produto. Se você tem um SaaS ou um CRM, pode buscar o QR code pela API e exibi-lo na sua tela, para que cada cliente conecte o número dele sem sair do seu sistema.
Como funciona o pareamento por QR code
Uma conexão sem sessão começa a parear assim que é criada (ou quando você pede para conectá-la de novo). A partir daí, o QR code fica disponível pela API:
curl -s "https://api.apiwpp.com/connections/$CONNECTION_ID/qr" \
-H "Authorization: Bearer $API_KEY"
{ "qr": "2@k8Jd0Qf3mX1pT7vZ9sLr4eYw6nHc2bGa,…", "status": "connecting" }
O campo qr traz o conteúdo do QR code: gere a imagem com qualquer biblioteca de QR code da sua linguagem. Se preferir a imagem pronta, a rota do projeto (GET /tenants/{id}/connections/{connId}/qr) responde qrCode como uma data URL PNG, que vai direto num <img src>.
Três cuidados deixam o fluxo sem atrito:
- Busque o QR code a cada 2 a 5 segundos. O WhatsApp troca o código a cada poucos segundos, e um código antigo não pareia.
- Mostre sempre o mais recente. Substitua a imagem a cada resposta em vez de manter a primeira na tela.
- Oriente quem vai escanear. No celular do número: WhatsApp › Aparelhos conectados › Conectar um aparelho.
Quando a leitura dá certo, status passa a open, qr volta a null e o projeto recebe o evento connection.status com o número que foi pareado.
Código de pareamento: sem câmera, sem QR code
Nem sempre dá para apontar a câmera para uma tela. O dono do número está em outra cidade, o celular está com a câmera quebrada, ou o pareamento acontece por telefone com o suporte. Para esses casos existe o código de pareamento: um código de 8 caracteres que a pessoa digita no próprio celular.
Com o QR code já na tela, peça o código informando o número no formato internacional:
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"}'
{ "code": "K7QX2M9P", "phone": "+5511900000001", "expiresAt": 1790251365000 }
No celular, o caminho é WhatsApp › Aparelhos conectados › Conectar um aparelho › Conectar com número de telefone. O aplicativo mostra o campo em dois grupos de quatro (K7QX-2M9P) e também avisa que houve um pedido de conexão. O código vale até expiresAt; depois disso, peça outro.
Como cada pedido gera um aviso no celular, há um intervalo mínimo entre pedidos para a mesma conexão e um número máximo de códigos por hora para o mesmo número. Se passar do ritmo, a resposta é 429 com o cabeçalho Retry-After, dizendo quantos segundos esperar.
Status em tempo real
Você não precisa ficar consultando a API para saber se o número está online. Cada mudança chega no webhook do projeto como connection.status:
{ "type": "connection.status", "data": { "status": "open", "phoneNumber": "5511900000001" } }
Os status possíveis são poucos e diretos:
status | O que significa |
|---|---|
connecting | Abrindo a conexão ou esperando a leitura do QR code |
open | Pareada e conectada: pode enviar e receber |
close | Sem conexão ativa: desconectada, sessão encerrada ou pareamento interrompido |
passkey_required | O QR foi lido, mas o WhatsApp pediu uma passkey ao celular |
Todo fechamento traz um motivo (reason) e o campo willReconnect, que diz se a apiwpp vai reconectar sozinha. Uma queda de rede (transient) é resolvida automaticamente; uma sessão encerrada pelo celular (logged_out) pede um novo pareamento. Com isso, o seu sistema sabe quando avisar alguém e quando apenas esperar.
Escopos: quem pode ver o QR code
Escanear um QR code conecta um número à sua conta, então ele é tratado como informação sensível. As chaves de API têm escopos:
connections:writeé necessário para receber o QR code e pedir o código de pareamento.connections:readbasta para acompanhar o status. Com esse escopo,qreqrCodevêmnull, e ostatuscontinua disponível.
Na prática, dê connections:write só ao componente que conduz o pareamento e use connections:read no monitoramento, em dashboards internos e em qualquer serviço que só precise saber se o número está online.
Uma limitação que você deve conhecer
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. Em vez de ficar gerando QR codes em ciclo, a conexão para com o status passkey_required e envia connection.status com esse motivo. Você pode tentar de novo mais tarde ou usar outro número. Números já pareados não são afetados: a passkey só aparece em pareamentos novos.
Depois de conectar
Com a conexão aberta, a sessão fica salva e criptografada, e o celular pode até ficar desligado: veja sessão persistente. A partir daí, o número já pode enviar mensagens pela fila.
Um número recém-conectado passa por um aquecimento de 14 dias, com limites de envio que crescem por etapa, porque é nessa fase que o WhatsApp mais restringe quem começa conversas com desconhecidos. Para um passo a passo completo com código, leia o tutorial como conectar um número por QR code ou código de pareamento, ou veja todos os recursos da apiwpp.
Perguntas frequentes
Preciso de aprovação da Meta para conectar o número?
Não. A apiwpp conecta o número pelo protocolo do WhatsApp Web, como um aparelho conectado, sem conta Business verificada nem aprovação. Por isso ela não é a API oficial do WhatsApp e não oferece o selo verificado.
Posso mostrar o QR code dentro do meu próprio sistema?
Pode. Busque o conteúdo do QR code pela API e gere a imagem, ou use a rota que devolve a imagem pronta como data URL PNG. Atualize a imagem a cada 2 a 5 segundos, porque o WhatsApp troca o código com frequência.
O que é melhor: QR code ou código de pareamento?
Os dois conectam o número do mesmo jeito. O QR code é mais rápido quando a pessoa está diante da tela; o código de 8 caracteres resolve quando não dá para usar a câmera ou quando o pareamento é feito a distância.
Como troco o número de uma conexão?
Faça logout da conexão: isso encerra a sessão no WhatsApp e apaga a sessão salva. O próximo pareamento pede um QR code novo e pode ser feito com outro número. Lembre que o aquecimento de 14 dias recomeça.
Outros recursos
Todos: Recursos →Depois do pareamento, a sessão do número fica salva e criptografada nos servidores da apiwpp. Reinícios, atualizações e quedas de rede não pedem um novo QR code, e o celular não precisa ficar ligado.
POST /connections/{id}/send coloca a mensagem na fila do número e responde 202 com jobId, scheduledAt e position. A API resolve o endereço do destinatário, mostra o "digitando…" e avisa o resultado pelo webhook message.delivery.
Cada evento do número chega no seu servidor com um POST assinado com HMAC-SHA256. A entrega é feita pelo menos uma vez, com novas tentativas, registro de cada entrega e reenvio.