Lobato API

GET /docs

Referência da API em HTML, para leitura humana (esta página). Sem auth.

GET /llms.txt

A mesma referência em Markdown puro, servida como text/plain. Sem auth.

GET /docs.md

Atalho para GET /llms.txt — conteúdo idêntico, servido como text/markdown em vez de text/plain (para ferramentas que esperam um .md irmão de uma página HTML de docs). Sem auth.

GET /docs/explorer

Explorador de API interativo (Redoc), renderizado no navegador a partir do spec OpenAPI abaixo — navegue pelo schema completo de request/response de cada endpoint numa única página com busca. Sem auth.

GET /openapi.yaml

O spec OpenAPI 3 puro que descreve esta API — a mesma fonte que o explorador acima lê. Importe direto no Postman, Insomnia, ou qualquer cliente compatível com openapi-generator. Sem auth.

Criar uma instância

Cria uma instância e retorna sua API key. Guarde-a imediatamente de qualquer forma — se dá pra buscá-la de novo depois via GET /instances/{id}/api-key depende da configuração do servidor, então não conte com isso.

{
  "name": "vendas-01",
  "owner": { "name": "Cliente Acme", "email": "optional@example.com" },
  "syncFullHistory": false
}

name e owner.name obrigatórios (1–100 caracteres). owner.email opcional, validado como email. Se já existir um dono com esse name exato, ele é reaproveitado; senão, é criado. syncFullHistory opcional (padrão false) — veja Atualizar configurações.

Resposta 201:

{
  "id": "clx1a2b3c...",
  "name": "vendas-01",
  "status": "disconnected",
  "phoneNumber": null,
  "createdAt": "2026-07-01T12:00:00.000Z",
  "connectedAt": null,
  "owner": { "id": "...", "name": "Cliente Acme", "email": "optional@example.com" },
  "apiKey": "a-api-key-da-instância-mostrada-só-agora"
}

curl -X POST "$BASE/api/instances" \
  -H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{"name":"vendas-01","owner":{"name":"Cliente Acme"}}'

Listar instâncias

Resposta: { "instances": [Instance, ...] } (mesmo formato do create, sem o apiKey).

Paginação é opcional: omita limit e todas as instâncias voltam, mais recente primeiro. Passe limit (máx. 2000) e before (do nextCursor da página anterior) pra paginar.

Listar donos

Resposta: { "owners": [{ "id", "name", "email" }, ...] }. Mesma paginação opcional, ordenado alfabeticamente por nome.

Consultar instância

Retorna o objeto Instance (sem apiKey). 404 NOT_FOUND se não existir.

Excluir instância

Remove a instância por completo: sessão + todas as linhas no banco (mensagens, contatos, grupos, webhooks). Irreversível. Resposta: { "removed": true }.

Conectar / obter QR code

Inicia a conexão (ou reconecta com uma sessão ainda válida). Espera até ~15s no servidor por um QR ou pela conexão completa antes de responder — chame de novo se ainda estiver connecting.

{ "status": "connected", "phoneNumber": "5511999999999" }
{ "status": "qr_pending", "qr": "data:image/png;base64,..." }
{ "status": "connecting" }

curl "$BASE/api/instances/$INSTANCE_ID/connect" -H "Authorization: Bearer $INSTANCE_KEY"

Reconectar

Destrava uma instância (ex.: presa em connecting) derrubando o socket/timer atual e começando uma tentativa nova, sem excluir a instância. Mesmos formatos de resposta e tempo de espera do Conectar acima.

{ "wipeSession": false }

wipeSession: true também apaga a sessão salva, forçando um pareamento por QR totalmente novo em vez de retomar o existente — use quando suspeitar que a própria sessão está corrompida.

curl -X POST "$BASE/api/instances/$INSTANCE_ID/reconnect" \
  -H "Authorization: Bearer $INSTANCE_KEY" -H "Content-Type: application/json" \
  -d '{"wipeSession": true}'

Conectar com código de pareamento

