Documentação

API Lumi

Guia dos endpoints disponíveis no Lumi neste momento. A API combina autenticação do painel, gerenciamento de instâncias, comandos WhatsApp assíncronos, consulta de dados locais e GraphQL usado pelo dashboard.

Base URLhttps://lume-io.com

Autenticação públicaX-API-Key ou Bearer

Execução WhatsAppComandos em fila

Acesso

Autenticação

O painel usa cookie de sessão. A API pública aceita chave por X-API-Key ouAuthorization: Bearer SUA_CHAVE. Existem chaves de usuário para gerenciar instâncias e chaves de instância para executar comandos WhatsApp.

curl https://lume-io.com/api/instances \
  -H "X-API-Key: SUA_USER_API_KEY"

POST/v1/auth/register

Cria uma conta, um tenant e inicia uma sessão por cookie.

Publico

Body

{
  "name": "Tiago",
  "email": "[email protected]",
  "password": "senha-segura",
  "business_name": "Minha Empresa"
}

Resposta

{
  "user": {
    "id": "uuid",
    "email": "[email protected]",
    "name": "Tiago",
    "created_at": "2026-05-06T23:00:00Z"
  },
  "tenant": {
    "id": "uuid",
    "name": "Minha Empresa",
    "role": "owner",
    "api_key_prefix": ""
  }
}

POST/v1/auth/login

Autentica o usuário e grava o cookie de sessão.

Publico

Body

{
  "email": "[email protected]",
  "password": "senha-segura"
}

GET/v1/auth/me

Retorna o usuário e tenant autenticados.

Cookie de sessão

POST/v1/auth/logout

Encerra a sessão atual.

Cookie de sessão

POST/v1/auth/api-key/rotate

Gera uma nova API key global do tenant. A chave completa aparece somente nessa resposta.

Cookie de sessão

Multi-instância

Instâncias

Uma instância representa uma conexão WhatsApp isolada dentro do tenant. A User API key global identifica o usuário e o workspace, então a criação não recebe username no body. O camponame é o nome da instância.

GET/api/instances

Lista as instâncias WhatsApp do usuário autenticado.

User API key

POST/api/instances

Cria uma instância para o usuário dono da User API key e retorna a API key da instância uma única vez.

User API key

Body

{
  "name": "Atendimento",
  "profile_emoji": "🍍"
}

Resposta

{
  "id": "uuid-da-instancia",
  "name": "Atendimento",
  "profile_emoji": "🍍",
  "api_key": "lumi_xxxxxxxxxxxxxxxxx",
  "api_key_prefix": "lumi_xxxxxxx",
  "status": "disconnected"
}

GET/api/instances/{instance_id}

Consulta uma instância específica.

User API key

DELETE/api/instances/{instance_id}

Remove uma instância do tenant.

User API key

POST/api/instances/{instance_id}/api-key/rotate

Gera uma nova API key para a instância.

User API key

Conexão

Sessão WhatsApp

Fluxo recomendado: crie a instância, chame POST /api/instances/{instance_id}/qr, consulte GET /api/instances/{instance_id}/session atéqr_available ser verdadeiro e então carregueGET /api/instances/{instance_id}/qr.png.

GET/api/instances/{instance_id}/session

Consulta o status da sessão WhatsApp de uma instância.

User API key

POST/api/instances/{instance_id}/qr

Enfileira o comando para gerar QR Code de conexão.

User API key

Resposta

{
  "id": "uuid-do-comando",
  "command": "generate_qr",
  "status": "queued"
}

GET/api/instances/{instance_id}/qr.png

Retorna o QR Code atual da instância como imagem PNG. Use depois de enfileirar a geração do QR.

User API key

POST/api/instances/{instance_id}/logout

Enfileira logout da sessão WhatsApp.

User API key

GET/v1/whatsapp/session

Consulta a sessão usada pelo painel.

Cookie de sessão

GET/v1/whatsapp/session/qr.png?instance_id={instance_id}

Retorna o QR Code da sessão como imagem PNG.

Cookie de sessão

API Reference

Mensagens

Endpoints públicos para construir fluxos em cima dos eventos recebidos por webhook. Use aInstance API key da instância conectada e acompanhe comandos assíncronos emGET /commands/{id}.

POST/message/send*

Enviar mensagem

Escolha o tipo de envio no exemplo ao lado. O cURL muda entre texto, mídia, áudio, sticker, localização, contato, enquete, resposta, reação, edição, remoção e presença, mantendo a mesma autenticação por X-API-Key da instância.

numberstring

Destino privado. Alternativo a jid.

jidstring

Destino completo, incluindo grupos.

textstring

Novo texto da mensagem.

media_typestring

image, video ou document.

urlstring

