Uma instância da Evolution API é um número de WhatsApp ligado ao seu servidor. Com a integração Baileys liga-se como se liga um computador ao WhatsApp Web: pede-se um código QR à API e lê-se com o celular. Quando a conexão cai, quase sempre se resolve lendo outro QR. Este artigo diz como, e como perceber porque caiu antes de tentar outra vez.
Os pedidos exatos (as rotas, os campos e o formato da resposta) estão na documentação oficial do projeto, e mudam com as versões. Aqui fica a sequência, não a sintaxe.
Ligar uma instância nova
| 1 |
Crie a instância. É um pedido autenticado com a chave da API (AUTHENTICATION_API_KEY) que dá um nome à instância e escolhe a integração. Escolha o Baileys para ligar por QR. A documentação diz o que o pedido leva.
|
|
| 2 |
Peça a conexão. A API devolve o código QR. Nas versões que o suportam, a documentação também prevê um código de emparelhamento, que se escreve no celular em vez de se ler.
|
|
| 3 |
Mostre o QR e leia-o depressa. O código expira em pouco tempo e a API muda-o. Se a tela demorar, peça outro. Se o recebe como texto codificado em vez de imagem, a documentação explica como o transformar em imagem.
|
|
| 4 |
No celular, abra o WhatsApp, vá às configurações, escolha os dispositivos associados e associe um dispositivo. Aponte a câmera para o QR.
|
|
| 5 |
Confirme o estado. Pergunte à API o estado da conexão. Enquanto diz «connecting», ainda não ligou. Quando passa ao estado de ligado (o nome exato vem na documentação), pode enviar. Veja enviar a primeira mensagem.
|
|
|
O QR dá acesso ao número. Quem o ler passa a poder enviar mensagens como você. Não o deixe numa página pública, numa conversa de grupo ou numa captura de tela guardada. Se o mostrou a quem não devia, saia em dispositivos associados no celular.
|
Quando a conexão cai
| Causa |
Como se vê |
O que fazer |
| Saiu dos dispositivos associados |
Removeu a sessão no celular ou o WhatsApp terminou-a. |
Ler um QR novo. A sessão antiga não se recupera. |
| O celular esteve muito tempo sem conexão |
O WhatsApp desassocia os dispositivos quando o telefone fica tempo demais desligado da internet. |
Ligue o telefone à internet e leia um QR novo se pedir. |
| As sessões perderam-se |
Depois de um reinício ou de uma atualização, a instância deixou de existir. |
Faltava o volume persistente. Veja PostgreSQL e Redis. |
| Fica em «connecting» |
O QR nunca chega a ligar e o serviço reinicia. |
Veja a instância presa em «connecting». |
| O número foi bloqueado |
O celular mostra um aviso do WhatsApp e não há QR que o valha. |
É o risco do Baileys. Não insista: veja o risco e as regras. |
Reconectar sem perder tempo
| 1 |
Primeiro o estado. Pergunte à API em que estado está a instância antes de mexer em nada.
|
|
| 2 |
Depois os registros. docker compose logs -f diz se o erro é de sessão, de rede ou do serviço.
|
|
| 3 |
Pedir outra conexão costuma chegar se a instância existe mas está desligada.
|
|
| 4 |
Só se isso não resultar, apague a instância e crie-a de novo, com a documentação aberta. Terá de ler um QR novo.
|
|
|
Evite desligar e voltar a ligar o mesmo número uma e outra vez. Tentativas repetidas parecem comportamento suspeito, e o WhatsApp pode reagir. Se a ligação não fica estável, procure a causa em vez de repetir.
|
PRODUTO RECOMENDADO Servidor VPS com acesso root Recursos só seus, o sistema que escolher, reinstalação quando quiser. desde R$ 46,20/mês (plano de 3 anos, com cupom) Ver planos |
Angola
Brasil
Kenya
Moçambique
Nigeria
Portugal
South Africa
United Kingdom
United States
International
