Documentação da API

A API do LovaZero Zap envia e recebe mensagens de WhatsApp por HTTP. Cada instância é um número conectado pelo QR Code (ou código de pareamento) no painel, com uma chave própria. Tudo é JSON em UTF-8.

https://zap.lovazero.shop/api/v1

1. Compre uma ou mais instâncias no painel (PIX, ciclo de 30 dias).
2. Abra a instância e conecte o número lendo o QR Code no WhatsApp do celular.
3. Gere a chave da instância (ela aparece uma única vez) e guarde no seu servidor.
4. Chame as rotas abaixo com a chave no cabeçalho.

Toda chamada leva a chave da instância, de um destes dois jeitos (tanto faz qual):

Authorization: Bearer lzz_sua_chave_aqui
X-Api-Key: lzz_sua_chave_aqui

A chave identifica a instância: a URL nunca leva id de sessão. Com duas instâncias, você tem duas chaves e usa a de cada número. A chave começa com lzz_, aparece inteira só na hora em que é gerada e pode ser trocada no painel a qualquer momento; a antiga para de funcionar na hora.

Guarde a chave numa variável de ambiente do seu servidor (os exemplos usam LZZ_CHAVE). Não coloque a chave em código que roda no navegador: quem abrir o site copia a chave e, forjando o Origin, passa pela trava de domínio (veja Domínios, IPs e CORS).

Diz de qual instância é a chave e como ela está. Responde mesmo com a instância vencida, suspensa ou desconectada.

curl "https://zap.lovazero.shop/api/v1/instancia" \
  -H "Authorization: Bearer $LZZ_CHAVE"

{
  "id": "ins_4f9c2a7b1d3e",
  "nome": "Atendimento",
  "status": "conectada",
  "numero": "5511999999999",
  "expiraEm": "2026-10-30T14:02:11.000Z"
}

As rotas de mensagem apontam o destino pelo chatId:

• Contato: DDI + DDD + número, só dígitos, seguido de @c.us. Ex.: 5511988887777@c.us.
• Grupo: o id do grupo, que termina em @g.us. Ex.: 120363025246125486@g.us (pegue em listar grupos).

No Brasil, alguns números antigos estão no WhatsApp sem o nono dígito. Na dúvida, confira com Verificar número: ele devolve o whatsappId certo para usar como chatId.

Algumas mensagens recebidas podem trazer o remetente como …@lid (id de privacidade do WhatsApp). Nesses casos o webhook traz também senderPhone com o telefone, quando o WhatsApp revela (senão, null). Para um id avulso, use GET /contacts/{contactId}/phone.

A primeira conexão é feita no painel: ele cria a sessão e mostra o QR Code. Antes disso, as rotas respondem 409 instancia_nao_conectada. Depois, se o número cair, dá para pedir um novo QR ou um código de pareamento pela API.

QR Code

qrCode vem como imagem PNG em data URL (pode ir direto num <img src>). O QR muda a cada poucos segundos; consulte de novo enquanto o status for qr_ready.

curl "https://zap.lovazero.shop/api/v1/qr" \
  -H "Authorization: Bearer $LZZ_CHAVE"

{
  "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA…",
  "status": "qr_ready"
}

Código de pareamento

Alternativa ao QR: no celular, abra WhatsApp → Aparelhos conectados → Conectar aparelho → Conectar com número de telefone e digite o código de 8 caracteres.

curl -X POST "https://zap.lovazero.shop/api/v1/pairing-code" \
  -H "Authorization: Bearer $LZZ_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "5511999999999"
  }'

{
  "pairingCode": "K7Q2M9XD",
  "status": "qr_ready"
}

Ligar, parar e sair

Status da sessão nessas respostas: created, initializing, qr_ready, authenticating, ready, disconnected, action_required ou failed.

curl -X POST "https://zap.lovazero.shop/api/v1/messages/send-text" \
  -H "Authorization: Bearer $LZZ_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "5511988887777@c.us",
    "text": "Olá, Maria! Seu pedido saiu para entrega."
  }'

{
  "messageId": "3EB0C767D26B8A3F1A2B",
  "timestamp": 1790776931
}

Guarde o messageId: é com ele que você reage, responde, apaga ou acompanha a entrega (evento message.ack).

curl -X POST "https://zap.lovazero.shop/api/v1/messages/send-image" \
  -H "Authorization: Bearer $LZZ_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "5511988887777@c.us",
    "url": "https://meusite.com.br/catalogo/tenis-azul.jpg",
    "caption": "Chegou o azul no seu número!"
  }'

{
  "messageId": "3EB0C767D26B8A3F1A2B",
  "timestamp": 1790776931
}