URL opcional associada ao local.

base64string

Sticker em base64, com ou sem data URL.

mimetypestring

MIME type. Padrão: image/webp.

captionstring

Legenda para imagem, vídeo ou documento.

file_namestring

Nome do arquivo quando media_type=document.

pttboolean

Quando true, envia como áudio de voz.

secondsnumber

Duração aproximada em segundos.

latitudenumber

Latitude da localização.

longitudenumber

Longitude da localização.

namestring

Pergunta ou título da enquete.

addressstring

Endereço exibido no WhatsApp.

display_namestring

Nome exibido do contato.

vcardstring

Conteúdo vCard completo.

optionsstring[]

Lista com duas ou mais opções.

selectable_options_countnumber

Quantidade máxima de opções selecionáveis. Use 1 para escolha única.

message_idstring

ID da mensagem enviada pela instância.

participant_jidstring

Participante original quando necessário em grupo.

emojistring

Emoji da reação. Envie string vazia para remover.

from_meboolean

Padrão true para apagar mensagem enviada pela instância.

statestring

typing/composing ou paused.

mediastring

text ou audio. Use audio para gravando.

TextImage / MediaAudioStickerLocationContactPollReplyReactionEditDeletePresence

POST/message/sendText

Enviar mensagem de texto

curl https://lume-io.com/message/sendText \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $LUMI_INSTANCE_KEY" \
  -d '{
    "number": "5511999999999",
    "text": "Olá, recebemos sua mensagem pelo webhook."
  }'

Response

{
  "id": "uuid",
  "group_jid": "[email protected]",
  "text": "Olá, recebemos sua mensagem pelo webhook.",
  "status": "pending",
  "created_at": "2026-05-07T00:00:00Z",
  "updated_at": "2026-05-07T00:00:00Z"
}

POST/message/sendMedia

Enviar mídia

curl https://lume-io.com/message/sendMedia \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $LUMI_INSTANCE_KEY" \
  -d '{
    "number": "5511999999999",
    "media_type": "image",
    "url": "https://example.com/image.jpg",
    "mimetype": "image/jpeg",
    "caption": "Imagem enviada pelo Lumi"
  }'

Response

{
  "id": "uuid-do-comando",
  "command": "message.send_media",
  "status": "pending",
  "created_at": "2026-05-07T00:00:00Z",
  "result": null
}

POST/message/sendAudio

Enviar áudio

curl https://lume-io.com/message/sendAudio \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $LUMI_INSTANCE_KEY" \
  -d '{
    "number": "5511999999999",
    "url": "https://example.com/audio.ogg",
    "mimetype": "audio/ogg",
    "ptt": true,
    "seconds": 12
  }'

Response

{
  "id": "uuid-do-comando",
  "command": "message.send_audio",
  "status": "pending",
  "created_at": "2026-05-07T00:00:00Z",
  "result": null
}

POST/message/sendSticker

Enviar sticker

curl https://lume-io.com/message/sendSticker \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $LUMI_INSTANCE_KEY" \
  -d '{
    "number": "5511999999999",
    "url": "https://example.com/sticker.webp",
    "mimetype": "image/webp"
  }'

Response

{
  "id": "uuid-do-comando",
  "command": "message.send_sticker",
  "status": "pending",
  "created_at": "2026-05-07T00:00:00Z",
  "result": null
}

POST/message/sendLocation

Enviar localização

curl https://lume-io.com/message/sendLocation \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $LUMI_INSTANCE_KEY" \
  -d '{
    "number": "5511999999999",
    "latitude": -23.561684,
    "longitude": -46.625378,
    "name": "Atendimento Lumi",
    "address": "Sao Paulo, SP"
  }'

Response

{
  "id": "uuid-do-comando",
  "command": "message.send_location",
  "status": "pending",
  "created_at": "2026-05-07T00:00:00Z",
  "result": null
}

POST/message/sendContact

Enviar contato

curl https://lume-io.com/message/sendContact \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $LUMI_INSTANCE_KEY" \
  -d '{
    "number": "5511999999999",
    "display_name": "Suporte Lumi",
    "vcard": "BEGIN:VCARD\nVERSION:3.0\nFN:Suporte Lumi\nTEL;type=CELL:+5511999999999\nEND:VCARD"
  }'

Response

{
  "id": "uuid-do-comando",
  "command": "message.send_contact",
  "status": "pending",
  "created_at": "2026-05-07T00:00:00Z",
  "result": null
}

POST/message/sendPoll

Enviar enquete

curl https://lume-io.com/message/sendPoll \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $LUMI_INSTANCE_KEY" \
  -d '{
    "jid": "[email protected]",
    "name": "Qual horario prefere?",
    "options": ["Manha", "Tarde", "Noite"],
    "selectable_options_count": 1
  }'