Alternativa ao pareamento por QR: conecta pelo código de 8 caracteres mostrado no app em Aparelhos conectados → Conectar com número de telefone. Sempre apaga qualquer sessão existente antes (só faz sentido pra um aparelho ainda não registrado). Espera até ~20s.

{ "phoneNumber": "5511999998888" }

phoneNumber: só dígitos, 8 a 15, com código do país incluído, sem +, espaços ou pontuação.

{ "status": "qr_pending", "pairingCode": "ABCD1234", "phoneNumber": "5511999998888" }

curl -X POST "$BASE/api/instances/$INSTANCE_ID/connect/pairing-code" \
  -H "Authorization: Bearer $INSTANCE_KEY" -H "Content-Type: application/json" \
  -d '{"phoneNumber":"5511999998888"}'

Status da conexão

Lido do Redis, com fallback pro MySQL se o Redis estiver fora.

{ "status": "connected", "phoneNumber": "5511999999999", "connectedAt": "2026-07-01T12:00:00.000Z" }

status: um de connecting, connected, disconnected, qr_pending. 404 se a instância não existir.

Atualizar configurações

Todo campo é opcional — envie só o que você está mudando.

{
  "syncFullHistory": true,
  "autoMarkRead": true,
  "metaAdsEnabled": true,
  "metaAdsToken": "EAAG..."
}

syncFullHistory: se um novo pareamento pede o histórico completo de mensagens em vez de só as conversas recentes. Vale a partir do próximo pareamento por QR/código.

autoMarkRead: marca toda mensagem recebida como lida (tique azul) assim que chega. Vale imediatamente.

metaAdsEnabled / metaAdsToken: enriquece mensagens de anúncio Click-to-WhatsApp via Marketing API da Meta. metaAdsToken é write-only (nunca é retornado — a resposta só informa metaAdsTokenConfigured); envie "" pra limpar. Exige API_KEY_ENCRYPTION_SECRET configurado no servidor, senão 503 ENCRYPTION_NOT_CONFIGURED.

Resposta: o objeto da instância atualizado.

Logout

Desconecta a sessão mas mantém o registro da instância (e a API key) — chame /connect de novo depois pra parear novamente. Resposta: { "status": "disconnected" }.

Gerar nova API key

Gera uma nova API key pra instância; a antiga para de funcionar na hora. Resposta: { "apiKey": "nova-chave" }.

Ver API key atual

Retorna a API key atual da instância — não gera uma nova.

{ "apiKey": "wa_..." }

Verificar número(s)

Verifica se números de telefone estão registrados no WhatsApp antes de enviar mensagem.

{ "numbers": ["5511999999999", "5511888888888"] }

{ "results": [ { "number": "5511999999999", "exists": true, "jid": "5511999999999@s.whatsapp.net" } ] }

jid está sempre no formato de número de telefone (nunca @lid) — veja Garantia de formato do JID. jid é null quando exists é false.

curl -X POST "$BASE/api/instances/$INSTANCE_ID/check-number" \
  -H "Authorization: Bearer $INSTANCE_KEY" -H "Content-Type: application/json" \
  -d '{"numbers":["5511999999999"]}'

Definir / remover a própria foto de perfil

Define ou remove a foto de perfil do WhatsApp desta instância. PUT aceita o mesmo formato de entrada dos endpoints de envio de mídia — multipart/form-data (uma parte file) ou um corpo JSON com um campo url.

Resposta do PUT: { "updated": true }. Resposta do DELETE: { "removed": true }. Ambos retornam 409 INSTANCE_NOT_CONNECTED se não estiver conectada.

curl -X PUT "$BASE/api/instances/$INSTANCE_ID/profile-picture" \
  -H "Authorization: Bearer $INSTANCE_KEY" \
  -F "file=@/path/avatar.jpg"

Definir o próprio nome de exibição

{ "name": "Acme Support" }

name obrigatório, não vazio. Resposta: { "updated": true }.

Definir o próprio status/recado

{ "status": "Atendimento 9h-18h" }

status obrigatório, mas "" é válido e limpa o campo. Resposta: { "updated": true }.

Enviar texto

{ "to": "5511999999999", "text": "Olá!" }

to/text são obrigatórios; mentions é opcional (ver callout acima). Resposta 200:

