Pular para o conteúdo principal

O que e o Ogmma API

Conceituacao​

O Ogmma API e uma plataforma API-first para envio e gerenciamento de mensagens WhatsApp. Pense nele como a ponte entre o seu sistema e o WhatsApp -- voce faz uma chamada REST e a mensagem chega no celular do seu cliente.

A plataforma foi construida para ser multi-tenant, ou seja, varias empresas podem usar a mesma infraestrutura de forma isolada e segura. Cada empresa (instituicao) tem seus proprios canais, contatos, conversas e configuracoes.

Como Funciona​

A arquitetura do Ogmma API e dividida em dois processos independentes que trabalham juntos:

┌─────────────────────┐     Redis Pub/Sub     ┌─────────────────────┐
│    API Server       │◄─────────────────────►│      Worker         │
│  (REST + WebSocket) │                       │  (WhatsApp Engine)  │
│                     │  message:received     │                     │
│  - Autenticacao     │  message:sent         │  - Baileys Adapter  │
│  - Validacao        │  channel:connected    │  - WABA Adapter     │
│  - Regras de        │  channel:qrcode       │  - Processamento    │
│    Negocio          │                       │    de Mensagens     │
└─────────────────────┘                       └─────────────────────┘
         ↓                                              ↓
         └──────────────→ MongoDB Atlas ←───────────────┘
                    Banco de Dados Compartilhado

API Server​

O API Server e o ponto de entrada para todas as requisicoes. E ele que:

  • Recebe suas chamadas REST (enviar mensagem, listar conversas, criar contato, etc.)
  • Valida autenticacao e permissoes (API Key ou JWT)
  • Aplica regras de negocio (limites de envio, validacao de dados)
  • Publica comandos para o Worker via Redis
  • Envia notificacoes em tempo real via WebSocket (Socket.IO)

Worker​

O Worker e o motor que se conecta ao WhatsApp. E ele que:

  • Gerencia sessoes do WhatsApp (conexao, QR code, reconexao)
  • Processa mensagens recebidas e enviadas
  • Executa os envios reais para o WhatsApp
  • Publica eventos de volta para o API Server
Importante

O Worker e completamente agnostico -- ele nao conhece regras de negocio, usuarios ou permissoes. Ele apenas sabe enviar e receber mensagens. Toda a comunicacao entre API Server e Worker acontece via Redis.

Canais Suportados​

O Ogmma API suporta dois tipos de canais WhatsApp:

CanalTipoDescricao
WhatsApp BaileysWHATSAPP_BAILEYSConexao nao-oficial via QR Code. Usa o protocolo Web do WhatsApp. Ideal para testes e volumes menores.
WhatsApp WABAWHATSAPP_WABAConexao oficial via Meta Business API. Requer numero verificado e templates aprovados. Ideal para producao e grandes volumes.

WhatsApp Baileys​

A conexao via Baileys funciona escaneando um QR Code, similar ao WhatsApp Web. Voce conecta seu numero pessoal ou comercial e comeca a enviar e receber mensagens imediatamente.

Vantagens:

  • Configuracao rapida (escaneie o QR e pronto)
  • Sem custos adicionais por mensagem
  • Todos os tipos de mensagem disponiveis

Consideracoes:

  • Conexao pode ser instavel em volumes muito altos
  • Requer que o celular esteja conectado a internet
  • Nao e a solucao oficial do Meta

WhatsApp WABA (Business API)​

A conexao via WABA utiliza a API oficial do Meta. Requer uma conta Business verificada e templates de mensagem aprovados para iniciar conversas.

Vantagens:

  • Conexao estavel e oficial
  • Suporte a templates aprovados
  • Ideal para grandes volumes
  • Nao depende de celular conectado

Consideracoes:

  • Requer verificacao de negocio no Meta
  • Mensagens iniciadas pela empresa precisam usar templates
  • Custo por conversa (modelo de precificacao do Meta)

Multi-Tenancy​

Cada empresa que usa o Ogmma API e identificada por um institutionId. Esse ID e incluido automaticamente em todas as operacoes, garantindo que:

  • Dados de uma empresa nunca sao acessiveis por outra
  • Cada empresa tem seus proprios canais, contatos e conversas
  • Limites e configuracoes sao aplicados por empresa

Voce nao precisa se preocupar com isso na integracao -- o institutionId e extraido automaticamente da sua API Key ou token JWT.

Autenticacao​

O Ogmma API oferece dois metodos de autenticacao:

API Key (Recomendado para integracoes)​

Use API Keys para integracoes server-to-server. A chave e enviada no header Authorization:

Authorization: Bearer oapi_sk_live_abc123...

As API Keys possuem escopos de permissao configuráveis, permitindo controle granular sobre o que cada chave pode acessar.

JWT (Para aplicacoes web)​

O JWT e utilizado pelo frontend web do Ogmma. O fluxo e em duas etapas:

  1. Login -- Autentica com email/senha e recebe um token pendente
  2. Selecao de Instituicao -- Seleciona a instituicao e recebe o token completo

Para integracoes via API, recomendamos usar API Keys por serem mais simples e seguras.

Fluxo de uma Mensagem​

Para entender melhor como tudo se conecta, veja o caminho que uma mensagem percorre:

1. Voce faz POST /channels/{channelId}/messages/text
   ↓
2. API Server valida autenticacao e dados
   ↓
3. API Server enfileira o comando no Redis
   ↓
4. Worker desenfileira e envia via WhatsApp (Baileys ou WABA)
   ↓
5. WhatsApp confirma o envio
   ↓
6. Worker publica evento 'message:sent' no Redis
   ↓
7. API Server recebe o evento
   ↓
8. WebSocket notifica o frontend em tempo real
   ↓
9. Webhook envia notificacao para sua URL configurada
Dica

O status 202 Accepted nas respostas da API significa que a mensagem foi aceita para processamento. O envio real e assincrono. Use Webhooks para acompanhar o status de entrega.

Proximos Passos​

Agora que voce entende como o Ogmma API funciona, vamos colocar a mao na massa: