[Open Source] TicTic – API REST pro WhatsApp sem refazer tudo do zero · caiopizzol

Você já perdeu um fim de semana inteiro configurando whatsapp-web.js, implementando gerenciamento de sessão, criando endpoints HTTP, só pra no próximo projeto fazer tudo de novo?

Eu também. Depois do 5º projeto repetindo o mesmo boilerplate, criei uma camada que resolve isso — e estou abrindo pra comunidade.

O que ele entrega

API REST pronta — endpoints HTTP sobre whatsapp-web.js, sem reinventar.
Gerenciamento de sessão — QR code com timeout correto de 60s, persistência via Docker volumes.
Multi-sessão — várias contas WhatsApp isoladas no mesmo serviço.
Arquitetura modular — Gateway (Cloudflare Workers) + Service (Node.js/Docker).
Tracking de uso — controle de limites mensais, sem guardar conteúdo das mensagens.
Formatação BR — remove 9º dígito automaticamente.

Status atual (sejamos honestos)

Feature	Status	Observação
Envio de texto	✅ Funcionando	Formatação BR automática
QR timeout 60s	✅ Funcionando	Previne múltiplos QRs
Persistência	✅ Funcionando	Sobrevive restart
Mídia/documentos	❌ Não implementado	whatsapp-web.js suporta, falta adicionar
Grupos	❌ Não implementado	Mesma situação
Fila robusta	⚠️ Básica	Sem retry elaborado ainda
Testes de carga	❌ Não feito	~512MB RAM por sessão

Resumo: MVP funcional pra projetos pequenos/médios, mas precisa de trabalho pra escala.

Mãos à obra

# Self-host o serviço WhatsApp (open source)
git clone https://github.com/tictic-dev/whatsapp
cd whatsapp
docker-compose up

# API rodando em localhost:3000

Como usar a API:

// 1. Criar sessão
const response = await fetch('http://localhost:3000/sessions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer SEU_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ sessionId: 'vendas' })
});

// 2. Pegar QR code (ATENÇÃO: só funciona 1x a cada 60s!)
const qrResponse = await fetch('http://localhost:3000/sessions/vendas/qr', {
  headers: { 'Authorization': 'Bearer SEU_TOKEN' }
});

const { qr, expires_in } = await qrResponse.json();
console.log(`Escaneie em ${expires_in} segundos`);

// 3. Enviar mensagem (após escanear QR)
await fetch('http://localhost:3000/sessions/vendas/messages', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer SEU_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: '11999887766',
    text: 'Boleto gerado: bit.ly/xyz'
  })
});

Arquitetura real

┌─────────────┐     ┌─────────────────┐     ┌──────────────┐
│   Seu App   │────▶│ TicTic Gateway  │────▶│ WhatsApp     │
└─────────────┘     │ (Cloudflare)    │     │ Service      │
                    └─────────────────┘     └──────────────┘
                            │                        │
                            ▼                        ▼
                    ┌─────────────────┐     ┌──────────────┐
                    │ D1 Database     │     │ Docker       │
                    │ (contas/uso)    │     │ (sessões)    │
                    └─────────────────┘     └──────────────┘

Detalhe importante sobre o QR:

// SessionManager.js - Controle real do timeout
isQRActive(sessionId) {
  const qrState = this.qrStates.get(sessionId);
  if (!qrState || !qrState.active) return false;
  
  const elapsed = Date.now() - qrState.timestamp;
  return elapsed < 60000; // WhatsApp regenera a cada 60s
}

// Se tentar gerar outro QR muito rápido:
// HTTP 409: "QR_ALREADY_ACTIVE, retry_after: 45"

Como você pode ajudar

Estou procurando:

Early adopters — preciso descobrir os edge cases reais
Contribuições — mídia é prioridade #1
Feedback de arquitetura — tá muito complexo? muito simples?
Casos de uso — como vocês usam WhatsApp nas apps?

Se você:

Já sofreu com whatsapp-web.js e tem dicas
Precisa de features específicas (grupos, reactions, etc)
Pode rodar em produção e reportar problemas
Manja de Puppeteer/Chromium e performance

Comenta aí ou abre issue no GitHub.

Descobertas técnicas (pra economizar seu tempo)

Cada sessão = ~512MB RAM — Chromium não é leve
QR expira em 60s exatos — não adianta tentar burlar
Número BR com 9º dígito quebra — sempre remova antes de enviar
Session persiste em .wwebjs_auth — faça backup disso
Logout no celular = sessão inválida — precisa novo QR

Próximos passos planejados

Suporte a mídia — imagens primeiro, depois PDFs/áudio
SDK JavaScript/TypeScript — facilitar integração
Webhooks melhores — eventos detalhados
Queue com retry — lidar com instabilidades
Guia de produção — quantas sessões por servidor, etc

Reflexão final

Todo desenvolvedor brasileiro já precisou mandar WhatsApp programaticamente. A API oficial é cara e burocrática, as não-oficiais são instáveis.

Ao invés de cada um reinventar essa roda, por que não construir uma solução open source que resolve 80% dos casos? O core pode ser simples — mandar mensagem de forma confiável. O resto a comunidade constrói em cima.

GitHub: github.com/tictic-dev/whatsapp
Site: tictic.dev (API gerenciada, se não quiser self-host)

PS: Nome "TicTic" é referência aos dois ticks (✓✓) do WhatsApp. Sim, é óbvio, mas funciona 😄