{ "messageId": "3EB0...", "key": { "remoteJid": "5511999999999@s.whatsapp.net", "id": "3EB0...", "fromMe": true } }

curl -X POST "$BASE/api/instances/$INSTANCE_ID/messages/text" \
  -H "Authorization: Bearer $INSTANCE_KEY" -H "Content-Type: application/json" \
  -d '{"to":"5511999999999","text":"Olá!"}'

Enviar mídia: imagem / vídeo / áudio / documento

Os quatro aceitam ou multipart/form-data (parte file + campos) ou um corpo JSON com um campo url. Mesmo formato de resposta do texto.

• image: file ou url, caption opcional.
• video: file ou url, caption opcional, ptv opcional (nota em vídeo).
• audio: file ou url. Sempre enviado como nota de voz — qualquer formato de entrada é aceito (mp3, wav, m4a, ogg...), convertido pra OGG/Opus. Falha com 500 FFMPEG_UNAVAILABLE se o servidor não tiver ffmpeg, ou 500 AUDIO_CONVERSION_FAILED se o upload não for decodificável como áudio.
• document: file ou url, obrigatório fileName (a menos que a parte file já traga um), mimetype opcional, caption opcional.

# via URL pública (JSON)
curl -X POST "$BASE/api/instances/$INSTANCE_ID/messages/image" \
  -H "Authorization: Bearer $INSTANCE_KEY" -H "Content-Type: application/json" \
  -d '{"to":"5511999999999","url":"https://example.com/foto.jpg","caption":"Olha isso"}'

# via upload multipart
curl -X POST "$BASE/api/instances/$INSTANCE_ID/messages/image" \
  -H "Authorization: Bearer $INSTANCE_KEY" \
  -F "to=5511999999999" -F "caption=Olha isso" -F "file=@/path/foto.jpg"

# áudio -- qualquer formato funciona; o servidor converte pra OGG/Opus automaticamente
curl -X POST "$BASE/api/instances/$INSTANCE_ID/messages/audio" \
  -H "Authorization: Bearer $INSTANCE_KEY" \
  -F "to=5511999999999" -F "file=@/path/audio.mp3"

# documento
curl -X POST "$BASE/api/instances/$INSTANCE_ID/messages/document" \
  -H "Authorization: Bearer $INSTANCE_KEY" -H "Content-Type: application/json" \
  -d '{"to":"5511999999999","url":"https://example.com/contrato.pdf","fileName":"contrato.pdf"}'

Enviar mais de uma parte file manda cada uma como mensagem separada (espaçadas ~1,2s). A resposta vira { "results": [...] }, uma entrada por arquivo.

Enviar localização

{ "to": "5511999999999", "latitude": -23.55, "longitude": -46.63, "name": "São Paulo" }

to, latitude, longitude obrigatórios; name e quotedMessageId opcionais. Resposta: { "messageId", "key" }.

Enviar botões

Envia uma mensagem interativa com 1 a 3 botões.

{
  "to": "5511999999999",
  "text": "Como podemos ajudar?",
  "footer": "Responda em até 24h",
  "buttons": [
    { "type": "reply", "id": "opt1", "displayText": "Falar com vendas" },
    { "type": "url", "displayText": "Ver catálogo", "url": "https://exemplo.com/catalogo" },
    { "type": "call", "displayText": "Ligar agora", "phoneNumber": "5511999999999" },
    { "type": "copy", "displayText": "Copiar cupom", "copyCode": "PROMO10" }
  ]
}

O type de cada botão determina os outros campos obrigatórios — reply precisa de id+displayText; url precisa de displayText+url; call precisa de displayText+phoneNumber; copy precisa de displayText+copyCode. Máximo de 3 botões. Não aceita quotedMessageId. Resposta: { "messageId", "key" }.

Enviar produto do catálogo

Envia um "cartão" de produto numa conversa — diferente de /catalog/products (que cria/edita/remove produtos no catálogo em si). A imagem pode vir como upload multipart ou pelo campo imageUrl (JSON); só aceita uma imagem.

