Central de Bots — API & Integração

1 Introdução

O ServidorWhats é uma API REST multi-instância para WhatsApp que suporta três providers sob a mesma interface HTTP. Escolha o provider ideal para cada caso de uso sem mudar a integração.

Baileys (padrão)

Protocolo reverso do WhatsApp Web. Leve, rápido, recurso completo. Ideal para automações e chatbots de alto volume.

whatsapp-web.js

Baseado em Puppeteer + Chromium. Maior compatibilidade com recursos visuais. Use provider: "wwebjs".

Meta Cloud API

API oficial do WhatsApp Business. Sem ban, sem QR Code. Requer conta Business verificada. Use provider: "meta".

MongoDB + Arquivos

Mensagens, agentes, pools e clientes em MongoDB. Sessões e dados em sessions/ e data/ localmente.

Anti-ban automático

Fila com delay aleatório entre envios (800–2500ms padrão), aquecimento progressivo e monitoramento de status.

Agentes IA

Chatbots com OpenAI, Vercel AI Gateway ou endpoint externo. Function calling, histórico de conversa e pausas.

Formato das respostas: Todos os endpoints retornam JSON com { success: true, ... } em caso de sucesso ou { success: false, error: "..." } em caso de erro. Códigos HTTP padrão são usados (200, 201, 400, 401, 403, 404, 500).

2 Autenticação

O servidor suporta dois níveis de acesso via chave de API e um terceiro via token de sessão para o portal do cliente.

x-api-key — chave padrão. Criada pelo admin via POST /apikeys. Dá acesso a instâncias, pools, agentes e métricas.

