API Docs - ZapSender

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

Payload JSON Completo

{
  "api_key": "SUA_API_KEY",
  "action": "send_message",
  "instance": "vendas01",
  "number": "5511999998877",
  "message": "{Olá|Oi} {nome}! Tudo bem?",
  "vars": { "nome": "Carlos" },
  "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: Nenhum arquivo de mídia é enviado pelo webhook — apenas a notificação do tipo. Seu sistema pode decidir como tratar cada tipo (ex: transcrever áudios com Whisper, processar imagens com OCR).

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": null,
  "messageType": "audio",
  "timestamp": "2024-03-27 15:31:12"
}