WhatsApp (Evolution API)

Conectando sua linha do WhatsApp via Evolution API

Configurar servidor, gerar QR Code, manter conexão aberta e lidar com desconexão.

Atualizado em 17 de maio de 20262 min de leitura

O PetShop Flow se integra com o WhatsApp via Evolution API — um servidor open-source que faz a ponte com o WhatsApp Web. Cada pet shop conecta sua própria instância.

Pré-requisitos

  • Você precisa de um servidor Evolution API rodando (próprio ou de um fornecedor).
  • URL do servidor (ex.: https://evolution.meuservidor.com).
  • API key do servidor Evolution.
  • Permissão manage_messaging (administrador).

Passo a passo

  1. Vá em /configuracoes/whatsapp.
  2. URL do servidor: cole a URL completa. O PetShop Flow remove a barra final automaticamente.
  3. API key: cole a chave (mínimo 8 caracteres).
  4. Nome da instância (opcional): só letras, números, _ ou -. Se você deixar em branco, o PetShop Flow usa petshop_<seu-slug>.
  5. Token de webhook (opcional): se não passar, o PetShop Flow gera um aleatório.
  6. Clique em Conectar.

[SCREENSHOT: Formulário de credenciais Evolution]

O que rola no servidor

Quando você salva, o PetShop Flow:

  1. Testa o servidor chamando pingEvolution com URL + API key. Se falhar com 401/403, retorna "Chave inválida ou sem permissão."
  2. Criptografa a API key e o token de webhook antes de gravar.
  3. Cria a instância no servidor Evolution apontando o webhook do PetShop Flow (/api/webhooks/evolution?t=<token>). Se a instância já existe, ignora o erro de "já existe".
  4. Salva os dados criptografados no messagingProviderConfig da pet shop.

Gerar QR Code e parear

Depois de conectado, você precisa parear com seu celular:

  1. Clique em Gerar QR Code.
  2. O PetShop Flow chama o Evolution e devolve a imagem em base64.
  3. Abra o WhatsApp do celular → Aparelhos conectados → Conectar um aparelho.
  4. Aponte a câmera pro QR.
  5. O estado muda de close pra connecting e depois open.

[SCREENSHOT: Página com QR Code visível]

Estados de conexão

  • open — conectada, funcional.
  • connecting — pareando.
  • close — desconectada (precisa novo QR).
  • unknown — PetShop Flow não conseguiu consultar o estado.

O PetShop Flow reconsulta o estado a cada visita à página e atualiza o banco se mudou.

Desconectar

Use Desconectar se quiser mudar de número ou parar de enviar. O PetShop Flow chama o Evolution pra encerrar a sessão e marca estado como close localmente — mesmo que a chamada externa falhe.

Permissões

Só administrador (manage_messaging).

Perguntas frequentes

Posso usar meu WhatsApp Business pessoal?

Sim. A Evolution API roda em cima do WhatsApp Web. O número que você parear vira o emissor.

O número precisa ser dedicado?

Recomendamos. Se você usa o número no celular ao mesmo tempo, a conexão pode cair com mais frequência.

A linha caiu, e agora?

Veja WhatsApp desconectou.

Artigos relacionados