API Reference

Visao Geral

WPP Gateway e uma API de WhatsApp com foco em disparo em massa e alta disponibilidade. O diferencial e o conceito de Instance Group - uma camada de orquestracao que gerencia multiplos numeros de WhatsApp como um pool unificado, com estrategias configuraveis de rotacao e failover.

Autenticacao

Todas as requisicoes autenticadas devem incluir o header X-API-Key.

GET /v1/groups HTTP/1.1
Host: localhost:8080
X-API-Key: wpp_7d0e60e402b57c375571d4d390a0ddeef86c154103c76a26...
Content-Type: application/json

{
  "success": true,
  "data": { ... },
  "meta": {
    "total": 10,
    "limit": 20,
    "offset": 0
  }
}

// Erro
{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "Group not found"
  }
}

Arquitetura

                    +-------------------------+
                    |      API Gateway         |
                    |   (Auth + Rate Limit)    |
                    +-----------+-------------+
                                |
                    +-----------v-------------+
                    |    Group Orchestrator    |
                    |  (Strategy Engine)       |
                    +-----------+-------------+
                                |
              +-----------------+-----------------+
              |                 |                  |
     +--------v-------+ +------v--------+ +------v--------+
     |  Instance A     | |  Instance B    | |  Instance C    |
     |  +55 11 9xxxx   | |  +55 11 8xxxx  | |  +55 21 9xxxx  |
     |  status: active | |  status: rest  | |  status: warm  |
     +--------+-------+ +------+--------+ +------+--------+
              |                 |                  |
              +-----------------+-----------------+
                                |
                    +-----------v-------------+
                    |   WhatsApp Servers       |
                    +-------------------------+

Registro / Conta

{
  "name": "Minha Empresa"
}

{
  "success": true,
  "data": {
    "api_key": "wpp_7d0e60e402b57c375571...",
    "tenant": {
      "id": "uuid",
      "name": "Minha Empresa",
      "plan": "basic",
      "max_groups": 5,
      "max_instances": 20,
      "is_active": true
    }
  }
}

Grupos

Instance Groups sao pools de numeros WhatsApp com estrategias de routing configuravel.

{
  "name": "campanha-marketing",
  "strategy": "rotation",
  "config": {
    "daily_budget_per_instance": 200,
    "hourly_budget_per_instance": 30,
    "min_delay_ms": 2000,
    "max_delay_ms": 7000
  },
  "webhook_url": "https://meusite.com/webhook",
  "webhook_events": ["message.sent", "message.delivered", "instance.banned"]
}

Instancias

Uma instancia = uma sessao WhatsApp = um numero. Gerenciadas dentro de um grupo.

{
  "display_name": "Celular 01",
  "priority": 1,
  "daily_budget": 200,
  "hourly_budget": 30
}

{
  "success": true,
  "data": {
    "qr_code": "2@ABC123...",
    "qr_base64": "iVBORw0KGgo...",
    "expires_in": 60
  }
}

{ "phone": "5511999999999" }

Mensagens

Envie mensagens via grupo (recomendado) - o orchestrator escolhe a melhor instancia automaticamente.

{
  "to": "5511999999999",
  "type": "text",
  "content": {
    "body": "Ola, tudo bem?"
  }
}

Texto

{ "to": "5511999999999", "type": "text", "content": { "body": "Ola!", "preview_url": true } }

Imagem

{
  "to": "5511999999999", "type": "image",
  "content": { "url": "https://exemplo.com/foto.jpg", "caption": "Veja!", "mime_type": "image/jpeg" }
}

Video

{
  "to": "5511999999999", "type": "video",
  "content": { "url": "https://exemplo.com/video.mp4", "caption": "Assista!", "mime_type": "video/mp4" }
}

Audio

{
  "to": "5511999999999", "type": "audio",
  "content": { "url": "https://exemplo.com/audio.ogg", "mime_type": "audio/ogg; codecs=opus", "ptt": true }
}

ptt: true = mensagem de voz. ptt: false = arquivo de audio.

Documento

{
  "to": "5511999999999", "type": "document",
  "content": { "url": "https://exemplo.com/doc.pdf", "mime_type": "application/pdf", "filename": "Contrato.pdf" }
}

Localizacao

{
  "to": "5511999999999", "type": "location",
  "content": { "latitude": -23.5505, "longitude": -46.6333, "name": "Escritorio SP", "address": "Av. Paulista, 1000" }
}

Contato (vCard)

{
  "to": "5511999999999", "type": "contact",
  "content": {
    "contacts": [{
      "name": { "formatted_name": "Joao Silva", "first_name": "Joao" },
      "phones": [{ "phone": "+5511999999999", "type": "CELL" }]
    }]
  }
}

Reacao

{ "to": "5511999999999", "type": "reaction", "content": { "message_id": "ABCDEF123", "emoji": "👍" } }

Envie emoji: "" para remover a reacao.

Enquete

{
  "to": "5511999999999", "type": "poll",
  "content": { "title": "Qual horario?", "options": ["Manha", "Tarde", "Noite"], "max_selections": 1 }
}

Botoes (ate 3)

{
  "to": "5511999999999", "type": "button",
  "content": {
    "body": "Escolha uma opcao:",
    "footer": "Responda clicando",
    "buttons": [
      { "id": "btn_sim", "text": "Sim" },
      { "id": "btn_nao", "text": "Nao" },
      { "id": "btn_info", "text": "Mais info" }
    ]
  }
}

Lista (ate 10 itens)

{
  "to": "5511999999999", "type": "list",
  "content": {
    "body": "Nosso cardapio:", "button_text": "Ver opcoes",
    "sections": [{
      "title": "Pizzas",
      "items": [
        { "id": "pizza_1", "title": "Margherita", "description": "R$ 39,90" },
        { "id": "pizza_2", "title": "Pepperoni", "description": "R$ 44,90" }
      ]
    }]
  }
}

Broadcasts

{
  "recipients": ["5511999999999", "5511888888888"],
  "type": "text",
  "content": { "body": "Ola {nome}!" },
  "variables": { "5511999999999": { "nome": "Joao" } },
  "options": { "shuffle_recipients": true, "spintax": true }
}

Metricas

Blacklist

{ "numbers": ["5511999999999", "5511888888888"], "reason": "opt_out" }

Webhooks

{
  "url": "https://meusite.com/webhook",
  "events": ["message.sent", "message.delivered", "message.failed", "instance.status_changed"]
}

Schemas

Status & Estrategias