API Docs
ZapSender - WebCis Public API

Turbine sua comunicação via WhatsApp.

Nossa API REST foi desenhada para facilitar integrações complexas. Automatize notificações, lembretes de pagamento e fluxos de atendimento com segurança de nível empresarial.

Base Endpoint (SSL Required)

https://zap.mago3.com.br/api.php

Segurança & Autenticação

Bearer Token

Padrão via Header HTTP. Recomendado para maior segurança em ambientes configurados.

JSON Payload

Envio da api_key dentro do corpo JSON. Mais estável em servidores Apache/CPanel.

TLS 1.3

Toda comunicação é criptografada de ponta a ponta via HTTPS.

Método 1: Header HTTP

Authorization: Bearer SUA_API_KEY

Método 2: JSON (Garante Funcionamento)

{
  "api_key": "SUA_API_KEY",
  "action": "...",
  "..."
}

Proteção Anti-Ban Ativa

Diferente de APIs genéricas, nosso motor processa cada mensagem com inteligência de segurança integrada. Sua conta está protegida por 3 camadas exclusivas:

Inteligência Spintax

Suporte a variações {A|B} para evitar padrões robóticos.

Cooldown de Segurança (48h)

Bloqueio automático de mensagens idênticas para o mesmo número.

Simulação Humana

Status "Digitando..." e delays aleatórios em todos os envios.

Exemplo Spintax

Payload "message":

"{Boa tarde|Olá|Oi} {contato}! Seu pedido está {a caminho|sendo entregue}."

Resultado Aleatório:

"Olá João! Seu pedido está a caminho."

Enviar Mensagem

Endpoint principal para disparos individuais com simulação humana.

POST /api.php

Parâmetros Obrigatórios (Payload Principal)

Campo Valor/Tipo Descrição Detalhada
action send_message Ação obrigatória para iniciar o processo de envio.
instance string Nome da instância que realizará o envio (deve estar Connected).
number string DDI + DDD + Número. Formato: 5511999887766.
message string O texto da mensagem. Suporta emojis e Spintax.

Todos os Parâmetros Suportados

Parâmetro Tipo Obrigatório Descrição e Regras
template_id integer Opcional Se enviado, ignora o campo message e usa um template do painel.
vars object Opcional Variáveis para substituição: {"cliente": "Carlos"}.
scheduled_at datetime Opcional Data/Hora para envio programado (Y-m-d H:i:s).
close_session boolean Opcional Se 1, fecha a janela de chat no painel após o envio.
fura_fila boolean PRIORIDADE Ignora a fila de espera e envia imediatamente (Consome 2 créditos).
image_url string Opcional URL pública direta da imagem a ser enviada (ex: https://site.com/imagem.png).
Payload JSON Completo 
{
  "api_key": "SUA_API_KEY",
  "action": "send_message",
  "instance": "vendas01",
  "number": "5511999998877",
  "message": "{Olá|Oi} {nome}! Tudo bem?",
  "vars": { "nome": "Carlos" },
  "image_url": "https://site.com/imagem.png",
  "schedule_enabled": 1
}
Dica de Alta Performance

Para integrações de larga escala, recomendamos o uso da propriedade fura_fila: true apenas para alertas críticos ou autenticação (2FA).

Simulação de Digitação Ativa por Padrão

Envio em Lote (Batch)

Dispare para múltiplos contatos em uma única chamada.

POST

A API agora aceita o array contacts. Ao enviar este array, o sistema processa cada contato individualmente, aplicando as variáveis específicas de cada um e personalizando a mensagem final.

Propriedade do Contato Tipo Descrição
number string Número de destino (DDI + DDD + Número).
name string Nome opcional para exibição no sistema.
vars object Variáveis exclusivas deste número (ex: {"nome": "João"}).
Exemplo JSON Lote 
{
  "api_key": "SUA_API_KEY",
  "action": "send_message",
  "instance": "Minha_Instancia",
  "message": "{Olá|Oi} {nome}, seu pedido foi aprovado!",
  "contacts": [
    {
      "number": "5511999990001",
      "name": "Maria Silva",
      "vars": { "nome": "Maria" }
    },
    {
      "number": "5511999990002",
      "name": "João Souza",
      "vars": { "nome": "João" }
    },
    {
      "number": "5511999990003",
      "name": "Ana Costa",
      "vars": { "nome": "Ana" }
    }
  ],
  "close_session": 1
}

Histórico de Sessão

GET

Polling de Mensagens

Retorne o histórico de uma sessão aberta. Você pode sincronizar as conversas do seu CRM usando o parâmetro after_id.

?action=get_chat_history&number=... 
GET /api.php?action=get_chat_history&number=5511999998877

Saldo & Créditos

GET

Consulte o saldo atual do usuário autenticado para exibir no seu painel externo ou controlar limites de disparo.

GET /api.php?action=get_credits

Exemplo de Retorno

2.450

Mensagens restantes

Instâncias

GET

Retorna todas as instâncias do usuário e seus respectivos status de conexão. Útil para validar se um bot pode disparar ou se o QR Code desconectou.

GET /api.php?action=list_instances

Webhook Externo

Receba mensagens recebidas em seu servidor (Integração com IA).

POST OUT

Sempre que uma mensagem é recebida em sua instância, nosso sistema pode disparar um POST JSON automático para uma URL externa. Ideal para conectar com motores de Inteligência Artificial ou CRMs próprios.

Campo Descrição
event Tipo de evento. Valor fixo: message_received.
instance Nome da instância que recebeu a mensagem.
number Número do remetente (incluindo DDI).
message Conteúdo textual da mensagem. Retorna null quando o tipo não é texto (ex: áudio, imagem).
messageType Tipo da mensagem recebida. Valores possíveis: text, audio, image, video, document, sticker.
timestamp Data e Hora do recebimento no formato Y-m-d H:i:s.

Tipos de Mensagem Suportados

O webhook notifica sobre todos os tipos de mensagem. O campo messageType identifica o tipo recebido. Para mídias, message retorna null.

text

Mensagem de texto simples ou formatada.

audio

Áudio ou mensagem de voz (PTT).

image

Foto ou imagem enviada.

video

Vídeo enviado pelo contato.

document

PDF, planilha ou outro documento.

sticker

Figurinha/sticker (adesivo).

Importante: Mensagens de áudio são baixadas automaticamente pelo nosso servidor e o link direto do arquivo `.ogg` é fornecido no campo message para fácil transcrição (ex: com OpenAI Whisper). Para os demais tipos de mídia (imagem, vídeo, documento, sticker), apenas a notificação do tipo é enviada no momento.

Dica para IA

Após processar a mensagem com sua IA, você deve responder ao usuário utilizando o endpoint send_message documentado acima.

Exemplo de JSON Recebido 
// Mensagem de texto
{
  "event": "message_received",
  "instance": "vendas_01",
  "number": "5511999998877",
  "message": "Olá, gostaria de saber mais.",
  "messageType": "text",
  "timestamp": "2024-03-27 15:30:45"
}

// Mensagem de áudio
{
  "event": "message_received",
  "instance": "vendas_01",
  "number": "5511999998877",
  "message": "https://zap.mago3.com.br/assets/uploads/audios/1234567890ABCDEF.ogg",
  "messageType": "audio",
  "timestamp": "2024-03-27 15:31:12"
}
Conexão Headless & Multi-Lojas

Conectar WhatsApp & Gerar QR Code na sua Loja Virtual

Você pode criar a instância, exibir o QR Code e monitorar a conexão do WhatsApp diretamente dentro da sua loja virtual ou plataforma SaaS, sem que você ou os seus lojistas precisem acessar o painel do ZapSender.

Como integrar com Plataformas de Lojas Virtuais:

1. Em Minha API, gere uma Chave da Plataforma de Lojas e insira-a no Superadmin da sua plataforma de e-commerce.

2. Quando um cliente lojista ativar o plugin na loja dele, seu sistema chama create_instance passando o identificador da loja (ex: loja_45).

3. Todas as instâncias criadas com a Chave de Loja são automaticamente separadas na tela Lojas Virtuais do ZapSender, mantendo suas instâncias pessoais totalmente isoladas.

POST action: create_instance

Cria a sessão de WhatsApp da sua loja. Você pode definir um nome identificador para a instância (ex: loja, notificacoes).

Parâmetros (JSON Body)

instance_name Nome identificador da instância (Opcional, padrão: loja). Apenas letras, números e traço.
Exemplo de Criação (PHP cURL) 
$ch = curl_init("https://zap.mago3.com.br/api.php");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer SUA_API_KEY",
        "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "action" => "create_instance",
        "instance_name" => "loja"
    ])
]);
$response = json_decode(curl_exec($ch), true);
// Salve $response['instance_name'] para usar nos próximos passos
Resposta de Sucesso 200 OK 
{
  "status": "success",
  "message": "Instância criada com sucesso!",
  "instance_name": "u12_loja"
}
POST action: get_qrcode

