Guia de Integração

Siga este guia passo a passo para integrar WhatsApp em seu sistema.

Passo 1: Obter Secret Key

Para usar a API, você precisa de uma Secret Key.

Para Desenvolvimento Local:
  1. Crie um arquivo .env na raiz do projeto
  2. Copie o conteúdo de env.example.txt
  3. Gere uma secret key forte (ex: openssl rand -hex 32)
  4. Configure: GATEWAY_SECRET=sua-chave-gerada
Para Produção:

Entre em contato com o administrador do sistema para obter a secret key de produção.

GATEWAY_SECRET=sua-chave-secreta-aqui
Importante: A secret key é usada no header X-Gateway-Secret em todas as requisições. Mantenha-a segura e nunca a compartilhe publicamente.
Passo 2: Criar uma Sessão

Crie uma sessão (canal) para conectar um número do WhatsApp:

Base URL:
Desenvolvimento: http://localhost:3000
Produção: https://wpp.pixel12digital.com.br
IMPORTANTE - Rotas Públicas:
A API pública está em /api/*. NÃO existe /v1/* nem /api/v1/*. Use apenas /api/*.
Via API:
curl -X POST "https://wpp.pixel12digital.com.br/api/channels" \
  -H "X-Gateway-Secret: sua-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"channel": "meu-canal"}'
Via Interface Web:

Acesse Sessões e crie uma nova sessão.

Passo 3: Conectar WhatsApp (QR Code)

Obtenha o QR code e escaneie com seu WhatsApp:

Via API:
curl -X GET "https://wpp.pixel12digital.com.br/api/channels/meu-canal/qr" \
  -H "X-Gateway-Secret: sua-secret-key"

Abra o WhatsApp no celular > Configurações > Aparelhos conectados > Conectar um aparelho

A resposta contém um campo qr (data URI) que pode ser usado diretamente em uma tag <img> ou convertido para imagem.

Passo 4: Enviar Primeira Mensagem

Envie sua primeira mensagem via API:

Formato de Número:
Use formato internacional: Código do país + DDD + número (sem espaços ou caracteres especiais)
Exemplos corretos: 5511999999999, 5511987654321
Exemplos incorretos: +55 11 99999-9999, 11999999999, 5511999999999@c.us 
curl -X POST "https://wpp.pixel12digital.com.br/api/messages" \
  -H "X-Gateway-Secret: sua-secret-key" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "meu-canal",
    "to": "5511999999999",
    "text": "Olá! Esta é minha primeira mensagem."
  }'

Certifique-se de que a sessão está "connected" antes de enviar mensagens.

Como verificar o status:
curl -H "X-Gateway-Secret: sua-secret-key" \
  https://wpp.pixel12digital.com.br/api/channels/meu-canal
Resposta de exemplo do envio:
{
  "success": true,
  "message_id": "msg_123ABC",
  "channel": "meu-canal",
  "to": "5511999999999",
  "status": "sent",
  "timestamp": "2026-01-08T15:00:00.000Z",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000"
}
IMPORTANTE - message_id pode ser null:
O campo message_id pode ser null na resposta. Isso é normal! Dependendo do driver (WPPConnect/Baileys), o message_id não é retornado de forma síncrona. O rastreamento confiável é feito via correlationId que permite cruzar logs, eventos de webhook (message.ack) e logs do sistema.
Exemplo com message_id null (também é válido): 
{
  "success": true,
  "message_id": null,
  "channel": "meu-canal",
  "to": "5511999999999",
  "status": "sent",
  "timestamp": "2026-01-08T15:00:00.000Z",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000"
}
Rastreamento com correlationId:
Use correlationId para cruzar logs + eventos de webhook + logs do sistema. O webhook message.ack também inclui o correlationId para correlação. Para rastreamento confiável, não dependa apenas de message_id - use correlationId.
Resposta de exemplo do status do canal:
{
  "success": true,
  "channel": {
    "id": "meu-canal",
    "name": "meu-canal",
    "status": "connected"
  },
  "created_at": "2024-01-15T10:00:00.000Z",
  "updated_at": "2024-01-15T10:30:00.000Z",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000"
}
Como obter o Channel ID:
Antes de enviar mensagens, liste os canais com GET /api/channels. A resposta retorna um array de objetos com id, name e status. Os campos id e name NUNCA são null ou vazios - sempre retornam valores válidos. Use o campo id como Channel ID nas requisições.
Passo 5: Configurar Webhooks (Opcional)

Configure webhooks para receber mensagens em tempo real:

Importante: Você NÃO precisa configurar nada no WPPConnect Server diretamente. O gateway já está configurado para receber eventos automaticamente. 
curl -X POST "https://wpp.pixel12digital.com.br/api/channels/meu-canal/webhook" \
  -H "X-Gateway-Secret: sua-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://seu-servidor.com/api/whatsapp/webhook"}'

Quando uma mensagem for recebida, o gateway enviará um POST para sua URL com o evento.

Eventos disponíveis:
  • message - Nova mensagem recebida
  • message.ack - Confirmação de leitura
  • connection.update - Mudança de status da conexão
Exemplos de Payload:
Evento: message 
{
  "event": "message",
  "channel": "Pixel12 Digital",
  "timestamp": "2026-01-08T23:45:12Z",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
  "message": {
    "id": "msg_123",
    "from": "5511999999999",
    "to": "SEU_NUMERO",
    "text": "Oi, tudo bem?",
    "type": "text"
  }
}
Evento: message.ack 
{
  "event": "message.ack",
  "channel": "Pixel12 Digital",
  "timestamp": "2026-01-08T23:45:20Z",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
  "ack": {
    "messageId": "msg_123",
    "status": "sent"
  }
}
Valores de status: queued, sent, delivered, read, failed
Rastreamento: O campo correlationId permite correlacionar este ACK com a requisição original de envio de mensagem. Use-o para cruzar logs e eventos.
Evento: connection.update 
{
  "event": "connection.update",
  "channel": "Pixel12 Digital",
  "timestamp": "2026-01-08T23:45:30Z",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
  "connection": {
    "status": "connected"
  }
}
Valores: connected, disconnected, connecting, qr_required
Headers dos Webhooks:
Content-Type: application/json
X-Correlation-ID: 550e8400-e29b-41d4-a716-446655440000
X-Webhook-Secret: <SEU_WEBHOOK_SECRET>  (se configurado)
User-Agent: WhatsApp-Gateway-Wrapper/1.0
Requisitos do Endpoint Cliente:
  • HTTPS público: O endpoint deve ser acessível via HTTPS público (não localhost/privado)
  • Resposta rápida: Responder com HTTP 200 OK em até 5 segundos
  • Idempotência: Processar eventos de forma idempotente (use correlationId ou eventId se disponível)
  • Validação de segurança: Validar o header X-Webhook-Secret antes de processar
  • Enfileiramento: Recomenda-se enfileirar o processamento (não bloquear o gateway)
  • Retries: O gateway pode tentar reenviar eventos em caso de falha (timeout, 5xx, etc.)
Comportamento em Falha:
  • Se o endpoint retornar HTTP 5xx ou timeout, o gateway pode tentar reenviar
  • Eventos são enviados de forma assíncrona - falhas não bloqueiam o processamento principal
  • Use correlationId para identificar eventos duplicados e evitar processamento duplo

Exemplos de Código

Python
import requests

BASE_URL = "https://wpp.pixel12digital.com.br"  # Use http://localhost:3000 para desenvolvimento
SECRET = "sua-secret-key"

headers = {
    "X-Gateway-Secret": SECRET,
    "Content-Type": "application/json"
}

response = requests.post(
    f"{BASE_URL}/api/messages",
    json={"channel": "meu-canal", "to": "5511999999999", "text": "Olá!"},
    headers=headers
)
print(response.json())
Node.js
const axios = require('axios');

const BASE_URL = 'https://wpp.pixel12digital.com.br'; // Use http://localhost:3000 para desenvolvimento
const SECRET = 'sua-secret-key';

const headers = {
  'X-Gateway-Secret': SECRET,
  'Content-Type': 'application/json'
};

axios.post(`${BASE_URL}/api/messages`, {
  channel: 'meu-canal',
  to: '5511999999999',
  text: 'Olá!'
}, { headers })
  .then(response => console.log(response.data))
  .catch(error => console.error(error));

Tratamento de Erros

401 - Unauthorized
{
  "success": false,
  "error": "Missing X-Gateway-Secret header",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000"
}

Solução: Adicione o header X-Gateway-Secret na requisição.

403 - Forbidden
{
  "success": false,
  "error": "Invalid X-Gateway-Secret",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000"
}

Solução: Verifique se a secret key está correta.

400 - Bad Request
{
  "success": false,
  "error": "channel (session_id) is required",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000"
}

Solução: Verifique se todos os campos obrigatórios foram enviados.

404 - Not Found
{
  "success": false,
  "error": "Channel not found",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000"
}

Solução: Verifique se o canal existe usando GET /api/channels. Se receber 404 em rotas com /v1/, verifique se está usando /api/* (sem /v1/).

Checklist de Integração
Próximos Passos