Skip to content

kauafpssx/ZapUnlocked-API

BranchesTags

Repository files navigation

⚡💬 ZapUnlocked-API

ZapUnlocked-API Banner

Free & Open Source Postman Collection REST API MIT License Python 3.10+

🌐 Select Language / Selecione o Idioma:

O que é o ZapUnlocked-API?

O mercado de APIs para WhatsApp cobra mensalidades abusivas: dezenas a centenas de reais por mês, com limites de uso, taxas por conversa e dados que passam por servidores de terceiros. O ZapUnlocked-API existe pra mudar isso.

Construída em Python com Neonize como motor de conexão, esta API oferece uma interface REST simples (FastAPI) para gerenciar sessões, enviar mídias complexas e criar interações inteligentes. Sem banco de dados pesado, sem mensalidade, sem depender de ninguém.

Nossa proposta é fundamentada na excelência técnica e na independência do desenvolvedor. Acreditamos que ferramentas poderosas devem ser acessíveis a quem constrói suas próprias soluções.

Tip

Perfeito para desenvolvedores que buscam agilidade na integração de bots, notificações e sistemas de atendimento automatizados. Sem pagar nada por isso.

Note

A API foi internacionalizada, todas as respostas, mensagens de erro e interface web agora estão em Inglês.

🗺️ Visão Geral da API

mindmap
  root((⚡💬 ZapUnlocked-API))
    📨 Mensagens
      Texto
      Mídia
      Reações
      Localização
      Contatos
      Links
      Editar
      Deletar
      Ler

    🔘 Interativas
      Botões
      Listas
      OTP
      PIX
      Enquetes

    🔍 Consultas
      Contatos
      Histórico
      Chats
      Memória
      Disco
      Database
      Cleanup

    🔗 Conexão
      Status
      SSE
      QR Code
      PNG
      Pairing
      Logout

    📡 Webhooks
      Criar
      Listar
      Editar
      Deletar
      Ativar
      Testar
      40 Eventos

    ⚙️ Perfil
      Nome
      Foto
      Privacidade
      Visto
      Bloqueios

    🤖 Bot
      IA Tag
      Auto Read
      Rejeitar Calls

    🛡️ IP Rules
      Whitelist
      Blacklist

    📱 Instância
      Conta
      Dispositivo
      Renomear

    🖥️ Sistema
      Env Vars
      Media Cleanup
      Auto Cleanup
Loading

✨ Funcionalidades em Destaque

Funcionalidade Descrição
🧩 Botões Stateless Crie fluxos interativos sem banco de dados, com webhooks criptografados
🔢 Pareamento sem QR Code Conecte via código numérico · ideal para servidores sem GUI
🎵 Conversão Automática de Áudio Envie áudios que aparecem como gravados na hora (PTT) nativamente
📦 Fila de Mídias Inteligente Gerenciamento automático para evitar consumo excessivo de memória
🏷️ Placeholders Dinâmicos Personalize mensagens e webhooks com {{name}}, {{day}}, {{phone}}

Note

Todas as funcionalidades são 100% gratuitas e mantidas pela comunidade open-source.

📋 Rotas da API