Prefira url: o corpo fica pequeno e o servidor baixa o arquivo. Em base64, o arquivo cresce cerca de um terço.

Mesmos campos da imagem. Informe filename para o arquivo chegar com nome.

curl -X POST "https://zap.lovazero.shop/api/v1/messages/send-document" \
  -H "Authorization: Bearer $LZZ_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "5511988887777@c.us",
    "url": "https://meusite.com.br/boletos/2026-10.pdf",
    "mimetype": "application/pdf",
    "filename": "boleto-outubro.pdf",
    "caption": "Seu boleto de outubro."
  }'

{
  "messageId": "3EB0C767D26B8A3F1A2B",
  "timestamp": 1790776931
}

Mesmos campos da imagem, mais ptt. Com "ptt": true o áudio chega como mensagem de voz (a bolinha do microfone); sem ele, como arquivo de áudio.

curl -X POST "https://zap.lovazero.shop/api/v1/messages/send-audio" \
  -H "Authorization: Bearer $LZZ_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "5511988887777@c.us",
    "url": "https://meusite.com.br/audios/boas-vindas.ogg",
    "mimetype": "audio/ogg; codecs=opus",
    "ptt": true
  }'

{
  "messageId": "3EB0C767D26B8A3F1A2B",
  "timestamp": 1790776931
}

Mesmos campos da imagem. Use MP4 (H.264 + AAC), o formato que o WhatsApp toca em todos os aparelhos.

curl -X POST "https://zap.lovazero.shop/api/v1/messages/send-video" \
  -H "Authorization: Bearer $LZZ_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "5511988887777@c.us",
    "url": "https://meusite.com.br/videos/como-usar.mp4",
    "caption": "Veja como usar em 1 minuto."
  }'

{
  "messageId": "3EB0C767D26B8A3F1A2B",
  "timestamp": 1790776931
}

Responde citando uma mensagem (o balão da original aparece em cima).

curl -X POST "https://zap.lovazero.shop/api/v1/messages/reply" \
  -H "Authorization: Bearer $LZZ_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "5511988887777@c.us",
    "quotedMessageId": "3EB0C767D26B8A3F1A2B",
    "text": "Abrimos sim, das 9h às 13h."
  }'

{
  "messageId": "3EB0C767D26B8A3F1A2B",
  "timestamp": 1790776931
}

Manda o “visto” (os dois tiques azuis) para quem escreveu.

curl -X POST "https://zap.lovazero.shop/api/v1/chats/read" \
  -H "Authorization: Bearer $LZZ_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "5511988887777@c.us",
    "messageIds": [
      "3EB0C767D26B8A3F1A2B"
    ]
  }'

{
  "success": true
}

curl -X POST "https://zap.lovazero.shop/api/v1/messages/delete" \
  -H "Authorization: Bearer $LZZ_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "5511988887777@c.us",
    "messageId": "3EB0C767D26B8A3F1A2B",
    "forEveryone": true
  }'

{
  "success": true
}

O WhatsApp só deixa apagar para todos por um tempo depois do envio; passado esse prazo, a mensagem continua para quem recebeu.

Diz se um telefone tem WhatsApp e devolve o whatsappId para usar como chatId. Número só com dígitos e DDI.

curl "https://zap.lovazero.shop/api/v1/contacts/check/5511988887777" \
  -H "Authorization: Bearer $LZZ_CHAVE"

{
  "number": "5511988887777",
  "exists": true,
  "whatsappId": "5511988887777@c.us"
}

Sem WhatsApp: "exists": false e "whatsappId": null. Não use esta rota para varrer listas de números: o WhatsApp trata isso como comportamento suspeito.

Conversas ativas, com não lidas e última mensagem. Pagine com limit e offset. timestamp é em segundos.

curl "https://zap.lovazero.shop/api/v1/chats?limit=20&offset=0" \
  -H "Authorization: Bearer $LZZ_CHAVE"

[
  {
    "id": "5511988887777@c.us",
    "name": "Maria",
    "isGroup": false,
    "kind": "individual",
    "unreadCount": 2,
    "timestamp": 1790776931,
    "lastMessage": "Vocês abrem sábado?",
    "archived": false,
    "pinned": false,
    "muted": false
  }
]

Mensagens que o motor guardou desta instância, da mais nova para a mais antiga.

curl "https://zap.lovazero.shop/api/v1/messages?chatId=5511988887777@c.us&limit=50" \
  -H "Authorization: Bearer $LZZ_CHAVE"