MASTER_KEY — definida na variável de ambiente MASTER_KEY. Acesso total, incluindo gestão de clientes (/admin/*), criação/revogação de API keys e logs internos.

Authorization: Bearer <token> — obtido em POST /portal/login. Restringe o acesso às instâncias e pools atribuídos ao cliente.

Passe a chave no header ou via query string:

bash — header (recomendado)

curl -H "x-api-key: SUA_API_KEY" BASE_URL/instances

bash — query string (alternativo)

curl BASE_URL/instances?api_key=SUA_API_KEY

GET /auth/info Nível de acesso da chave fornecida

x-api-keyTodos providers

Retorna o nível da chave enviada: master, apikey ou none. Útil para validar a chave antes de integrações.

curl

curl -H "x-api-key: SUA_API_KEY" \
  http://localhost:3000/auth/info

GET /tenant Identifica marca/escopo do domínio

x-api-key

Identifica a marca e o conjunto de instâncias/pools visíveis para o domínio (host) de onde a requisição parte. Essencial em ambientes multi-tenant com domínios personalizados por cliente.

curl

curl -H "x-api-key: SUA_API_KEY" \
  http://localhost:3000/tenant

3 Instâncias (multi-provider)

Gerencie conexões WhatsApp individuais. Cada instância tem um instanceId único, um provider (baileys, wwebjs ou meta) e um ciclo de vida independente.

GET /instances Lista todas as instâncias

x-api-keyTodos providers

Retorna todas as instâncias ativas (Baileys + wwebjs + Meta). Filtro opcional por provider via query string.

Parâmetro	Tipo	Descrição
`?provider`	string	opcional — filtra por `baileys`, `wwebjs` ou `meta`

curl

curl -H "x-api-key: SUA_API_KEY" \
  "http://localhost:3000/instances?provider=baileys"

POST /instances Cria nova instância

x-api-keyTodos providers

Cria uma instância. O campo provider define qual engine usar. Para Baileys e wwebjs, após criar aguarde o QR Code em GET /instances/:id/qr.

Campo	Tipo	Descrição
`instanceId`	string	obrigatório — identificador único (letras, números, _ e -)
`provider`	string	opcional — `baileys` (padrão) \| `wwebjs` \| `meta`
`label`	string	opcional — nome amigável para exibição
`webhook`	string	opcional — URL para receber eventos
`webhookSecret`	string	opcional — segredo HMAC para assinar o webhook
`ignoreGroups`	boolean	opcional — ignora mensagens de grupos
`phoneNumberId`	string	Meta only — ID do número no Meta Business
`accessToken`	string	Meta only — token de acesso permanente da Meta
`verifyToken`	string	Meta only — token de verificação do webhook Meta

curl — Baileys (padrão)

curl -s -X POST http://localhost:3000/instances \
  -H "x-api-key: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "bot1",
    "label": "Bot Principal",
    "webhook": "https://meuapp.com/webhook"
  }'

curl — Meta Cloud API

curl -s -X POST http://localhost:3000/instances \
  -H "x-api-key: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "meta1",
    "provider": "meta",
    "phoneNumberId": "123456789",
    "accessToken": "EAABsb...",
    "verifyToken": "meu-verify-token"
  }'

GET /instances/:id Detalhes de uma instância

x-api-key

Retorna status, telefone, pushName, webhook configurado, QR Code (se disponível) e configurações da instância.

curl

curl -H "x-api-key: SUA_API_KEY" \
  http://localhost:3000/instances/bot1

GET /instances/:id/qr QR Code em base64

x-api-keyBaileys / wwebjs

Retorna o QR Code como base64 (campo qrCode) e como texto (campo qrText). Use GET /instances/:id/qr/image para obter diretamente como imagem PNG — útil em <img src="">.

Meta Cloud API não usa QR Code. Este endpoint retorna erro 400 para instâncias Meta.

curl

curl -H "x-api-key: SUA_API_KEY" \
  http://localhost:3000/instances/bot1/qr

POST /instances/:id/reconnect Força reconexão da instância

x-api-key

Encerra o socket atual e inicia nova tentativa de conexão. Funciona para Baileys e wwebjs. Após reconectar pode ser necessário escanear o QR novamente se a sessão expirou.

Endpoints relacionados (sem body): POST /instances/:id/disconnect — desconecta sem remover. DELETE /instances/:id — remove completamente (sessão + estado).

curl

curl -s -X POST http://localhost:3000/instances/bot1/reconnect \
  -H "x-api-key: SUA_API_KEY"

POST /instances/:id/send/text Envio de texto unificado

x-api-keyTodos providers

Envia uma mensagem de texto. Funciona para qualquer provider (Baileys, wwebjs e Meta) sem mudar a chamada. O número to deve incluir DDI (ex.: 5511999990000).

Campo	Tipo	Descrição
`to`	string	obrigatório — número com DDI, sem +
`text`	string	obrigatório — conteúdo da mensagem
`quotedMessageId`	string	opcional — ID de mensagem a responder (Baileys)

curl

curl -s -X POST http://localhost:3000/instances/bot1/send/text \
  -H "x-api-key: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"5511999990000","text":"Olá, tudo bem?"}'

POST /instances/:id/send/media Envio de mídia unificado

x-api-keyTodos providers

Envia imagem, vídeo, áudio ou documento via URL pública. Funciona para todos os providers.

Campo	Tipo	Descrição
`to`	string	obrigatório
`type`	string	obrigatório — `image` \| `video` \| `audio` \| `document`
`url`	string	obrigatório — URL pública acessível
`caption`	string	opcional — legenda
`filename`	string	opcional — nome do arquivo (documentos)

curl

curl -s -X POST http://localhost:3000/instances/bot1/send/media \
  -H "x-api-key: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999990000",
    "type": "image",
    "url": "https://exemplo.com/imagem.jpg",
    "caption": "Confira nossa promoção!"
  }'

4 Mensagens Avançadas (Baileys)

Endpoints avançados exclusivos do provider Baileys. Todos sob /instances/:id/messages/. Aceita ?queue=true para enfileirar com delay anti-spam.

POST/instances/:id/messages/textTexto simples. Body: {to, text, quotedMessageId?}

POST/instances/:id/messages/text/batchLote de até 200 mensagens. Body: {messages:[{to,text}]}

POST/instances/:id/messages/imageImagem por URL. Body: {to, url, caption?}

POST/instances/:id/messages/documentDocumento. Body: {to, url, filename?, mimetype?, caption?}

POST/instances/:id/messages/audioÁudio por URL. Body: {to, url}

POST/instances/:id/messages/videoVídeo por URL. Body: {to, url, caption?}

POST/instances/:id/messages/locationLocalização. Body: {to, latitude, longitude, name?, address?}

POST/instances/:id/messages/reactReagir com emoji. Body: {to, messageId, emoji}

POST/instances/:id/messages/presenceIndicador "digitando…". Body: {to, presence} — valores: composing, recording, available, paused

POST/instances/:id/messages/readMarcar lidas. Body: {keys: [...]}

POST/instances/:id/messages/check-numberVerifica se número tem WhatsApp. Body: {phone}

POST/instances/:id/messages/broadcastDisparo em massa com warmup. Body: {message, recipients, googleSheet?} — máx. 1000

POST /instances/:id/messages/text/batch Exemplo detalhado — envio em lote

x-api-keyBaileys

Enfileira até 200 mensagens de texto com delay anti-spam automático. Retorna um jobId por mensagem para acompanhamento.

curl

curl -s -X POST http://localhost:3000/instances/bot1/messages/text/batch \
  -H "x-api-key: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"to": "5511999990001", "text": "Olá, João!"},
      {"to": "5511999990002", "text": "Olá, Maria!"}
    ]
  }'

5 Grupos (Baileys)

Gerencie grupos do WhatsApp via instâncias Baileys. Todos os endpoints sob /instances/:id/groups/.

GET/instances/:id/groupsLista todos os grupos que a instância participa

POST/instances/:id/groupsCriar grupo. Body: {subject, participants: ["551199..."]}

GET/instances/:id/groups/:groupIdMetadados do grupo (nome, participantes, admins)

PUT/instances/:id/groups/:groupId/subjectMudar nome. Body: {subject}

PUT/instances/:id/groups/:groupId/descriptionMudar descrição. Body: {description}

POST/instances/:id/groups/:groupId/participants/addAdicionar participantes. Body: {participants:[]}

POST/instances/:id/groups/:groupId/participants/removeRemover participantes. Body: {participants:[]}

POST/instances/:id/groups/:groupId/participants/promotePromover a admin. Body: {participants:[]}

POST/instances/:id/groups/:groupId/participants/demoteRebaixar de admin. Body: {participants:[]}

POST/instances/:id/groups/:groupId/leaveSair do grupo

GET/instances/:id/groups/:groupId/inviteObter link de convite

POST/instances/:id/groups/joinEntrar em grupo por código. Body: {inviteCode}

6 Inbox Interno

Leia e responda conversas diretamente pela API, sem webhook. Requer SAVE_MESSAGES=true no .env para que as mensagens sejam persistidas no MongoDB.

Pré-requisito: defina SAVE_MESSAGES=true no arquivo .env. Sem isso, os endpoints retornam listas vazias.

GET /instances/:id/inbox Lista conversas da instância

x-api-key

Retorna a lista de chats com a última mensagem de cada conversa. Use ?limit=50 (padrão 100, máx 500).

curl

curl -H "x-api-key: SUA_API_KEY" \
  "http://localhost:3000/instances/bot1/inbox?limit=50"

GET /instances/:id/inbox/:peer Mensagens de uma conversa

x-api-key

Retorna as mensagens de um contato ou grupo específico. :peer é o JID do contato (ex.: 5511999990000@s.whatsapp.net ou 123456@g.us).

curl

curl -H "x-api-key: SUA_API_KEY" \
  "http://localhost:3000/instances/bot1/inbox/5511999990000@s.whatsapp.net"

POST /instances/:id/inbox/:peer/reply Responder na conversa

x-api-key

Envia uma resposta de texto para o peer informado. Body: { text }.

curl

curl -s -X POST \
  http://localhost:3000/instances/bot1/inbox/5511999990000@s.whatsapp.net/reply \
  -H "x-api-key: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Olá! Como posso ajudar?"}'

7 Pools (multi-número + failover)

Agrupe múltiplas instâncias em um pool para distribuição de carga e failover automático. Se uma instância estiver desconectada ou banida, o pool redireciona automaticamente para a próxima disponível.

Estratégias:
failover — sempre usa a primeira instância saudável.
round-robin — distribui entre as instâncias em rotação.
least-used — sempre escolhe a que enviou menos mensagens.

POST /pools Cria novo pool

x-api-key

Campo	Tipo	Descrição
`label`	string	obrigatório
`strategy`	string	opcional — `failover` (padrão) \| `round-robin` \| `least-used`
`members`	string[]	opcional — lista de instanceIds iniciais

curl

curl -s -X POST http://localhost:3000/pools \
  -H "x-api-key: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Pool Marketing",
    "strategy": "round-robin",
    "members": ["bot1", "bot2", "bot3"]
  }'

GET/poolsLista todos os pools com status de saúde

GET/pools/:idDetalhes do pool

PATCH/pools/:idAtualiza label, strategy ou members

DELETE/pools/:idRemove pool

POST/pools/:id/membersAdiciona instância. Body: {instanceId}

DELETE/pools/:id/members/:instanceIdRemove instância do pool

GET/pools/:id/healthSaúde dos números + próxima instância a usar

POST /pools/:id/send/text Envia texto via pool (failover automático)

x-api-key

O pool seleciona automaticamente a melhor instância disponível conforme a estratégia configurada. Se a instância escolhida falhar, tenta a próxima.

curl

curl -s -X POST http://localhost:3000/pools/pool-mktg/send/text \
  -H "x-api-key: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"5511999990000","text":"Olá do pool!"}'

POST/pools/:id/send/mediaEnvia mídia via pool. Body: {to, type, url, caption?}

8 Agentes IA

Configure um chatbot com IA por instância. Suporta dois modos: interno (LLM gerenciado pelo servidor) e externo (seu próprio endpoint recebe a mensagem e devolve a resposta).

Modo interno: use provider: "openai" (compatível com qualquer API OpenAI) ou provider: "vercel-ai-gateway". Configure apiKey, model e systemPrompt. O servidor gerencia histórico de conversa, delay de digitação e pausas.

Modo externo: use provider: "external" e informe externalEndpoint. O servidor faz POST para seu endpoint com o corpo { instanceId, from, text, history } e espera { reply: "texto da resposta" }.

POST /instances/:id/agent Configurar / ativar agente

x-api-keyTodos providers

Campo	Tipo	Descrição
`provider`	string	obrigatório — `openai` \| `vercel-ai-gateway` \| `external`
`apiKey`	string	openai/vercel — chave da OpenAI ou gateway
`model`	string	opcional — ex.: `gpt-4o-mini`
`systemPrompt`	string	opcional — personalidade / instrução do bot
`externalEndpoint`	string	external — URL do endpoint externo
`enabled`	boolean	opcional — ativa/desativa (padrão: true)
`historySize`	number	opcional — mensagens no contexto (padrão: 10)
`ignoreGroups`	boolean	opcional — ignora mensagens de grupo (padrão: true)
`typingIndicator`	boolean	opcional — simula "digitando…" (padrão: true)

curl — modo interno (OpenAI)

curl -s -X POST http://localhost:3000/instances/bot1/agent \
  -H "x-api-key: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "openai",
    "apiKey": "sk-proj-...",
    "model": "gpt-4o-mini",
    "systemPrompt": "Você é um atendente simpático da Loja XYZ.",
    "historySize": 15
  }'

curl — modo externo

curl -s -X POST http://localhost:3000/instances/bot1/agent \
  -H "x-api-key: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "external",
    "externalEndpoint": "https://meubot.com/whatsapp",
    "enabled": true
  }'

GET/instances/:id/agentRetorna configuração do agente (apiKey mascarada)

DELETE/instances/:id/agentArquiva agente (soft-delete). Use ?purge=true para apagar definitivamente

POST/instances/:id/agent/testTestar resposta do agente sem enviar pelo WhatsApp. Body: {message, from?}

POST/instances/:id/agent/pause/:phonePausar agente para um número. Body: {durationMs?} (padrão 24h)

POST/instances/:id/agent/resume/:phoneRetomar agente para um número

GET/instances/:id/agent/history/:phoneHistórico de conversa com um número

DELETE/instances/:id/agent/history/:phoneLimpar histórico de conversa

GET/agents/modelsCatálogo de modelos com estimativa de custo por mensagem

9 Métricas / Monitoramento

Endpoints para monitorar a saúde do servidor, uso de recursos e performance de cada instância.

GET /metrics/overview Visão geral completa

x-api-key

Retorna contadores de instâncias, volume de mensagens enviadas/recebidas, taxa de erros e recursos do sistema em um único payload.

curl

curl -H "x-api-key: SUA_API_KEY" \
  http://localhost:3000/metrics/overview

GET/metrics/systemSaúde da VPS: CPU, memória RAM, disco, uptime

GET/metrics/instancesPerformance de todas as instâncias (mensagens/s, erros, latência)

GET/metrics/instance/:idPerformance detalhada de uma instância específica

GET/healthStatus geral do servidor (versão, uptime, memória Node.js, BD)

10 Multi-tenant (Admin)

Gerencie clientes em ambientes multi-tenant. Todos os endpoints /admin/* exigem a MASTER_KEY no header x-api-key.

MASTER_KEY obrigatória. Estes endpoints não funcionam com chaves de integração comuns. Configure a variável MASTER_KEY no .env do servidor.

POST /admin/clients Cria conta de cliente

MASTER_KEY

Cria um cliente com login próprio. Atribua instâncias, pools e domínios para que o cliente veja apenas seus recursos.

Campo	Tipo	Descrição
`name`	string	obrigatório
`email`	string	obrigatório — usado no login do portal
`password`	string	obrigatório
`domains`	string[]	opcional — domínios autorizados (ex.: `["bot.cliente.com"]`)
`instanceIds`	string[]	opcional — instâncias atribuídas
`poolIds`	string[]	opcional — pools atribuídos

curl

curl -s -X POST http://localhost:3000/admin/clients \
  -H "x-api-key: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Empresa ABC",
    "email": "admin@abc.com",
    "password": "senha123",
    "domains": ["bot.abc.com"],
    "instanceIds": ["bot1", "bot2"],
    "poolIds": []
  }'

GET/admin/clientsLista todos os clientes

GET/admin/clients/:idDetalhes de um cliente

PATCH/admin/clients/:idAtualiza nome, email, instâncias, pools ou domínios

PUT/admin/clients/:id/passwordRedefine senha do cliente. Body: {password}

DELETE/admin/clients/:idRemove cliente

11 Portal do Cliente

Interface de self-service para clientes. O cliente faz login com email e senha, obtém um token JWT de sessão e usa esse token para acessar apenas suas instâncias e pools atribuídos.

Autenticação do portal: use o header Authorization: Bearer <token> obtido em POST /portal/login. O token não é a mesma coisa que a x-api-key.

POST /portal/login Login do cliente → token de sessão

PortalSem autenticação

Autentica um cliente e retorna um token de sessão. O login é restrito ao domínio configurado para o cliente — tentar logar em outro domínio retorna 403.

curl

curl -s -X POST http://localhost:3000/portal/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@abc.com","password":"senha123"}'

# Use o token retornado nas próximas chamadas:
curl http://localhost:3000/portal/me \
  -H "Authorization: Bearer TOKEN_AQUI"

GET/portal/meDados da conta do cliente autenticado

GET/portal/instancesInstâncias atribuídas ao cliente (com estado)

GET/portal/instances/:id/qrQR Code da instância do cliente

GET/portal/instances/:id/metricsMétricas de desempenho da instância

GET/portal/instances/:id/inboxLista conversas (requer SAVE_MESSAGES)

GET/portal/instances/:id/inbox/:peerMensagens de uma conversa

POST/portal/instances/:id/inbox/:peer/replyResponder na conversa. Body: {text}

POST/portal/instances/:id/send/textEnviar texto. Body: {to, text}

POST/portal/instances/:id/send/mediaEnviar mídia. Body: {to, type, url, caption?}

GET/portal/poolsPools atribuídos ao cliente

POST/portal/pools/:id/send/textEnviar via pool (failover). Body: {to, text}

12 Webhooks

Configure uma URL de webhook ao criar ou atualizar uma instância para receber eventos em tempo real. O servidor faz POST para a URL configurada com o payload do evento.

Eventos emitidos

instance.connected instance.disconnected instance.banned instance.qr message.received message.sent message.ack message.reaction message.deleted group.add group.remove group.promote group.demote group.update contacts.update presence.update call.received

Assinatura HMAC

Se a instância tiver webhookSecret configurado, cada requisição de webhook incluirá o header X-ServidorWhats-Signature com o HMAC-SHA256 do corpo em hexadecimal. Valide esse header no seu servidor para garantir a autenticidade dos eventos.

POST sua-url-de-webhook Exemplo de payload recebido

Payload de exemplo para o evento message.received:

JSON — evento message.received

{
  "event": "message.received",
  "instanceId": "bot1",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "data": {
    "messageId": "3EB0123456ABCDEF",
    "from": "5511999990000@s.whatsapp.net",
    "fromName": "João Silva",
    "text": "Olá, preciso de ajuda!",
    "type": "text",
    "isGroup": false,
    "timestamp": 1736940600
  }
}

Node.js — verificar assinatura HMAC

// Express middleware para validar X-ServidorWhats-Signature
const crypto = require('crypto');

function verifyWebhook(secret) {
  return (req, res, next) => {
    const sig = req.headers['x-servidorwhats-signature'];
    const body = JSON.stringify(req.body);
    const expected = crypto
      .createHmac('sha256', secret)
      .update(body)
      .digest('hex');
    if (sig !== expected) {
      return res.status(401).json({ error: 'Assinatura inválida' });
    }
    next();
  };
}

Configurar webhook numa instância

curl — PUT /instances/:id/webhook

curl -s -X PUT http://localhost:3000/instances/bot1/webhook \
  -H "x-api-key: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook": "https://meuapp.com/whatsapp/events",
    "webhookSecret": "meu-segredo-hmac"
  }'

13 Painéis

Além da API, o servidor inclui painéis web integrados acessíveis pelo navegador.

Dica de integração: use GET /health como healthcheck do seu load balancer ou orquestrador (Docker, PM2). O endpoint retorna {"status":"ok"} com código 200 quando tudo está funcionando.

1 Introdução

Baileys (padrão)

whatsapp-web.js

Meta Cloud API

MongoDB + Arquivos

Anti-ban automático

Agentes IA

2 Autenticação

3 Instâncias (multi-provider)

4 Mensagens Avançadas (Baileys)

5 Grupos (Baileys)

6 Inbox Interno

7 Pools (multi-número + failover)

8 Agentes IA

9 Métricas / Monitoramento

10 Multi-tenant (Admin)

11 Portal do Cliente

12 Webhooks

Eventos emitidos

Assinatura HMAC

Configurar webhook numa instância

13 Painéis

Painel Admin

Monitor

Portal do Cliente

Documentação