Response

{
  "id": "uuid-do-comando",
  "command": "message.send_poll",
  "status": "pending",
  "created_at": "2026-05-07T00:00:00Z",
  "result": null
}

POST/message/sendReply

Responder mensagem

curl https://lume-io.com/message/sendReply \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $LUMI_INSTANCE_KEY" \
  -d '{
    "number": "5511999999999",
    "message_id": "3EB0ABCDEF123456",
    "text": "Respondendo sua mensagem."
  }'

Response

{
  "id": "uuid-do-comando",
  "command": "message.send_reply",
  "status": "pending",
  "created_at": "2026-05-07T00:00:00Z",
  "result": null
}

POST/message/sendReaction

Enviar reação

curl https://lume-io.com/message/sendReaction \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $LUMI_INSTANCE_KEY" \
  -d '{
    "number": "5511999999999",
    "message_id": "3EB0ABCDEF123456",
    "emoji": "✅",
    "from_me": false
  }'

Response

{
  "id": "uuid-do-comando",
  "command": "message.send_reaction",
  "status": "pending",
  "created_at": "2026-05-07T00:00:00Z",
  "result": null
}

POST/message/edit

Editar mensagem

curl https://lume-io.com/message/edit \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $LUMI_INSTANCE_KEY" \
  -d '{
    "number": "5511999999999",
    "message_id": "3EB0ABCDEF123456",
    "text": "Texto corrigido"
  }'

Response

{
  "id": "uuid-do-comando",
  "command": "message.edit",
  "status": "pending",
  "created_at": "2026-05-07T00:00:00Z",
  "result": null
}

POST/message/delete

Apagar mensagem

curl https://lume-io.com/message/delete \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $LUMI_INSTANCE_KEY" \
  -d '{
    "number": "5511999999999",
    "message_id": "3EB0ABCDEF123456"
  }'

Response

{
  "id": "uuid-do-comando",
  "command": "message.delete",
  "status": "pending",
  "created_at": "2026-05-07T00:00:00Z",
  "result": null
}

POST/presence/chat

Enviar presença

curl https://lume-io.com/presence/chat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $LUMI_INSTANCE_KEY" \
  -d '{
    "number": "5511999999999",
    "state": "typing",
    "media": "text"
  }'

Response

{
  "id": "uuid-do-comando",
  "command": "presence.chat",
  "status": "pending",
  "created_at": "2026-05-07T00:00:00Z",
  "result": null
}

Status / Stories

Status do WhatsApp chegam pelo JID status@broadcast, mas o Lumi organiza no painel por contato. A API pública permite postar texto, postar imagem/video e marcar status recebidos como vistos.

POST/status/sendText

Publica um Status/Story de texto usando a instância WhatsApp conectada.

Instance API key

Body

{
  "text": "Atendimento online agora."
}

Resposta

{
  "id": "uuid-do-comando",
  "command": "status.send_text",
  "status": "pending",
  "created_at": "2026-05-07T00:00:00Z",
  "result": null
}

POST/status/sendMedia

Publica um Status/Story de imagem ou video por URL pública ou base64.

Instance API key

Body

{
  "media_type": "image",
  "url": "https://example.com/status.jpg",
  "mimetype": "image/jpeg",
  "caption": "Novidade no atendimento"
}

Resposta

{
  "id": "uuid-do-comando",
  "command": "status.send_media",
  "status": "pending",
  "created_at": "2026-05-07T00:00:00Z",
  "result": null
}

POST/status/read

Marca Status/Stories recebidos como visualizados. Use somente quando quiser enviar recibo de visualização ao contato.

Instance API key

Body

{
  "sender_jid": "[email protected]",
  "message_ids": ["3EB0ABCDEF123456"]
}

Resposta

{
  "id": "uuid-do-comando",
  "command": "status.read",
  "status": "pending",
  "created_at": "2026-05-07T00:00:00Z",
  "result": null
}

GET/internal/instances/{instance_id}/status

Endpoint interno do dashboard para listar Status recebidos nas últimas 24h agrupados por contato.

Cookie de sessão

GET/internal/instances/{instance_id}/status/messages?sender_jid={jid}

Endpoint interno do dashboard para listar a timeline de Status de um contato.

Cookie de sessão

GET/internal/instances/{instance_id}/media/{message_id}

Endpoint interno do dashboard para servir mídia baixada/descriptografada de mensagens e Status recebidos.

Cookie de sessão

Preview de mídia: imagens, vídeos e áudios recebidos após o deploy são baixados/descriptografados pelo wa-gateway, salvos no volume lumi_media e exibidos no dashboard pela rota autenticada /internal/instances/{instance_id}/media/{message_id}. Mídias antigas podem aparecer como metadado caso tenham sido recebidas antes desse recurso.

