QR code de pareamento do WhatsApp
QR code de pareamento é o código que o celular escaneia para ligar o número de WhatsApp a um aparelho conectado, como o WhatsApp Web ou uma API. Ele muda a cada poucos segundos e pode ser trocado por um código de 8 caracteres.
Atualizado em
O QR code de pareamento é o quadrado que aparece na tela do WhatsApp Web, do aplicativo de desktop ou de uma API de WhatsApp quando um número ainda não está conectado. Ele carrega uma chave temporária. Quando o dono do número o escaneia pelo celular, em WhatsApp › Aparelhos conectados › Conectar um aparelho, o WhatsApp registra aquela tela ou aquele servidor como um novo aparelho conectado do número.
Por que o QR code muda a cada poucos segundos
O código é de uso único e vale por pouco tempo. O WhatsApp gera um novo a cada poucos segundos enquanto ninguém escaneia, para que uma foto antiga da tela não sirva para conectar o número depois. Por isso, quem mostra o QR code precisa sempre exibir o mais recente.
Numa API, isso vira uma regra simples de implementação. Na apiwpp, o conteúdo do QR code está em GET /connections/{id}/qr, e o seu sistema deve buscá-lo a cada 2 a 5 segundos, trocando a imagem a cada resposta:
{ "qr": "2@k8Jd0Qf3mX1pT7vZ9sLr4eYw6nHc2bGa,…", "status": "connecting" }
O campo qr é o texto que vira a imagem, gerada com qualquer biblioteca de QR code. Se preferir a imagem pronta, a rota do projeto (GET /tenants/{id}/connections/{connId}/qr) devolve uma data URL PNG, que entra direto num <img>. É assim que um SaaS ou CRM mostra o QR code dentro da própria tela, para cada cliente conectar o número dele sem sair do sistema.
A alternativa: código de pareamento de 8 caracteres
Nem sempre dá para apontar a câmera para a tela: o dono do número está em outra cidade, a câmera do celular não funciona ou o pareamento é feito 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, em Conectar um aparelho › Conectar com número de telefone.
Na apiwpp, o código é pedido em POST /connections/{id}/pairing-code, informando o número no formato internacional. A resposta traz o código e até quando ele vale. O resultado é o mesmo do QR code: o número fica conectado como aparelho conectado.
O que acontece depois de escanear
Quando a leitura dá certo, o WhatsApp entrega ao aparelho as chaves da sessão, e a partir daí o celular não precisa mais participar. Na apiwpp:
- a conexão passa ao status
opene o projeto recebe o eventoconnection.statusno webhook; - a sessão fica salva e criptografada, então reinícios e reconexões não pedem um QR code novo;
- começa o aquecimento de número de 14 dias, com limites de envio que sobem por etapa.
Um QR code novo só volta a ser necessário depois de um logout, quando o aparelho é removido no celular ou quando você troca o número da conexão.
Um aviso honesto: desde meados de 2026, o WhatsApp pede a alguns celulares uma passkey logo depois da leitura do QR code. A apiwpp ainda não consegue concluir essa etapa; nesse caso, a conexão para com o status passkey_required, em vez de gerar QR codes sem fim. Números já pareados não são afetados.
O passo a passo completo, com os status da conexão e os escopos de chave, está em conexão por QR code ou código de pareamento e no tutorial como conectar um número à API.
Perguntas frequentes
O QR code da API é o mesmo do WhatsApp Web?
O mecanismo é o mesmo: nos dois casos, o celular escaneia o código e registra um aparelho conectado. A diferença é quem fica do outro lado. No WhatsApp Web é um navegador; numa API como a apiwpp, é um servidor que envia e recebe mensagens pelo seu sistema.
Quanto tempo o QR code vale?
Poucos segundos. O WhatsApp troca o código continuamente enquanto ele não é lido, e um código antigo não conecta. Por isso a recomendação é buscar o QR code a cada 2 a 5 segundos e mostrar sempre o último.
Preciso escanear de novo quando o servidor reinicia?
Não. Depois do primeiro pareamento, a sessão fica guardada e a reconexão usa essa sessão. Só um logout, a remoção do aparelho no celular ou a troca de número pedem um QR code novo.
Dá para conectar sem câmera?
Sim, com o código de pareamento de 8 caracteres. A pessoa digita o código no celular, em "Conectar com número de telefone", e o resultado é o mesmo da leitura do QR code.
Outros termos
Todos: Glossário →Aparelho conectado é um dispositivo extra ligado a uma conta de WhatsApp, como o WhatsApp Web, o aplicativo de desktop ou o servidor de uma API. Ele é pareado pelo celular uma vez e depois envia e recebe mensagens mesmo com o celular desligado.
Aquecimento de número (ou de chip) é o período depois de conectar um WhatsApp em que os limites de envio começam baixos e sobem aos poucos, para o número ganhar histórico antes de chegar ao volume normal. Na apiwpp, ele dura 14 dias e é aplicado pela fila.
Webhook é uma chamada HTTP que um serviço faz para um endereço do seu sistema quando um evento acontece, como uma mensagem recebida. Em vez de perguntar de tempos em tempos se há novidades, o seu sistema é avisado na hora.