wpp-gateway API Reference

Bem-vindo à referência completa da API REST do wpp-gateway — o gateway unificado de WhatsApp e Instagram da plataforma Oggma.

Base URL (produção): https://wpp.ogmma.com.br
Versão da API: v1
Autenticação: header X-API-Key: ak_live_...
Formato: JSON (UTF-8), erros padronizados, snake_case nunca — só camelCase.

O que é o wpp-gateway?

O wpp-gateway é um serviço multi-tenant que consolida três canais de mensageria em uma única API REST + webhooks:

Canal	Tipo	Descrição
WABA	Oficial Meta	WhatsApp Business Cloud API (templates aprovados, mensagens de marketing/utility/auth)
BAILEYS	Não oficial	WhatsApp Web via QR code ou pairing code (uso pessoal/atendimento)
INSTAGRAM	Oficial Meta	Mensagens via Messenger Platform (Instagram Business)

Cada phone (também chamado de canal) é independente, tem o próprio status de conexão, webhook URL e ciclo de vida. A API expõe um modelo uniforme — mandar uma mensagem de texto é o mesmo POST /v1/messages independentemente do canal subjacente.

Quando usar

Aplicações que precisam enviar e receber mensagens via WhatsApp/Instagram sem manter sessão Baileys ou validar tokens Meta.
Sistemas que querem padronizar eventos de múltiplos canais em um único formato de webhook.
Produtos B2B com múltiplos clientes (multi-tenant nativo via account + X-API-Key).
Casos com necessidade de IA embarcada (transcrição, OCR, AI Agent, RAG) — todos opcionais e BYO-key OpenAI.

Arquitetura

                          ┌──────────────────────────┐
                          │   Cliente (seu backend)  │
                          └──────────┬───────────────┘
                                     │ X-API-Key
                                     ▼
       ┌────────────────────────────────────────────────────────────┐
       │                       wpp-gateway                          │
       │                                                            │
       │  ┌─────────┐   ┌──────────┐   ┌──────────┐  ┌───────────┐  │
       │  │   API   │   │  Worker  │   │Dispatcher│  │  Billing  │  │
       │  │ :3000   │◄─►│  :3001   │◄─►│   BullMQ │  │  Asaas    │  │
       │  └────┬────┘   └────┬─────┘   └────┬─────┘  └─────┬─────┘  │
       │       │             │              │              │        │
       │       └─────┬───────┴──────────────┴──────────────┘        │
       │             │       Redis pub/sub (wpp:cmd, wpp:events)    │
       │             │                                              │
       │             │  Postgres (multi-tenant) + S3 (mídia TTL 7d) │
       └─────────────┼──────────────────────────────────────────────┘
                     │
                     ▼
        ┌────────────────────────────────┐
        │   Baileys │ Meta Graph │ Instagram │
        └────────────────────────────────┘
                     │
                     ▼
            HTTPS POST (webhook) ───►  Cliente
            X-WppGateway-Signature

API (3000): REST + SSE, autenticação por API key.
Worker (3001): sessões Baileys, processamento de mensagens, AI Agent, transcrição.
Dispatcher: entrega de webhooks com retries exponenciais + DLQ.
Billing: ciclos de fatura via Asaas (Pix, boleto, cartão).

Sumário

#	Capítulo	Conteúdo
01	Getting Started	Primeiro request, conceitos (account, phone, channel), tour rápido
02	Authentication	X-API-Key, criação via admin, rotação, escopos
03	Phones (canais)	CRUD, QR, pairing code, embedded signup WABA, OAuth Instagram, business profile
04	Messages	Envio (15 tipos), reply, idempotency, scheduled
05	Message Ops	React, edit, delete, read, typing
06	Media	Upload, download via signed URL, transcrição (Whisper), OCR, TTL 7d
07	WABA Templates	Lifecycle (DRAFT → APPROVED), sync, edit, carousel, OTP, flows
08	Webhooks	Registro, eventos publicados, assinatura HMAC, retry/DLQ
09	Events (SSE)	Server-Sent Events, alternativa a webhooks
10	Lookup	Verificar números no WhatsApp (Baileys-only)
11	AI Agent	Configuração, knowledge base (RAG), conversations, handoff
12	Calls (WABA)	Voice calls signaling (SDP), recording, transcrição
13	Billing	Usage, invoices, Asaas (Pix/boleto), dunning
14	Errors	Catálogo completo de códigos (PHONE_NOT_FOUND, PAIRING_NOT_READY, ACCOUNT_SUSPENDED, ...)
15	SDK React	Provider, hooks, componentes prontos (BaileysQRConnect, WabaEmbeddedSignup)
16	Changelog	Histórico de versões

Endpoints públicos (sem auth)

GET /health — liveness probe.
GET /health/ready — readiness (checa Postgres, Redis, S3).
GET /openapi.json — OpenAPI 3.0 spec auto-gerada.
GET /v1/meta-webhook / POST /v1/meta-webhook — webhook da Meta (Cloud API + Instagram).
POST /v1/asaas-webhook — webhook do gateway de pagamentos Asaas.
POST /v1/flows/data-exchange/:flowId — callback criptografado de WhatsApp Flows (RSA-OAEP).

Todos os demais endpoints /v1/* exigem X-API-Key.

Convenções gerais

IDs: UUID v4 em todos os recursos locais (phone.id, message.id, etc).
Datas: ISO-8601 com timezone (2026-05-21T14:33:00.000Z).
Paginação: cursor-based (cursor + nextCursor) com limit máximo 200.
Async ops: retornam 202 Accepted com status: 'enqueued' ou 'pending'.
Rate limit: 600 req/min por account (default), 300 req/min em POST /v1/messages.
Multi-tenancy: todo recurso é filtrado por accountId derivado da API key — nunca é necessário passá-lo no body.

Próximo passo

Comece em Getting Started para fazer seu primeiro envio.

O que é o wpp-gateway?​

Quando usar​

Arquitetura​

Sumário​

Endpoints públicos (sem auth)​

Convenções gerais​

Próximo passo​