WhatsApp via QR Code: conectando uma instância
O WhatsApp via QR Code é a forma rápida de conectar um número ao Rishi: você escaneia um QR Code (igualzinho ao WhatsApp Web) e pronto, o sistema começa a enviar mensagens automáticas em nome desse número.
É o caminho indicado pra automações de baixo volume e pra começar rápido sem burocracia da Meta. Pra escala maior, use a API Oficial (Meta).
QR Code vs. API Oficial
Decidir qual usar é a primeira pergunta. Aqui vai a comparação direta:
| Característica | QR Code | API Oficial |
|---|---|---|
| Burocracia inicial | Escanear QR e pronto | Aprovação Meta + CNPJ verificado |
| Custo por mensagem | Sem custo extra | Pode ter custo Meta (varia por categoria) |
| Risco de banimento | Existe — uso não-oficial | Sem risco se seguir as regras |
| Estabilidade | Conexão pode cair | Estável |
| Templates aprovados | Não — texto livre | Sim, obrigatório pra contato frio |
| Volume recomendado | < 500 mensagens/dia | Qualquer volume |
| Mensagens chegam de | Número real seu | Número Business verificado |
| Multi-aparelho | 1 dispositivo extra (como WhatsApp Web) | Não aplica |
O método QR Code não é reconhecido pela Meta como uso legítimo da API. O número pode ser banido sem aviso prévio, especialmente com alto volume, envio para contatos que não têm seu número salvo, ou conteúdo percebido como spam. Use com responsabilidade.
Conectando uma instância
1. Acesse a lista de instâncias
No app Rishi, vá em Suas Conexões (/instances).
Se você ainda não tem nenhuma instância, a tela mostra a página de upsell. Adquira uma e volte aqui.
2. Inicie a conexão
No card da instância Desconectada, clique em Conectar. O sistema abre a página pública de QR Code.
A página de QR é pública (sem login). Ela usa uma URL assinada — você pode mandar esse link pra outra pessoa (funcionário, sócio) e ela conecta sem precisar acessar o painel Rishi. Mais sobre isso na seção Compartilhando o link abaixo.
3. Escaneie no celular
Siga o passo a passo da tela:
- Abra o WhatsApp no celular
- Toque nos três pontinhos (Android) ou em Configurações (iPhone)
- Toque em Aparelhos Conectados
- Toque em Conectar um Aparelho
- Escaneie o QR Code da tela do Rishi
A tela faz polling a cada 15 segundos pra detectar a conexão. Quando funciona, muda pra Conectado com sucesso! e o sistema sincroniza:
- Nome do perfil
- Foto de perfil
- Número conectado (JID)
4. Pronto pra usar
A instância aparece como CONNECTED no painel. A partir daí, qualquer fluxo do Flow Builder que use essa instância no nó Mensagem vai disparar mensagens normalmente.
Compartilhando o link de conexão
Não está com o celular agora? Quer que outro funcionário conecte? Use o link público:
- No card da instância, copie o shareable URL.
- Mande o link via WhatsApp/e-mail pra quem vai conectar.
- A pessoa abre o link, vê o passo a passo e escaneia o QR — sem precisar de acesso ao painel Rishi.
Há também uma listagem pública (/shareable/qrcodes/{user}) que mostra todos os links de QR de uma conta.
O shareable_url não expira. Diferente de outros links assinados, esse é permanente. Se vazar, gere uma nova instância pra invalidar.
O QR em si expira
A URL pública não expira, mas o QR Code dentro dela expira em ~60 segundos (limitação do protocolo WhatsApp). Por isso o frontend faz polling automático: enquanto a página estiver aberta, ele renova o QR a cada 15s.
Estados da instância
| Status | Significado |
|---|---|
| Connected | Conectada e operacional. Mensagens são enviadas normalmente |
| Disconnected | Não conectada (instância nova, ou conexão caiu). Mensagens não saem. Avisamos automaticamente por WhatsApp quando isso acontece, com link pra reconectar |
| Blocked | Permanentemente bloqueada (geralmente por ação administrativa) |
Reconectando após queda
Se a sessão cair (atualização do app, troca de celular, inatividade), você recebe um WhatsApp automático com o link de reconexão. Basta clicar e escanear novamente.
Você também pode reconectar a qualquer momento clicando em Conectar no card no painel.
Soft block: pausa silenciosa
Em alguns casos (comportamento suspeito, risco de ban iminente), o time Rishi pode ativar soft_block numa instância. Quando isso acontece:
- O painel mostra badge laranja Bloqueada com contador de mensagens descartadas
- Mensagens são descartadas silenciosamente pelo job de envio
- A instância pode estar tecnicamente CONNECTED, mas com soft_block ativo
É diferente de Blocked: você pode resolver entrando em contato com o suporte. O contador de mensagens bloqueadas zera quando o soft_block é desativado.
Configurando o plugin WooCommerce
Com a instância conectada, você pode plugar diretamente no WooCommerce pra disparar mensagens em eventos da loja sem passar pelo Flow Builder.
- No card da instância (ou na tela de detalhes), clique em Configurar Plugin.
- Baixe o plugin
.zipindicado. - Instale em WordPress → Plugins → Adicionar novo → Enviar plugin.
- Em WooCommerce → WhatsApp → Configurações, copie do modal Rishi e cole:
- ID da Instância (
session_id) - Token de API
- ID da Instância (
- Ative as automações desejadas (pedido novo, status atualizado, código de rastreio, etc.).
Métricas e diagnóstico
O painel mostra por instância:
- Mensagens enviadas nos últimos 7 dias — gráfico
- Falhas de envio — tabela com destinatário, evento, motivo
- Cancelamentos (unsubscribers) — contatos que pediram pra parar de receber
Motivos de falha comuns:
| Motivo | O que aconteceu |
|---|---|
unsubscribed |
Cliente cancelou recebimento |
invalid_receiver |
Telefone inválido ou número não existe no WhatsApp |
invalid_body |
Texto da mensagem inválido (raro) |
generic |
Erro não classificado — geralmente erro de rede ou da API |
missing_recipient |
Cliente sem telefone cadastrado |
Mensagens com falha não são reenviadas automaticamente. O job tenta 3 vezes (com backoff de 20s, 40s, 120s) antes de marcar como falha definitiva.
Limites e avisos importantes
- Volume. Recomendado pra até 500 mensagens/dia. Acima disso, o risco de banimento aumenta sensivelmente.
- Mensagens pra contatos novos. Risco de denúncia por spam é alto. Prefira mandar pra quem já te conhece.
- Templates aprovados. Não existem. Qualquer texto pode ser enviado, mas isso é faca de dois gumes.
- Recibos de leitura. Se o cliente desativou recibos de leitura, suas mensagens ficam com status "Entregue" indefinidamente — o painel sinaliza isso.
- Múltiplos aparelhos. O número conectado por QR pode estar em apenas 1 aparelho extra. Se você conectar em outro lugar, a sessão Rishi pode cair.
- Celular precisa estar ativo. Pra contas WhatsApp comum (não Business multi-device), o celular precisa de bateria e conexão periódica pra manter a sessão.
Casos de borda
- Instância sem provedor configurado → tela de QR mostra "Conta inativa" e o time é notificado automaticamente.
- Instância deletada (soft delete) → aparece com badge Excluída e fica em status BLOCKED.
- Reconexão automática após migração de provedor → quando a instância sem credenciais perde conexão, o sistema tenta provisionar Uazapi automaticamente.
- Dois usuários diferentes acessando a mesma instância → bloqueado por permissão (HTTP 403).
Próximos passos
- Nó Mensagem — use a instância em fluxos automáticos.
- WhatsApp API Oficial (Meta) — quando precisar escalar.
- Sites — conecte sua loja pra disparar mensagens em eventos de pedido.