📨 Envio de Mensagens · 15 endpoints
Método Rota Descrição Body
POST /send Enviar mensagem de texto / responder phone, message
POST /send_image Enviar imagem phone, image_url
POST /send_video Enviar vídeo (suporta GIF e PTV) phone, video_url
POST /send_audio Enviar áudio (com conversão automática para PTT) phone, audio_url
POST /send_document Enviar documento phone, document_url
POST /send_sticker Enviar figurinha phone, sticker_url
POST /send_reaction Enviar reação com emoji phone, messageId, emoji
POST /send_location Enviar localização phone, lat, lng
POST /send_contact Enviar contato phone, name, contactPhone
POST /send_contacts Enviar múltiplos contatos phone, contacts
POST /send_link Enviar link com preview phone, url
POST /messages/delete Deletar mensagem phone, messageId
POST /messages/read Marcar como lida phone, messageIds
POST /messages/edit Editar mensagem enviada phone, messageId, message
🔘 Mensagens Interativas · 7 endpoints
Método Rota Descrição Body
POST /messages/send-button-list Botão de lista de opções phone, buttons
POST /messages/send-button-actions Botão de ação phone, buttons
POST /messages/send-button-otp Botão de cópia (OTP) phone, code
POST /messages/send-button-pix Botão de PIX phone, pixKey
POST /messages/send-option-list Enviar lista de opções phone, buttons
POST /messages/send-poll Enviar enquete phone, name, options
POST /messages/send-poll-vote Votar em enquete phone, options
🔍 Consultas e Gestão · 8 endpoints
Método Rota Descrição Body
POST /management/fetch_messages Buscar histórico de mensagens phone
POST /management/recent_contacts Listar chats recentes ❌
GET /management/memory Status do uso de memória ❌
GET /management/volume_stats Verificar uso de disco ❌
DELETE /management/cleanup Limpar mídia temporária ❌
GET /management/database/status Status e estatísticas do banco ❌
POST /management/database/config Atualizar configurações do banco interval
POST /management/database/cleanup Limpeza manual do banco ❌
👤 Contatos · 1 endpoint
Método Rota Descrição Body
POST /contacts/info Informações detalhadas do contato phone
🏠 Geral · 3 endpoints
Método Rota Descrição Body
GET / Página de boas-vindas (HTML) ❌
GET /status Status da conexão e sessão (JSON) ❌
GET /status/stream Status em tempo real via SSE ❌
🔗 Conexão (QR) · 2 endpoints
Método Rota Descrição Body
GET /qr Visualizar QR Code interativo (HTML) ❌
GET /qr/image Obter imagem do QR Code (PNG) ❌
🔐 Sessão · 2 endpoints
Método Rota Descrição Body
POST /session/pair Gerar código de pareamento numérico phone
POST /session/logout Desconectar e resetar sessão ❌
📡 Webhooks (CRUD) · 8 endpoints
Método Rota Descrição Body
POST /webhooks Criar webhook nomeado name, url
GET /webhooks Listar todos os webhooks ❌
GET /webhooks/{name} Obter webhook por nome ❌
PUT /webhooks/{name} Editar webhook ❌
DELETE /webhooks/{name} Remover webhook ❌
POST /webhooks/{name}/toggle Ativar / desativar active
POST /webhooks/{name}/test Testar webhook ❌
GET /webhooks/events Listar tipos de eventos (40 tipos) ❌
⚙️ Perfil e Privacidade · 3 endpoints
Método Rota Descrição Body
POST /settings/profile Alterar nome e foto do bot ❌
POST /settings/privacy Ajustar privacidade (visto por último, etc) ❌
POST /settings/block Bloquear / desbloquear contato phone, action
🤖 Configurações do Bot · 6 endpoints
Método Rota Descrição Body
GET /settings/bot Ver configurações do bot ❌
POST /settings/bot Atualizar configurações (tag IA, IP control) ❌
PUT /settings/instance/call-reject-auto Rejeitar chamadas automaticamente value
PUT /settings/instance/call-reject-message Mensagem de chamada rejeitada value
PUT /settings/instance/auto-read-message Leitura automática de mensagens value
GET /settings/phone-code/{phone} Gerar código de pareamento por número ❌
📱 Instância · 3 endpoints
Método Rota Descrição Body
GET /instance/me Dados da conta conectada ❌
GET /instance/device Dados técnicos do dispositivo ❌
PUT /instance/update-name Renomear instância name
🛡️ Regras de IP · 5 endpoints
Método Rota Descrição Body
GET /settings/ip-rules Listar regras de IP (whitelist/blacklist) ❌
POST /settings/ip-rules/whitelist Adicionar IP à whitelist ip
POST /settings/ip-rules/blacklist Adicionar IP à blacklist ip
DELETE /settings/ip-rules/whitelist/{ip} Remover IP da whitelist ❌
DELETE /settings/ip-rules/blacklist/{ip} Remover IP da blacklist ❌
🖥️ Sistema · 5 endpoints
Método Rota Descrição Body
GET /system/env Ver variáveis de ambiente ❌
PUT /system/env Atualizar variáveis de ambiente ❌
POST /system/cleanup/force Limpeza forçada de mídia temporária ❌
GET /system/cleanup/settings Ver configurações de limpeza automática ❌
PUT /system/cleanup/settings Atualizar intervalo de limpeza automática ❌

Total: 68 endpoints

📡 Eventos de Webhook

Todos os webhooks recebem um envelope padrão:

{
  "event": "message.text",
  "timestamp": "2025-01-01T12:00:00Z",
  "data": { ... }
}

