API WhatsApp — Manual Completo

Multi-sessao com Baileys  |  Token fixo por cliente  |  Agente IA integrado

Quick Start

1

Obtenha seu token

Use a variavel de ambiente API_TOKEN para definir um token global, ou crie tokens por sessao via POST /sessions.

2

Escaneie o QR Code

Acesse GET /sessions/:id/pair para obter o QR code. Escaneie com o WhatsApp no celular para conectar a sessao.

3

Envie sua primeira mensagem

curl -X POST /sessions/minha-sessao/send \
  -H "x-api-token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to":"5511999999999","text":"Ola!"}'

Autenticacao

Todas as requisicoes devem incluir o token via um dos seguintes metodos:

Header Authorization

Authorization: Bearer SEU_TOKEN

Header x-api-token

x-api-token: SEU_TOKEN

Endpoints

Sessions

POST /sessions

Cria uma nova sessao. Body: {"id": "minha-sessao"}

Exemplo 
curl -X POST /sessions \
  -H "x-api-token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id":"loja-sp"}'

// Response 201
{"id":"loja-sp","status":"disconnected","created":"2025-01-01T..."}
GET /sessions

Lista todas as sessoes ativas com status de conexao.

GET /sessions/:id/status

Retorna o status de conexao de uma sessao especifica.

Messages

POST /sessions/:id/send

Envia uma mensagem. Body: {"to", "text", "mediaUrl?"}

Exemplo com midia 
curl -X POST /sessions/loja-sp/send \
  -H "x-api-token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999999999",
    "text": "Confira nosso catalogo!",
    "mediaUrl": "https://example.com/catalogo.pdf"
  }'

// Response 200
{"messageId":"3EB0...","status":"sent"}
GET /sessions/:id/messages/inbox

Lista mensagens recebidas na sessao. Suporta ?limit=50.

GET /sessions/:id/messages/logs

Historico completo de mensagens enviadas e recebidas.

Agent (IA)

GET /sessions/:id/agent

Retorna a configuracao atual do agente IA da sessao.

POST /sessions/:id/agent

Atualiza a configuracao do agente. Body: {"model", "systemPrompt", "temperature"}

POST /sessions/:id/agent/test

Testa o agente com uma mensagem simulada. Body: {"message": "Ola"}

Health & Admin

GET /health

Health check basico. Retorna {"status":"ok"}.

GET /ready

Readiness probe para Kubernetes/Docker. Verifica dependencias.

GET /metrics

Metricas Prometheus: sessoes ativas, mensagens enviadas, latencia.

GET /docs

Documentacao Swagger/OpenAPI interativa.

GET /analytics/executive

Dashboard executivo com metricas agregadas de todas as sessoes.

FAQ