Instruções de Inicialização

Como Conectar a Instância

A conexão de um número de WhatsApp ao ZapFácil é feita de forma simples através de um fluxo assíncrono. Siga os passos abaixo:

Nota: O emparelhamento via QR Code pode ser feito visualmente pelo próprio usuário através do Painel de Controle (Dashboard) do ZapFácil. A API de envio de mensagens e recepção de webhooks é recomendada para automatizar o envio de conversas (qualquer usuário). Já os endpoints de gerenciamento de instâncias/empresas destinam-se a criar, listar e deletar conexões programaticamente (indicado para desenvolvedores e plataformas SaaS, como um SaaS de delivery que cria instâncias automaticamente para seus clientes).

1

Inicializar Conexão

Dispare uma requisição POST para a rota /instances/{instance_id}/connect. O servidor responderá imediatamente indicando que a inicialização está em andamento (status CONNECTING).

2

Obter o QR Code

Você pode obter o QR Code gerado via Webhook:

Via Webhook: Configure uma URL de webhook para escutar o evento QR_CODE. O servidor enviará um payload JSON contendo a string de imagem Base64.

3

Ler o QR Code

Abra o WhatsApp no celular, navegue em Aparelhos Conectados > Conectar um Aparelho, e aponte para a imagem gerada. Assim que a sincronização for concluída, você receberá a notificação webhook de alteração de estado para CONNECTED.

Simulação de Comportamento Humano

Humanização & Anti-ban

O WhatsApp possui mecanismos rígidos contra automações de spam. Para reduzir significativamente o risco de bloqueio de números, o ZapFácil implementa um motor de humanização automático para simular comportamentos reais durante os envios de mensagens.

Digitando... (delayTyping)

Simulador de Digitação

Simula o estado "Digitando..." no topo da conversa do destinatário antes da mensagem de texto ser disparada.

Se omitido, o sistema calcula dinamicamente: 1 segundo a cada 50 caracteres da mensagem (mínimo de 1s, máximo de 15s) com variação aleatória (jitter) de +/- 1s.

Fila e Pausa (delayBetweenMessages)

Intervalo pós-envio

Aplica uma pausa na fila de mensagens da instância imediatamente após cada disparo com sucesso.

Se omitido, o ZapFácil aplica automaticamente uma pausa flutuante de 1 a 3 segundos antes de liberar a próxima mensagem da fila.

Política de Uso Recomendado (Não faça campanhas/mensagens em massa):

O ZapFácil é uma ferramenta projetada e recomendada exclusivamente para comunicações transacionais e conversacionais humanizadas. Nós não apoiamos, não recomendamos e não damos suporte ao envio de campanhas ou disparos de mensagens em massa (spam). Esta prática viola os termos de serviço do WhatsApp e leva ao banimento imediato e irreversível de seu número de telefone. Foque em utilizar a API para responder interações receptivas de seus clientes ou enviar notificações autorizadas importantes.

Otimização de Escala

Standby & Gestão de RAM

Para garantir alta performance e escalabilidade de recursos no servidor, o ZapFácil gerencia a alocação de memória RAM das sessões ativas do WhatsApp de forma inteligente com regras de hibernação automáticas e agendadas.

Ociosidade

Hibernação Automática (Standby)

Instâncias que passam longos períodos sem atividade (sem envio ou recebimento de mensagens) entram automaticamente em modo standby (hibernação) para liberar memória física do servidor.

⚠️ Exceção para Webhooks Ativos: Se a sua empresa tiver webhooks ativos (isto é, com uma URL de webhook configurada e pelo menos um evento selecionado no painel), a instância nunca entrará em hibernação automática (auto-sleep é desabilitado) para garantir a escuta ininterrupta dos eventos.

Agendamento Definido pelo Usuário

Agendamento de Dormir e Acordar

O próprio usuário pode configurar e agendar horários específicos nas configurações da empresa para a sessão do WhatsApp dormir e acordar de forma programada.

Isso permite que você defina um período de sono (ex: das 22:00 às 07:00) para economizar recursos e garantir que as sessões sejam reativadas automaticamente no início do horário comercial.

Reativação

Reativação Automática & Botão "Acordar"

Quando uma nova mensagem é disparada através da API, o sistema restabelece a conexão da instância imediatamente de forma transparente. Alternativamente, é possível utilizar a ação "Acordar" diretamente no Painel de Controle para carregar explicitamente a sessão na memória ativa a qualquer momento.

Preferências e Filtros

Configurações da Empresa

Nas configurações da empresa, no Painel de Controle, você pode personalizar o comportamento padrão das instâncias e dos disparos de webhooks com as seguintes opções:

Auto-marcar mensagens como lidas

Leitura Automática Humanizada

Marca automaticamente as mensagens recebidas como lidas (visualizadas) no WhatsApp, simulando o atraso de um humano (varia de 5 a 60 segundos após o recebimento).

Ignorar mensagens de grupos

Filtro de Mensagens de Grupos

Quando ativado, os webhooks não serão disparados para mensagens recebidas em grupos, evitando processamento desnecessário de conversas coletivas.

Ignorar mensagens próprias

Filtro de Mensagens Próprias

Quando ativado, os webhooks não serão disparados para mensagens enviadas por você mesmo (seja via celular ou via outros disparadores), mantendo seus webhooks focados apenas nas respostas dos clientes.