Se o webhook tiver um body customizado com {{placeholders}}, esse body é enviado em vez do envelope padrão.

🏷️ Placeholders disponíveis no body customizado
Placeholder Valor
{{from}} Número do remetente
{{text}} Texto da mensagem
{{phone}} Mesmo que {{from}}
{{id}} ID da mensagem
{{requested}} Quantidade solicitada (fetchMessages)
{{found}} Quantidade encontrada (fetchMessages)
{{timestamp}} Timestamp UTC atual
📥 Mensagens Recebidas · 16 eventos

Campos base presentes em eventos de mensagem recebida:

{
  "messageId": "3EB0ABCDEF123456",
  "from": "5511999999999",
  "fromName": "João Silva",
  "fromJid": "5511999999999@s.whatsapp.net",
  "isGroup": false
}
message.text - Texto simples / formatado 
{
  "event": "message.text",
  "data": {
    "...base": "...",
    "text": "Olá! Como posso ajudar?",
    "quoted": { "id": "3EB0...", "fromMe": true }
  }
}
message.image - Imagem recebida 
{
  "event": "message.image",
  "data": {
    "...base": "...",
    "caption": "Foto do produto",
    "mimetype": "image/jpeg",
    "fileLength": 204800
  }
}
message.video - Vídeo recebido 
{
  "event": "message.video",
  "data": {
    "...base": "...",
    "caption": "Veja esse vídeo!",
    "mimetype": "video/mp4",
    "fileLength": 5242880,
    "isPTT": false,
    "isGif": false
  }
}
message.audio - Áudio / nota de voz 
{
  "event": "message.audio",
  "data": {
    "...base": "...",
    "mimetype": "audio/ogg; codecs=opus",
    "fileLength": 30720,
    "isPTT": true,
    "durationSeconds": 8
  }
}
message.document - Documento / arquivo 
{
  "event": "message.document",
  "data": {
    "...base": "...",
    "fileName": "contrato.pdf",
    "caption": "Segue o contrato",
    "mimetype": "application/pdf",
    "fileLength": 102400
  }
}
message.sticker - Figurinha 
{
  "event": "message.sticker",
  "data": {
    "...base": "...",
    "mimetype": "image/webp",
    "isAnimated": false
  }
}
message.contact - Contato compartilhado 
{
  "event": "message.contact",
  "data": {
    "...base": "...",
    "displayName": "Maria Souza",
    "vcard": "BEGIN:VCARD\nVERSION:3.0\n..."
  }
}
message.location - Localização 
{
  "event": "message.location",
  "data": {
    "...base": "...",
    "lat": -23.5505,
    "lng": -46.6333,
    "name": "Av. Paulista",
    "address": "Av. Paulista, 1000 - São Paulo"
  }
}
message.reaction - Reação (emoji) 
{
  "event": "message.reaction",
  "data": {
    "...base": "...",
    "emoji": "❤️",
    "targetMessageId": "3EB0ABCDEF123456",
    "isRemoved": false
  }
}
message.poll_created - Enquete recebida 
{
  "event": "message.poll_created",
  "data": {
    "...base": "...",
    "pollName": "Qual o melhor sabor?",
    "options": ["Chocolate", "Morango", "Baunilha"]
  }
}
message.poll_vote - Voto em enquete 
{
  "event": "message.poll_vote",
  "data": {
    "...base": "...",
    "pollId": "3EB0ABCDEF123456",
    "selectedOptions": ["Chocolate"]
  }
}
message.button_reply - Clique em botão 
{
  "event": "message.button_reply",
  "data": {
    "...base": "...",
    "buttonId": "opcao_sim",
    "displayText": "Sim",
    "type": "quick_reply"
  }
}
message.list_reply - Seleção em lista interativa 
{
  "event": "message.list_reply",
  "data": {
    "...base": "...",
    "rowId": "1",
    "title": "X-Burguer",
    "description": "R$ 18,90"
  }
}
message.deleted - Mensagem apagada pelo remetente 
{
  "event": "message.deleted",
  "data": {
    "...base": "..."
  }
}
message.unknown - Tipo não mapeado 
{
  "event": "message.unknown",
  "data": {
    "...base": "...",
    "rawType": "senderKeyDistributionMessage"
  }
}
message.undecryptable - Mensagem não descriptografável 
{
  "event": "message.undecryptable",
  "data": {
    "...base": "..."
  }
}
📤 Mensagens Enviadas · 4 eventos
message.sent - Mensagem enviada (manual) 
{
  "event": "message.sent",
  "data": {
    "to": "5511999999999",
    "type": "text",
    "messageId": "3EB0ABCDEF123456"
  }
}
message.delivered - Mensagem entregue ao destinatário (receipt type 1) 
{
  "event": "message.delivered",
  "data": {
    "from": "5511999999999",
    "messageId": "3EB0ABCDEF123456"
  }
}
message.read - Mensagem lida pelo destinatário (receipt type 4) 
{
  "event": "message.read",
  "data": {
    "from": "5511999999999",
    "messageId": "3EB0ABCDEF123456"
  }
}
message.receipt - Outros tipos de confirmação (receipt types 2, 3, 5+) 
{
  "event": "message.receipt",
  "data": {
    "from": "5511999999999",
    "messageId": "3EB0ABCDEF123456",
    "receiptType": 2
  }
}
🔗 Conexão · 11 eventos
connection.connected - WhatsApp conectado 
{
  "event": "connection.connected",
  "data": {
    "phone": "5511999999999"
  }
}
connection.disconnected - WhatsApp desconectado 
{
  "event": "connection.disconnected",
  "data": {}
}
connection.qr_ready - QR Code gerado 
{
  "event": "connection.qr_ready",
  "data": {
    "qr": "2@abc123..."
  }
}
connection.pair_code - Código de pareamento gerado 
{
  "event": "connection.pair_code",
  "data": {
    "code": "NR62-NZSF"
  }
}
connection.pair_status - Status do pareamento 
{
  "event": "connection.pair_status",
  "data": {
    "status": "waiting",
    "phone": "5511999999999"
  }
}
connection.logged_out - Sessão encerrada remotamente 
{
  "event": "connection.logged_out",
  "data": {}
}
connection.connect_failure - Falha na conexão 
{
  "event": "connection.connect_failure",
  "data": {
    "reason": "network_error"
  }
}
connection.stream_error - Erro no stream 
{
  "event": "connection.stream_error",
  "data": {
    "error": "connection closed"
  }
}
connection.temporary_ban - Ban temporário 
{
  "event": "connection.temporary_ban",
  "data": {
    "phone": "5511999999999"
  }
}
connection.client_outdated - Cliente desatualizado 
{
  "event": "connection.client_outdated",
  "data": {}
}
connection.stream_replaced - Stream substituído 
{
  "event": "connection.stream_replaced",
  "data": {}
}
👥 Grupo · 2 eventos
group.join - Novo membro entrou no grupo 
{
  "event": "group.join",
  "data": {
    "groupId": "5511999999999-123456@g.us",
    "inviter": "5511888888888",
    "member": "5511999999999"
  }
}
group.update - Grupo atualizado 
{
  "event": "group.update",
  "data": {
    "groupId": "5511999999999-123456@g.us",
    "name": "Novo Nome",
    "updatedBy": "5511888888888"
  }
}
👤 Contato / Presença · 4 eventos
contact.presence - Status de presença do contato 
{
  "event": "contact.presence",
  "data": {
    "from": "5511999999999@s.whatsapp.net",
    "presence": "available",
    "lastSeen": 1700000000
  }
}
contact.chat_presence - Status de digitação 
{
  "event": "contact.chat_presence",
  "data": {
    "from": "5511999999999@s.whatsapp.net",
    "presence": "composing",
    "mediaType": 0
  }
}
contact.picture_change - Foto de perfil alterada 
{
  "event": "contact.picture_change",
  "data": {
    "from": "5511999999999@s.whatsapp.net",
    "pictureId": "abc123"
  }
}
contact.identity_change - Chave de segurança alterada 
{
  "event": "contact.identity_change",
  "data": {
    "from": "5511999999999@s.whatsapp.net"
  }
}
📞 Chamada · 3 eventos
call.received - Chamada recebida 
{
  "event": "call.received",
  "data": {
    "from": "5511999999999",
    "fromJid": "5511999999999@s.whatsapp.net",
    "callId": "ABC123DEF456"
  }
}
call.accepted - Chamada aceita 
{
  "event": "call.accepted",
  "data": {
    "from": "5511999999999",
    "callId": "ABC123DEF456"
  }
}
call.terminated - Chamada encerrada 
{
  "event": "call.terminated",
  "data": {
    "from": "5511999999999",
    "callId": "ABC123DEF456",
    "reason": "timeout"
  }
}