Grupos

Endpoints de grupo retornam 202 Accepted quando enfileiram comandos. Consulte/commands/{id} para ver resultado, falha ou processamento.

GET/groups

Enfileira listagem de grupos do WhatsApp conectado.

Instance API key

POST/group/create

Cria um grupo.

Instance API key

Body

{
  "name": "Clientes VIP",
  "participants": ["5511999999999"],
  "locked": false,
  "announce": false
}

POST/group/info

Consulta detalhes de um grupo.

Instance API key

Body

{
  "jid": "[email protected]"
}

POST/group/participants

Adiciona, remove, promove ou rebaixa participantes.

Instance API key

Body

{
  "jid": "[email protected]",
  "action": "add",
  "participants": ["5511999999999"]
}

POST/group/name

Atualiza o nome do grupo.

Instance API key

Body

{
  "jid": "[email protected]",
  "name": "Novo nome"
}

POST/group/description

Atualiza a descrição do grupo.

Instance API key

Body

{
  "jid": "[email protected]",
  "description": "Descrição do grupo"
}

GET/commands/{id}

Consulta o status e resultado de um comando enfileirado.

Instance API key

Também existem comandos para /group/photo, /group/invite-link,/group/invite-reset, /group/invite-info, /group/locked,/group/announce, /group/requests, /group/requests via POST,/group/join, /group/leave, /group/join-approval,/group/member-add-mode e rotas de /community/*.

Conversas

Chats e Contatos

Consultas locais e comandos de estado para chats, contatos e labels.

GET/contacts

Lista contatos sincronizados da instância.

Instance API key

GET/labels

Lista labels locais da instância.

Instance API key

POST/chat/find

Busca um chat por JID ou número.

Instance API key

Body

{
  "number": "5511999999999"
}

POST/chat/check

Verifica se um número existe no WhatsApp.

Instance API key

Body

{
  "number": "5511999999999"
}

POST/profile

Consulta perfil e foto de um contato.

Instance API key

Body

{
  "number": "5511999999999"
}

POST/v1/groups/{group_jid}/messages

Endpoint legado para enfileirar mensagem de texto usando o JID na URL.

Instance API key

Body

{
  "text": "Mensagem enviada pelo Lumi"
}

GET/v1/outbound-messages/{id}

Consulta o status de uma mensagem enfileirada.

Publico

Comandos adicionais disponíveis: /chat/labels, /chat/pin,/chat/mute, /chat/archive, /chat/read,/chat/block, /chat/blocklist, /chat/delete e/label/edit. Para enviar para grupo no endpoint recomendado, use{"jid":"[email protected]"} no body de /message/sendText.

Eventos

Webhooks

A configuração de webhook está disponível hoje via GraphQL no dashboard. Cada instância possui URL, ativação, filtros de eventos, exclusões e histórico de entregas.

mutation UpdateWebhook($id: String!, $url: String!) {
  updateInstanceWebhook(
    id: $id
    url: $url
    enabled: true
    local_map: false
    groups_ignore: false
    events: ["message.received"]
    exclude: []
  ) {
    id
    webhook_url
    webhook_enabled
  }
}

Dashboard

GraphQL

O endpoint POST /graphql usa cookie de sessão e alimenta o painel operacional.

query Dashboard($instance_id: String) {
  dashboard(instance_id: $instance_id) {
    session {
      id
      status
      qr_available
      qr_expires_at
    }
    instances {
      id
      name
      status
      api_key_prefix
    }
    groups {
      jid
      name
      monitored
    }
  }
}

Queries

dashboard(instance_id)
webhookDeliveries(instance_id, limit)

Mutations

createInstance(name, profile_emoji)
rotateInstanceAPIKey(id)
deleteInstance(id)
setGroupMonitoring(jid, monitored, instance_id)
sendGroupMessage(group_jid, instance_id, text)
sendMediaMessage(...), sendAudioMessage(...) e sendStickerMessage(...)
sendLocationMessage(...), sendContactMessage(...) e sendPollMessage(...)
sendReplyMessage(...), sendReactionMessage(...), editMessage(...) e deleteMessage(...)
sendPresence(instance_id, jid, state, media)
requestWhatsAppQR(instance_id)
updateInstanceWebhook(...)
updateInstanceClearHistory(id, enabled)
sendTestWebhook(instance_id)

Operação

Observabilidade

GET /healthz retorna o status da API. GET /metrics expõe métricas Prometheus e exige token por Authorization: Bearer ou X-Metrics-Token.

curl https://lume-io.com/metrics \
  -H "Authorization: Bearer SEU_METRICS_TOKEN"

Voltar para o painel