Gera o QR Code de autenticação do WhatsApp. O sistema retorna o QR Code já codificado em Base64 para você desenhar diretamente em uma tag <img src="data:image/png;base64,..."> na tela de configurações da sua loja virtual.

Parâmetros (JSON Body)

instance Nome da instância (Opcional: se omitido, o sistema seleciona automaticamente a sua primeira instância ativa).
Exemplo no Frontend (JavaScript Fetch) 
const res = await fetch("https://zap.mago3.com.br/api.php", {
    method: "POST",
    headers: {
        "Authorization": "Bearer SUA_API_KEY",
        "Content-Type": "application/json"
    },
    body: JSON.stringify({ action: "get_qrcode" })
});
const data = await res.json();

if (data.connected) {
    alert("WhatsApp já está conectado!");
} else if (data.qrcode_base64) {
    // Exibe a imagem do QR Code na tela da sua loja:
    document.getElementById("qr-code-img").src = data.qrcode_base64;
}
Retorno do QR Code 200 OK 
{
  "status": "success",
  "connected": false,
  "state": "connecting",
  "instance": "u12_loja",
  "qrcode_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "code": "2@qP9...==,5WqX..."
}
POST action: get_instance_status

Verifica em tempo real se o WhatsApp foi conectado com sucesso após o escaneamento do QR Code. Ideal para executar polling a cada 3 segundos enquanto a tela de conexão estiver aberta.

Polling Automático (JavaScript) 
const interval = setInterval(async () => {
    const res = await fetch("https://zap.mago3.com.br/api.php", {
        method: "POST",
        headers: {
            "Authorization": "Bearer SUA_API_KEY",
            "Content-Type": "application/json"
        },
        body: JSON.stringify({ action: "get_instance_status" })
    });
    const data = await res.json();
    if (data.connected && data.state === "open") {
        clearInterval(interval);
        alert("WhatsApp conectado com sucesso pelo número: " + data.owner_jid);
    }
}, 3000);
Status Conectado open 
{
  "status": "success",
  "instance": "u12_loja",
  "state": "open",
  "connected": true,
  "owner_jid": "5511999998877@s.whatsapp.net"
}
POST action: disconnect_instance

Desconecta o WhatsApp da instância caso você queira deslogar o número ou escanear um novo aparelho.

Exemplo de Desconexão (cURL) 
curl -X POST "https://zap.mago3.com.br/api.php" \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "disconnect_instance"}'
Resposta 200 OK 
{
  "status": "success",
  "message": "Instância desconectada com sucesso."
}