🛠️ Instalação e Hospedagem

Coloque sua API profissional de WhatsApp no ar em menos de 5 minutos com a ZapUnlocked-API.

💻 Instalação Local

Ideal para desenvolvimento, testes ou rodar em servidor próprio.

flowchart LR
  A[Clone] --> B[Install]
  B --> C[Config .env]
  C --> D[Run 🚀]
  D --> E[Config Account 🔗]
  E --> F[Production! ⚡]
Loading

1. Clone o Repositório

git clone https://github.com/kauafpssx/ZapUnlocked-API.git
cd ZapUnlocked-API

2. Instale as Dependências

Sistema Comando
🪟 Windows scripts\install\install.bat
🐧 Linux / macOS bash scripts/install/install.sh

3. Configure o Ambiente

Sistema Comando
🪟 Windows scripts\generate-env\generate-env.bat
🐧 Linux / macOS bash scripts/generate-env/generate-env.sh
Variável Descrição
API_KEY Senha para autenticação em todos os endpoints
INTERNAL_SECRET Token para validar assinaturas de webhook
PORT Porta da API (padrão: 8300)

4. Execute a API

Sistema Comando
🪟 Windows scripts\run\run.bat
🐧 Linux / macOS bash scripts/run/run.sh

☁️ Hospedagem: Alwaysdata (Grátis 24/7)

