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

WhatsApp

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, labels e envio básico de texto.

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

Enfileira uma mensagem de texto para um grupo monitorado.

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.

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