Getting Started

Este guia te leva do zero a enviar a primeira mensagem via WhatsApp em menos de 10 minutos.

Pré-requisitos

1. Uma account no wpp-gateway. Accounts são criadas pelo time admin via POST /v1/admin/accounts (ver Authentication).
2. Uma API key ativa (ak_live_...) — emitida via POST /v1/admin/api-keys.
3. URL base: https://wpp.ogmma.com.br.

---

Conceitos chave

Account

Tenant da plataforma. Cada account tem:

• Uma lista de phones (canais).
• Uma ou mais API keys.
• Um plano de billing (pay_as_you_go, flat, free_tier, etc).
• Configurações BYO-key (OpenAI) opcionais.
• Estado de dunning (NONE, WARNING, CRITICAL, SUSPENDED) baseado em faturas em aberto.

Accounts não são criadas via API pública — só admin com X-Admin-Token.

Phone (canal)

Representa uma conexão com um número WhatsApp ou conta Instagram. Tem type imutável: BAILEYS, WABA ou INSTAGRAM.

Cada phone tem seu próprio:

• status (PENDING_QR, CONNECTED, DISCONNECTED, ...).
• webhookUrl opcional (HTTP POST quando algo acontece).
• Credenciais (token Meta criptografado, auth state Baileys, etc — nunca expostos via API).
• AI Agent opcional (1 por phone).

API key

Token que identifica a account. Formato: ak_live_<base64url>. Enviada em todo request em X-API-Key.

X-API-Key: ak_live_QWj3...XzY9

Channel type

Type	Caso de uso	Limitações
BAILEYS	Atendimento humano, alto volume, mensagens não estruturadas	Não oficial — risco de ban Meta; sem templates aprovados
WABA	Notificações, marketing transacional, fluxos de negócio	Custo por conversa (24h window), exige templates aprovados
INSTAGRAM	Messenger via Instagram Business	Limitado a texto + mídia, sem grupos

---

Primeiro request — listar phones

A operação mais simples: listar phones da sua account.

curl:

curl https://wpp.ogmma.com.br/v1/phones \
  -H "X-API-Key: ak_live_..."

Node (fetch):

const res = await fetch('https://wpp.ogmma.com.br/v1/phones', {
  headers: { 'X-API-Key': process.env.WPP_API_KEY },
});
const phones = await res.json();
console.log(phones);

Python (requests):

import os, requests
res = requests.get(
    'https://wpp.ogmma.com.br/v1/phones',
    headers={'X-API-Key': os.environ['WPP_API_KEY']},
)
print(res.json())

Se a chave estiver correta, você recebe 200 OK com um array (pode estar vazio na primeira chamada):

[]

---

Fluxo típico end-to-end

1. Criar um phone Baileys

curl -X POST https://wpp.ogmma.com.br/v1/phones \
  -H "X-API-Key: ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "BAILEYS",
    "label": "Atendimento Vendas",
    "webhook": {
      "url": "https://api.minhaempresa.com/wpp-events",
      "secret": "minha-chave-secreta-de-16+-chars",
      "events": ["message:received", "message:status", "channel:connected"]
    }
  }'

Resposta 201 Created:

{
  "id": "5f7b2e1c-3d4a-4e5f-9a8b-1c2d3e4f5a6b",
  "type": "BAILEYS",
  "label": "Atendimento Vendas",
  "status": "PENDING_QR",
  "webhookUrl": "https://api.minhaempresa.com/wpp-events",
  "createdAt": "2026-05-21T14:00:00.000Z"
}

2. Pegar o QR code (polling)

curl https://wpp.ogmma.com.br/v1/phones/5f7b2e1c-.../qrcode \
  -H "X-API-Key: ak_live_..."

• Se ainda não estiver pronto: 425 Too Early com code: QR_NOT_READY — tente de novo em 1-2s.
• Quando pronto: 200 OK com { qr, dataUrl } (data URL é PNG base64 pronto pra <img>).

Renderize o dataUrl na sua interface e peça pro usuário escanear no celular.

3. Aguardar channel:connected no webhook

Quando o WhatsApp do celular escaneia o QR, o gateway publica:

{
  "id": "...",
  "type": "channel:connected",
  "accountId": "...",
  "phoneId": "5f7b2e1c-...",
  "timestamp": "2026-05-21T14:01:23.000Z",
  "data": { "phoneNumber": "5511999998888" }
}

Seu endpoint registrado em webhook.url recebe esse JSON via HTTP POST com header X-WppGateway-Signature (HMAC-SHA256). Ver Webhooks.

4. Enviar uma mensagem de texto

curl -X POST https://wpp.ogmma.com.br/v1/messages \
  -H "X-API-Key: ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "phoneId": "5f7b2e1c-3d4a-4e5f-9a8b-1c2d3e4f5a6b",
    "to": "5511988887777",
    "type": "text",
    "content": { "text": "Olá! Recebi seu contato e já vou te ajudar." }
  }'

Resposta 202 Accepted:

{ "messageId": "9a1b2c3d-...", "status": "QUEUED" }

A mensagem entra na fila (BullMQ) e é despachada pelo Worker. Você recebe message:status no seu webhook quando virar SENT, depois DELIVERED, depois READ.

5. Receber mensagens

Toda mensagem inbound (cliente → seu phone) gera evento message:received no seu webhook:

{
  "id": "...",
  "type": "message:received",
  "accountId": "...",
  "phoneId": "5f7b2e1c-...",
  "timestamp": "2026-05-21T14:05:11.000Z",
  "data": {
    "whatsappMessageId": "ABCD1234EFGH...",
    "fromMe": false,
    "type": "text",
    "content": { "text": "Quero saber sobre o produto X" },
    "from": { "canonicalKey": "+5511988887777", "pn": "5511988887777", "type": "phone" },
    "chat": { "canonicalKey": "+5511988887777", "pn": "5511988887777", "type": "phone" },
    "pushName": "João da Silva"
  }
}

Detalhes do payload em Webhooks → message:received.

---

Próximos passos

• Phones — todos endpoints de gestão de canais (incl. WABA embedded signup, Instagram OAuth).
• Messages — todos os 15 tipos suportados (template, button, list, location, contact, sticker, ...).
• Webhooks — assinatura HMAC, retry, replay manual.
• SDK React — componentes prontos (<BaileysQRConnect>, <WabaEmbeddedSignup>) para usar no frontend.

Suporte

Erros não documentados? Ver catálogo de erros ou abrir issue no repositório paulorbj/wpp-gateway.