{
  "to": "5511999999999",
  "title": "Camiseta Preta M",
  "description": "100% algodão",
  "price": 49.9,
  "currency": "BRL",
  "imageUrl": "https://exemplo.com/camiseta.jpg",
  "url": "https://exemplo.com/produtos/camiseta-preta-m"
}

to e title obrigatórios. price é decimal em unidade "normal" da moeda (ex: 49.9 para R$49,90) — não é o mesmo formato inteiro que price usa em /catalog/products. url é o link do produto no catálogo/loja (mostrado no cartão); imageUrl é a URL da imagem em si, propositalmente um campo separado pra nunca se confundir com url. productId (id do produto no catálogo do WhatsApp) e retailerId (id próprio do lojista) são opcionais e independentes — nenhum dos dois é obrigatório pra mandar o cartão. businessOwnerJid é opcional, usa o jid da própria instância por padrão. body/footer aparecem como texto abaixo do cartão. Resposta: { "messageId", "key" }.

Editar uma mensagem enviada

{ "remoteJid": "5511999999999@s.whatsapp.net", "text": "preço correto: R$ 79,90" }

remoteJid e text obrigatórios. Só funciona numa mensagem que esta instância mesma enviou e ainda tem registrada — senão, 404.

Resposta: { "edited": true }.

Apagar mensagem (para todos)

Exige o parâmetro de query remoteJid. Parâmetro fromMe opcional ("true"/"false", padrão "true").

Resposta: { "deleted": true }.

curl -X DELETE "$BASE/api/instances/$INSTANCE_ID/messages/$MSG_ID?remoteJid=5511999999999@s.whatsapp.net" \
  -H "Authorization: Bearer $INSTANCE_KEY"

Reagir a uma mensagem

{ "remoteJid": "5511999999999@s.whatsapp.net", "emoji": "👍", "fromMe": false }

remoteJid e emoji obrigatórios. emoji: "" remove uma reação existente. fromMe opcional, padrão false. Resposta: { "messageId", "key" } (a key da própria reação).

Marcar mensagens como lidas

{ "keys": [ { "remoteJid": "5511999999999@s.whatsapp.net", "id": "3EB0...", "fromMe": false } ] }

keys obrigatório, mínimo 1. Resposta: { "marked": 1 } (quantidade enviada).

Histórico de mensagens da conversa

Histórico paginado do próprio log desta API (não é uma busca ao vivo no WhatsApp). chatJid aceita um número de telefone puro, um JID de número, ou um JID de grupo.

Query: limit (padrão 50, máx. 100), before (data/hora ISO 8601).

{ "messages": [ /* mais recentes primeiro */ ], "nextCursor": "2026-06-30T09:00:00.000Z" }

nextCursor é null quando não há mais histórico, senão é o createdAt da linha mais antiga — passe como before pra pegar a próxima página.

Importar por telefone

Exportação em massa do histórico completo de um número, do mais antigo pro mais recente. phone aceita um número puro, um JID de número, ou um JID de grupo.

Query: limit (padrão 2000, máx. 5000), since (data/hora ISO 8601).

{ "phone": "5511999999999", "chatJid": "5511999999999@s.whatsapp.net", "count": 2000, "truncated": true, "nextSince": "2026-06-30T09:00:00.000Z", "messages": [ /* mais antigas primeiro */ ] }

Quando truncated é true, passe nextSince de volta como since pra pegar a próxima página.

Definir a própria presença

{ "presence": "composing", "to": "5511999999999" }

presence: um de composing, recording, available, unavailable. to obrigatório para composing/recording. Resposta: { "ok": true }.

Assinar presença de um contato

{ "jid": "5511999999999" }

As atualizações de presença desse contato passam a chegar pelo evento de webhook presence.update. Resposta: { "subscribed": true }.

Criar grupo

{ "name": "Time de Vendas", "participants": ["5511999999999", "5511888888888"] }

name obrigatório (1–150 caracteres). participants obrigatório, mínimo 1. Resposta 201: GroupMetadata completo.

Listar grupos

Todos os grupos em que esta instância participa. Cache de ~45s no Redis.