{
  "messages": [
    {
      "id": "0a941dac-a965-45e7-b318-74ae8be134f0",
      "waMessageId": "3EB0C767D26B8A3F1A2B",
      "chatId": "5511988887777@c.us",
      "chatName": "Maria",
      "from": "5511999999999@c.us",
      "to": "5511988887777@c.us",
      "body": "Olá, Maria! Seu pedido saiu para entrega.",
      "type": "text",
      "direction": "outgoing",
      "timestamp": 1790776931,
      "status": "delivered",
      "createdAt": "2026-09-30T14:02:11.000Z"
    }
  ],
  "total": 1
}

Aqui o id é o registro interno; para reagir, responder ou apagar use o waMessageId. Mensagens com mídia trazem o arquivo em GET /messages/{chatId}/{messageId}/media.

curl "https://zap.lovazero.shop/api/v1/groups" \
  -H "Authorization: Bearer $LZZ_CHAVE"

[
  {
    "id": "120363025246125486@g.us",
    "name": "Clientes VIP",
    "linkedParentJID": null
  }
]

curl -X POST "https://zap.lovazero.shop/api/v1/groups" \
  -H "Authorization: Bearer $LZZ_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Clientes VIP",
    "participants": [
      "5511988887777@c.us",
      "5511977776666@c.us"
    ]
  }'

{
  "id": "120363025246125486@g.us",
  "name": "Clientes VIP",
  "participantsCount": 3,
  "isAdmin": true
}

Detalhes (participantes, admins, configurações): GET /groups/{groupId}. Link de convite: GET /groups/{groupId}/invite-code.

Todas recebem {"participants": [chatIds]} (até 256) e respondem o resultado de cada um. O número da instância precisa ser admin do grupo.

curl -X POST "https://zap.lovazero.shop/api/v1/groups/120363025246125486@g.us/participants" \
  -H "Authorization: Bearer $LZZ_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "participants": [
      "5511966665555@c.us"
    ]
  }'

{
  "success": true,
  "message": "Participants added",
  "results": [
    {
      "id": "5511966665555@c.us",
      "success": true,
      "status": 200,
      "message": "ok"
    }
  ]
}

Um item pode falhar sozinho (ex.: a pessoa só aceita entrar por convite): confira results[].success de cada número.

Webhook é o endereço do seu sistema que recebe um POST a cada evento (mensagem nova, entrega, conexão…). Há dois jeitos de configurar:

• No painel (Instância → Webhook): URL e eventos. Simples, sem assinatura.
• Pela API: além de URL e eventos, aceita secret (assina cada entrega), cabeçalhos próprios e número de tentativas. Pode ter mais de um por instância.

curl -X POST "https://zap.lovazero.shop/api/v1/webhooks" \
  -H "Authorization: Bearer $LZZ_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://meusite.com.br/webhook/whatsapp",
    "events": [
      "message.received",
      "message.ack",
      "session.status"
    ],
    "secret": "troque-por-um-segredo-longo-e-aleatorio"
  }'

{
  "id": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
  "sessionId": "8f14e45f-ceea-4c6b-9a3e-2d0c7b1e5a90",
  "url": "https://meusite.com.br/webhook/whatsapp",
  "events": [
    "message.received",
    "message.ack",
    "session.status"
  ],
  "filters": null,
  "active": true,
  "retryCount": 3,
  "lastTriggeredAt": null,
  "createdAt": "2026-09-30T14:02:11.000Z",
  "updatedAt": "2026-09-30T14:02:11.000Z"
}

Toda entrega tem o mesmo envelope; o que muda é o data. Exemplo de mensagem recebida:

{
  "event": "message.received",
  "timestamp": "2026-09-30T14:02:11.418Z",
  "sessionId": "8f14e45f-ceea-4c6b-9a3e-2d0c7b1e5a90",
  "idempotencyKey": "msg_8f14e45f-ceea-4c6b-9a3e-2d0c7b1e5a90_3EB0A1B2C3D4E5F60718_d2f1c3b4-5a6e-4f70-8a91-b2c3d4e5f607",
  "deliveryId": "dlv_550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "id": "3EB0A1B2C3D4E5F60718",
    "from": "5511988887777@c.us",
    "to": "5511999999999@c.us",
    "chatId": "5511988887777@c.us",
    "body": "Oi! Vocês abrem sábado?",
    "type": "text",
    "timestamp": 1790776931,
    "fromMe": false,
    "isGroup": false,
    "kind": "individual",
    "isStatusBroadcast": false,
    "contact": {
      "pushName": "Maria"
    }
  }
}

• data.id é o id da mensagem: use em reagir, responder, apagar e marcar como lida. data.timestamp é em segundos; o timestamp de fora é a hora do envio do webhook.
• sessionId é o id interno da sessão no motor (fixo por instância). Para separar números, use endereços diferentes ou guarde esse id.
• Em grupo, chatId é o grupo e author é quem escreveu. Mensagens com mídia trazem media com mimetype e o arquivo em data (base64) quando é pequeno; arquivos maiores chegam com "omitted": true e você baixa em GET /messages/{chatId}/{messageId}/media.