A Alwaysdata é a opção recomendada para hospedar a API de forma estável e gratuita sem precisar manter um servidor ligado.

📊 Recursos do Plano Free

Recurso Disponível no Free
💾 Armazenamento 1 GB SSD
🧠 RAM 256 MB
⚡ CPU 1/4 vCPU
🔄 Backup 3 dias automático
📡 Uptime 24/7 via Services

👣 Passo a Passo para Deploy

1. Crie sua conta em Alwaysdata.com · plano Free.

2. Acesse o SSH em https://ssh-[usuario].alwaysdata.net.

3. Clone e instale:

git clone https://github.com/kauafpssx/ZapUnlocked-API.git ~/ZapUnlocked-API
cd ~/ZapUnlocked-API
bash scripts/install/install.sh

4. (Opcional) Gere o .env:

bash scripts/generate-env/generate-env.sh

Note

O script de instalação já pergunta se deseja configurar o .env. Se respondeu sim, este passo pode ser pulado. Caso contrário, execute o comando acima ou configure o .env manualmente.

5. Configure o Serviço (24/7) em Advanced › Services › Add a service:

Campo Valor
Command bash scripts/run/run.sh
Working directory ZapUnlocked-API
Environment variables PORT=8300

6. Acesse via:

http://services-[usuario].alwaysdata.net:8300/

Tip

A URL já é acessível externamente. (Opcional) Para usar um domínio personalizado, configure um Reverse Proxy em Web › Sites › Add a site apontando para http://[usuario].alwaysdata.net.

🔐 Autenticação (Login)

Após o deploy, conecte sua conta do WhatsApp acessando no navegador:

http://services-[usuario].alwaysdata.net:8300/qr?API_KEY=SUA_SENHA_SECRETA

📖 Documentação Oficial

👉 zapunlocked-api.kauafpss.com.br

Para documentação técnica detalhada, exemplos de código e playground interativo, acesse nosso site oficial.

Tip

Use o LLMs.txt como índice para IA: zapunlocked-api.kauafpss.com.br/llms.txt. Descubra todas as páginas antes de explorar.

❤️ Créditos & Agradecimentos

Projeto Descrição
Neonize Biblioteca Python para conexão nativa com o WhatsApp Web
whatsmeow Biblioteca Go base do Neonize · o coração da conexão
Alwaysdata Infraestrutura gratuita de alta qualidade

📄 Licença

Este projeto é licenciado sob a Licença MIT.

Feito com 💜 por Kauã Ferreira

About

⚡💬 Free, self-hosted WhatsApp API built on Neonize. RESTful messaging, media, interactive buttons, polls, webhooks and automation. No cost, no limits.

zapunlocked-api.kauafpss.com.br

Topics

api chat open-source documentation json storage routes webhook self-hosted secure free whatsapp easy autentication whatsapp-api secured freehosting alwaysdata x-api-key neonize

Resources

Readme

License

MIT license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Contributors

Languages