{ "groups": [ /* GroupMetadata, ... */ ] }

Listar grupos com mensagens

Lista os grupos sincronizados no MySQL e anexa as mensagens persistidas de cada um. Não é uma busca ao vivo no WhatsApp, não exige o socket conectado.

Query: limit (padrão 1000, mín. 1, máx. 1000, mensagens por grupo; messageLimit aceito como apelido), before (ISO 8601). groupLimit/groupBefore limitam separadamente quantos grupos são retornados (opcional, sem padrão).

{
  "groups": [
    {
      "id": "1",
      "groupJid": "123456789-1600000000@g.us",
      "name": "Time de Vendas",
      "syncedAt": "2026-07-01T12:00:00.000Z",
      "messages": [ /* mais recentes primeiro */ ],
      "nextCursor": "2026-06-30T09:00:00.000Z"
    }
  ]
}

curl "$BASE/api/instances/$INSTANCE_ID/groups/messages?groupLimit=50" \
  -H "Authorization: Bearer $INSTANCE_KEY"

Obter mensagens de um grupo

Mesma fonte/semântica do endpoint acima, pra um único grupo. 404 se o grupo não estiver sincronizado. Cada mensagem inclui senderName, senderNumber, senderJid, e mediaUrl quando disponível.

Query: limit (padrão 1000, mín. 1, máx. 1000), before.

{
  "id": "1",
  "groupJid": "123456789-1600000000@g.us",
  "name": "Time de Vendas",
  "messages": [
    {
      "waMessageId": "3EB0...",
      "senderJid": "5511999999999@s.whatsapp.net",
      "senderNumber": "5511999999999",
      "senderName": "Maria Sender",
      "mediaUrl": "https://api.example.com/media/2026/07/file.jpg"
    }
  ],
  "nextCursor": null
}

Sincronização de histórico do grupo sob demanda

Pede ao WhatsApp mensagens mais antigas deste grupo, ancoradas na mensagem mais antiga já persistida. Sem corpo na requisição. 404 se o grupo ainda não estiver sincronizado; 400 se não houver nenhuma mensagem já persistida pra ancorar.

Os resultados chegam de forma assíncrona pelo evento de webhook messaging-history.set e são persistidos do mesmo jeito que a sincronização inicial — este endpoint só dispara o pedido.

{ "status": "requested", "anchor": { "waMessageId": "3EB0...", "createdAt": "2026-06-30T09:00:00.000Z" } }

Consultar metadados do grupo

Cache de ~60s no Redis. 409 INSTANCE_NOT_CONNECTED se não estiver conectada.

{
  "id": "123456789-1600000000@g.us",
  "subject": "Time de Vendas",
  "owner": "5511999999999@s.whatsapp.net",
  "desc": "Descrição do grupo",
  "participants": [
    { "id": "5511999999999@s.whatsapp.net", "admin": "superadmin" },
    { "id": "5511888888888@s.whatsapp.net", "admin": null }
  ]
}

Todo campo identificador é um JID em formato de número de telefone, nunca @lid.

Atualizar grupo

{ "subject": "Nome novo", "description": "Descrição nova", "announcement": true, "locked": false, "ephemeralExpiration": 604800 }

Pelo menos um campo obrigatório. announcement: true = só admins podem enviar mensagens. locked: true = só admins podem editar as informações do grupo. ephemeralExpiration: segundos até a mensagem desaparecer, 0 desativa. Resposta: { "updated": true }.

Definir / remover foto do grupo

Mesmo formato de entrada da foto de perfil da própria instância. Exige que esta instância seja admin do grupo. PUT: { "updated": true }. DELETE: { "removed": true }.

Obter / revogar código de convite

GET obtém (ou gera) o código de convite atual. POST .../revoke revoga e gera um novo. Os dois exigem que esta instância seja admin do grupo, senão 502 INVITE_CODE_UNAVAILABLE.

{ "code": "AbCdEfGhIjK", "inviteUrl": "https://chat.whatsapp.com/AbCdEfGhIjK" }

Entrar em um grupo

{ "code": "https://chat.whatsapp.com/AbCdEfGhIjK" }

