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:
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).
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.
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.
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.
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.
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.
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.
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.
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 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.
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:
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).
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.
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.
Integração com n8n
Automatize atendimentos, chatbots com IA e notificações transacionais conectando o ZapFácil ao n8n em segundos. Disponibilizamos um template pronto em formato .json para você importar diretamente no seu n8n via Ctrl + V.
Passo a Passo de Configuração
Importar no n8n
Clique no botão "Copiar JSON do Workflow" acima. No seu n8n, abra um novo fluxo e simplesmente pressione Ctrl + V (ou Cmd + V). Os 4 nós e anotações serão carregados no canvas.
Copiar a Webhook URL
Dê dois cliques no nó ZapFácil Webhook e copie a URL gerada (use a Production URL para ambiente produtivo ou a Test URL para executar testes no n8n).
Cadastrar no Painel do ZapFácil
No painel do ZapFácil, acesse Configurações da Empresa:
- Cole a URL no campo URL do Webhook.
- Marque o evento Mensagem Recebida (MESSAGE_RECEIVED).
- Clique em Salvar Configurações.
Informar o Company Token
No nó ZapFácil - Enviar Resposta no n8n, abra a seção Headers e substitua SEU_COMPANY_TOKEN_AQUI pelo token da sua empresa copiado do painel ZapFácil. Ative o workflow no n8n e sua automação estará operando!
Workflow JSON (n8n v1+)
zapfacil-n8n-template.json{
"name": "ZapFácil - Automação WhatsApp n8n",
"nodes": [
{
"parameters": {
"content": "### 🚀 Integração ZapFácil + n8n\n\n**Como usar:**\n1. Copie a **URL do Webhook** (Production ou Test URL) do nó ao lado.\n2. No painel do **ZapFácil**, vá em **Configurações da Empresa** e cole a URL no campo **Webhook URL** marcando o evento `MESSAGE_RECEIVED`.\n3. No nó **ZapFácil - Enviar Resposta**, substitua `SEU_COMPANY_TOKEN_AQUI` pelo seu **Token da Empresa** gerado no painel.\n4. Ative o workflow no n8n!",
"height": 280,
"width": 380,
"color": 6
},
"id": "c1f7a0b1-3829-4d69-bb19-45e0f7f25901",
"name": "Instruções de Uso",
"type": "n8n-nodes-base.stickyNote",
"typeVersion": 1,
"position": [
220,
140
]
},
{
"parameters": {
"httpMethod": "POST",
"path": "zapfacil-webhook",
"options": {}
},
"id": "e2a3c4d5-6789-4abc-9def-0123456789ab",
"name": "ZapFácil Webhook",
"type": "n8n-nodes-base.webhook",
"typeVersion": 2,
"position": [
260,
460
],
"webhookId": "zapfacil-webhook"
},
{
"parameters": {
"conditions": {
"options": {
"caseSensitive": true,
"leftValue": "",
"typeValidation": "strict"
},
"conditions": [
{
"id": "cond-event",
"leftValue": "={{ $json.body.event }}",
"rightValue": "MESSAGE_RECEIVED",
"operator": {
"type": "string",
"operation": "equals"
}
},
{
"id": "cond-not-from-me",
"leftValue": "={{ $json.body.data.is_from_me }}",
"rightValue": false,
"operator": {
"type": "boolean",
"operation": "equals"
}
}
],
"combinator": "and"
},
"options": {}
},
"id": "f3b4c5d6-789a-4bcd-8ef0-123456789abc",
"name": "Filtrar Mensagens Recebidas",
"type": "n8n-nodes-base.if",
"typeVersion": 2.2,
"position": [
480,
460
]
},
{
"parameters": {
"assignments": {
"assignments": [
{
"id": "phone",
"name": "phone",
"value": "={{ $json.body.data.phone }}",
"type": "string"
},
{
"id": "sender_name",
"name": "sender_name",
"value": "={{ $json.body.data.push_name || 'Cliente' }}",
"type": "string"
},
{
"id": "received_message",
"name": "received_message",
"value": "={{ $json.body.data.message }}",
"type": "string"
},
{
"id": "instance_id",
"name": "instance_id",
"value": "={{ $json.body.instance_id }}",
"type": "string"
}
]
},
"options": {}
},
"id": "a4b5c6d7-89ab-4cde-9f01-23456789abcd",
"name": "Extrair Dados da Mensagem",
"type": "n8n-nodes-base.set",
"typeVersion": 3.4,
"position": [
700,
440
]
},
{
"parameters": {
"method": "POST",
"url": "=https://zapfacil.dev/api/instances/{{ $json.instance_id }}/send-text",
"sendHeaders": true,
"headerParameters": {
"parameters": [
{
"name": "Authorization",
"value": "Bearer SEU_COMPANY_TOKEN_AQUI"
},
{
"name": "Content-Type",
"value": "application/json"
}
]
},
"sendBody": true,
"specifyBody": "json",
"jsonBody": "={\n \"phone\": \"{{ $json.phone }}\",\n \"message\": \"Olá {{ $json.sender_name }}! Recebemos sua mensagem: *\\\"{{ $json.received_message }}\\\"*\\n\\nEsta é uma resposta automática enviada via ZapFácil + n8n 🚀\",\n \"delayTyping\": 2\n}",
"options": {}
},
"id": "b5c6d7e8-9abc-4def-a012-3456789abcde",
"name": "ZapFácil - Enviar Resposta",
"type": "n8n-nodes-base.httpRequest",
"typeVersion": 4.2,
"position": [
920,
440
]
}
],
"connections": {
"ZapFácil Webhook": {
"main": [
[
{
"node": "Filtrar Mensagens Recebidas",
"type": "main",
"index": 0
}
]
]
},
"Filtrar Mensagens Recebidas": {
"main": [
[
{
"node": "Extrair Dados da Mensagem",
"type": "main",
"index": 0
}
]
]
},
"Extrair Dados da Mensagem": {
"main": [
[
{
"node": "ZapFácil - Enviar Resposta",
"type": "main",
"index": 0
}
]
]
}
},
"pinData": {},
"settings": {
"executionOrder": "v1"
}
}