Cabeçalhos de cada entrega

Com secret, cada entrega leva X-OpenWA-Signature: sha256=<hex>: um HMAC-SHA256 dos bytes exatos do corpo, usando o seu segredo. Calcule sobre o corpo cru (não sobre o JSON já convertido e reescrito) e compare em tempo constante. Sem secret, o cabeçalho não vem.

import crypto from "node:crypto";
import express from "express";


const app = express();


// A assinatura é sobre os bytes exatos do corpo: leia o corpo CRU.
app.post("/webhook/whatsapp", express.raw({ type: "application/json" }), (req, res) => {
  const recebida = Buffer.from(req.get("X-OpenWA-Signature") ?? "");
  const esperada = Buffer.from(
    "sha256=" + crypto.createHmac("sha256", process.env.LZZ_WEBHOOK_SEGREDO).update(req.body).digest("hex"),
  );
  if (recebida.length !== esperada.length || !crypto.timingSafeEqual(recebida, esperada)) {
    return res.sendStatus(401);
  }


  const evento = JSON.parse(req.body.toString("utf8"));
  if (evento.event === "message.received" && !evento.data.fromMe) {
    console.log(evento.data.chatId, evento.data.body);
  }
  res.sendStatus(200); // responda rápido; trabalho pesado vai para uma fila
});


app.listen(3000);

import hashlib
import hmac
import os


from flask import Flask, abort, request


app = Flask(__name__)
SEGREDO = os.environ["LZZ_WEBHOOK_SEGREDO"].encode()




@app.post("/webhook/whatsapp")
def webhook():
    corpo = request.get_data()  # bytes exatos do corpo
    esperada = "sha256=" + hmac.new(SEGREDO, corpo, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(request.headers.get("X-OpenWA-Signature", ""), esperada):
        abort(401)


    evento = request.get_json()
    if evento["event"] == "message.received" and not evento["data"]["fromMe"]:
        print(evento["data"]["chatId"], evento["data"]["body"])
    return "", 200

Erros da nossa porta de entrada vêm no formato {"erro": "codigo", "detalhe": "frase pronta"}. O detalhe pode ser mostrado ao usuário; decida pelo erro.

{
  "erro": "instancia_expirada",
  "detalhe": "Esta instância venceu em 30/09/2026. Renove no painel."
}

A ordem das checagens é: chave (401) → suspensa (403) → vencida (402) → conectada (409) → domínio/IP (403) → limite (429). Toda resposta leva X-Request-Id; mande esse valor quando falar com o suporte.

Erros do WhatsApp

Passando pela porta de entrada, a resposta vem do motor do WhatsApp, com o formato dele:

{
  "statusCode": 400,
  "message": [
    "text should not be empty"
  ],
  "error": "Bad Request"
}

• 400: corpo inválido: campo obrigatório faltando, tipo errado ou campo que não existe (campos a mais são recusados). Também quando a sessão ainda não está ativa.
• 404: grupo, mensagem ou contato não encontrado.
• 409: a sessão não está pronta (conectando, sem internet no aparelho). Pode tentar de novo.
• 501: o recurso não existe no motor Baileys (marcado em Todas as rotas).

No painel, cada instância pode limitar de onde vêm as chamadas. Lista vazia = sem restrição. Com regras, a chamada passa se bater em qualquer uma:

• Domínios: comparados com o Origin da chamada (ou o Referer, se não houver Origin), sem porta nem esquema. *.meusite.com.br vale para os subdomínios, não para meusite.com.br: cadastre os dois se precisar.
• IPs: IPv4 ou IPv6 exatos, ou faixa IPv4 em CIDR (ex.: 198.51.100.0/24).
• Até 20 domínios e 20 IPs por instância. Recusa = 403 origem_nao_autorizada.

CORS

O OPTIONS (preflight) responde 204 liberando Authorization, X-Api-Key e Content-Type. A resposta de verdade só leva Access-Control-Allow-Origin quando a chamada passou pelas restrições; aí também expõe X-Request-Id, Retry-After e Content-Disposition. Lembre: chave usada no navegador fica visível para quem abrir o site. Sempre que der, chame a API do seu servidor.

Esses limites protegem o serviço. Quem decide se o número é banido é o WhatsApp: mandar muitas mensagens iguais para quem não pediu é o caminho mais rápido para perder o número. Espalhe os envios no tempo e fale com quem quer ouvir de você.

Tudo o que a API aceita. Cada caminho vem depois de /api/v1 e usa a chave da instância, como nos exemplos acima. Qualquer outro caminho responde 404 rota_desconhecida.