code aceita tanto o código puro quanto a URL de convite completa. Resposta: { "groupJid": "..." }. 502 GROUP_JOIN_FAILED se inválido/expirado/revogado.

Adicionar / remover participantes

{ "participants": ["5511999999999"] }

{ "result": [ { "jid": "5511999999999@s.whatsapp.net", "status": "200" } ] }

status é o resultado do WhatsApp por participante: "200" ok, "403" não permitido, "408" não está no WhatsApp/timeout, "409" já é participante.

Listar contatos

Cache de ~45s no Redis. Resposta: { "contacts": [ { "jid", "name", "syncedAt", ... } ] }. Paginação opcional (limit, máx. 2000, + before).

Listar conversas

Derivado do próprio log de mensagens desta API — uma linha por conversa distinta com mensagem registrada.

{ "chats": [ { "chatJid": "5511999999999@s.whatsapp.net", "name": "Some Contact", "lastMessageAt": "2026-07-01T12:00:00.000Z" } ] }

Obter foto de perfil

Funciona pra JIDs de usuário e de grupo. Opcional ?type=preview (padrão, miniatura) ou ?type=image (resolução completa). Baixada e espelhada em armazenamento local, então url é sempre um link estável em /media/*.

{ "jid": "5511999999999@s.whatsapp.net", "url": "https://api-wpp.example.com/media/1751370000000-9b1e2c-c3.jpg" }

Listar produtos

Query: jid (opcional, usa o catálogo da própria instância por padrão), limit (1-100), cursor.

{ "products": [ "..." ], "nextCursor": null }

Criar produto

multipart/form-data (uma ou mais partes file) ou JSON (array images de URLs).

Campos: name, description, price (inteiro, menor unidade da moeda), currency (3 letras, ex. "BRL"), retailerId?, url?, isHidden?, originCountryCode? (2 letras).

curl -X POST "$BASE/api/instances/$INSTANCE_ID/catalog/products" \
  -H "Authorization: Bearer $INSTANCE_KEY" \
  -F "name=Camiseta Azul" -F "description=100% algodão" -F "price=4990" -F "currency=BRL" \
  -F "file=@/caminho/foto.jpg"

Resposta: 201 com o produto criado.

Atualizar produto

Mesmos campos do create (sem originCountryCode, imutável). As imagens são totalmente substituídas. Resposta: o produto atualizado.

Excluir produtos

{ "productIds": ["123456789"] }

Resposta: { "deleted": 1 }. 502 PRODUCT_DELETE_FAILED se o WhatsApp não confirmar nenhuma exclusão.

Criar webhook

{
  "url": "https://yoursite.com/webhook",
  "events": ["messages.upsert", "connection.update"],
  "secret": "optional-hmac-secret",
  "active": true
}

url obrigatório, http(s):// válido, precisa resolver pra um IP público (veja proteção contra SSRF). events obrigatório, mínimo 1, dentre os 9 nomes abaixo. secret opcional — ativa assinatura HMAC. active opcional, padrão true.

Resposta 201: a linha do webhook criado.

curl -X POST "$BASE/api/instances/$INSTANCE_ID/webhooks" \
  -H "Authorization: Bearer $INSTANCE_KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://yoursite.com/webhook","events":["messages.upsert","connection.update"],"secret":"opcional"}'

Listar webhooks

Resposta: { "webhooks": [Webhook, ...] }.

Atualizar webhook

Atualização parcial — qualquer subconjunto de url, events, secret, active. Um url novo dispara a checagem de SSRF de novo. 404 se não encontrado.

Excluir webhook

Resposta: { "removed": true }. 404 se não encontrado.

Logs de entrega

Últimas 100 tentativas de entrega, mais recente primeiro.

{ "logs": [ { "id": "123", "webhookId": "wh_...", "eventType": "messages.upsert", "payload": {}, "statusCode": 200, "attempt": 1, "success": true, "error": null, "createdAt": "..." } ] }

id é um BigInt, serializado como string JSON.

Reenviar uma entrega registrada

Reenvia um evento já registrado. Resposta: { "resent": true }.