Entrar Painel
Doc AI Friendly (agente de IA)
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.

Low-Code & Automação Workflow Oficial

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.

Baixar workflow.json Arquivo JSON para importação manual
Baixar ↓

Passo a Passo de Configuração

1

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.

2

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).

3

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.
4

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"
  }
}