Documentacao API

Autenticacao

Todas as rotas exigem o header x-api-key com uma API Key ativa.

x-api-key: sua-api-key-aqui

Gerencie suas API Keys na pagina API Keys.

Rate Limiting

Todas as rotas possuem limite de requisicoes por minuto. Quando excedido, a API retorna 429 Too Many Requests.

Headers de resposta

Header	Descricao
X-RateLimit-Limit	Limite de requisicoes por minuto da sua conta
X-RateLimit-Remaining	Requisicoes restantes na janela atual
X-RateLimit-Reset	Timestamp (Unix) quando a janela reseta

O limite padrao e 60 req/min. Caso precise de mais, contate o administrador.

Conectar um novo numero

1

POST /session/connect — Inicia uma nova conexao e retorna um tempId

2

GET /session/pending/{tempId}/qr — Obtenha o QR code para escanear
Alternativa: POST /session/pending/{tempId}/pairing-code — Obtenha um codigo numerico de 8 caracteres para vincular sem QR

3

GET /session/pending/{tempId}/status — Monitore ate conectar; a resposta incluira o phone_number

4

Use o phone_number como identificador em todas as rotas operacionais

POST /session/connect

Inicia uma nova conexao WhatsApp. Retorna um ID temporario para acompanhar o processo.

Body (JSON, opcional)

Campo	Tipo	Descricao
webhookUrl	string	URL para receber eventos via webhook
displayName	string	Nome de exibicao do numero
proxyHost	string	Host do proxy
proxyPort	integer	Porta do proxy
proxyUser	string	Usuario do proxy
proxyPass	string	Senha do proxy
proxyType	string	`http` ou `socks5` (padrao: http)

Resposta

{
  "status": true,
  "tempId": "a1b2c3d4e5f6...",
  "message": "Session started, use the tempId to get QR code"
}

GET /session/pending/{tempId}/qr

Retorna o QR code da sessao pendente como imagem base64.

Resposta

{
  "status": true,
  "qr": "data:image/png;base64,iVBOR..."
}

Faca polling a cada 2-3 segundos ate obter o QR. Se status: false, o QR ainda nao esta pronto.

POST /session/pending/{tempId}/pairing-code

Alternativa ao QR code. Retorna um codigo numerico de 8 caracteres para vincular o dispositivo. No celular, va em Dispositivos Vinculados > Vincular com numero de telefone e insira o codigo.

Body (JSON)

Campo	Tipo	Obrigatorio	Descricao
phoneNumber	string	Sim	Numero do telefone a vincular (ex: `5511999998888`)

Resposta

{
  "status": true,
  "pairingCode": "A1B2-C3D4"
}

O codigo expira em ~60 segundos. Pode solicitar novo codigo na mesma sessao. Nota: apos solicitar pairing code, o QR code nao sera mais emitido naquela sessao.

GET /session/pending/{tempId}/status

Monitora o status da conexao pendente. Quando conectado, retorna o numero de telefone.

Resposta (aguardando)

{
  "status": true,
  "connected": false,
  "sessionStatus": "awaiting_auth"
}

Resposta (conectado)

{
  "status": true,
  "connected": true,
  "sessionStatus": "connected",
  "phone_number": "5511999998888"
}

O tempId expira apos 5 minutos se nao for escaneado.

GET /session/numbers

Lista todos os numeros conectados da sua conta com status em tempo real.

Resposta

{
  "status": true,
  "numbers": [
    {
      "phone_number": "5511999998888",
      "display_name": "Atendimento",
      "status": "connected",
      "webhook_url": "https://meusite.com/webhook",
      "created_at": "2026-02-24T12:00:00.000Z"
    }
  ]
}

GET /session/{number}/status

Retorna o status da sessao de um numero especifico.

Resposta

{
  "status": true,
  "connected": true,
  "sessionStatus": "connected",
  "message": "Session is authenticated"
}

POST /session/{number}/send-message

Envia uma mensagem de texto.

Body (JSON)

Campo	Tipo	Obrigatorio	Descricao
to	string	Sim	Numero destino (ex: `5511999998888`)
message	string	Sim	Texto da mensagem
humanMode	boolean	Nao	Simula comportamento humano antes do envio (marca como lido, digitando..., delay aleatorio)

Exemplo

{
  "to": "5521988887777",
  "message": "Ola! Tudo bem?",
  "humanMode": true
}

Resposta

{
  "status": true,
  "message": "Message sent",
  "messageId": "BAE5F2A7C4B8D123"
}

O messageId pode ser usado para rastrear o status de entrega via GET /session/{number}/messages/{messageId}/status.

POST /session/{number}/send-media

Envia arquivo. Aceita dois formatos: upload (multipart/form-data) ou base64 (application/json).

Opcao 1 — File upload (multipart/form-data)

Campo	Tipo	Obrigatorio	Descricao
to	string	Sim	Numero destino
file	file	Sim	Arquivo a enviar
caption	string	Nao	Texto de legenda (imagens, videos, documentos)
sendAudioAsVoice	boolean	Nao	Enviar audio como mensagem de voz
humanMode	boolean	Nao	Simula comportamento humano antes do envio (marca como lido, digitando..., delay aleatorio)

Opcao 2 — Base64 (application/json)

Campo	Tipo	Obrigatorio	Descricao
to	string	Sim	Numero destino
base64	string	Sim	Conteudo do arquivo em base64
filename	string	Sim	Nome do arquivo (ex: `foto.jpg`)
mimetype	string	Sim	Tipo MIME (ex: `image/jpeg`)
caption	string	Nao	Texto de legenda (imagens, videos, documentos)
sendAudioAsVoice	boolean	Nao	Enviar audio como mensagem de voz
humanMode	boolean	Nao	Simula comportamento humano antes do envio (marca como lido, digitando..., delay aleatorio)

Exemplo base64

{
  "to": "5521988887777",
  "base64": "iVBORw0KGgo...",
  "filename": "foto.jpg",
  "mimetype": "image/jpeg",
  "caption": "Confira esta imagem!",
  "humanMode": true
}

Resposta

{
  "status": true,
  "message": "File sent",
  "messageId": "BAE5F2A7C4B8D456"
}

GET /session/{number}/contacts

Lista os contatos do WhatsApp conectado.

GET /session/{number}/contacts/{contactId}

Retorna detalhes de um contato especifico, incluindo foto de perfil.

GET /session/{number}/chats

Lista as conversas do WhatsApp conectado.

GET /session/{number}/chats/{chatId}

Retorna detalhes de uma conversa com as ultimas mensagens.

Query params

Param	Tipo	Padrao	Descricao
limit	integer	10	Quantidade de mensagens
mediaBase64	boolean	false	Incluir midia como base64

GET /session/{number}/download-media/{messageId}

Faz download da midia de uma mensagem especifica.

Resposta

{
  "status": true,
  "media": {
    "mimetype": "image/jpeg",
    "data": "base64...",
    "filename": "photo.jpg"
  }
}

DELETE /session/{number}

Desconecta e remove o numero da sua conta. Faz logout do WhatsApp.

Resposta

{
  "status": true,
  "message": "Number disconnected and removed"
}

Quando configurado, o sistema envia eventos para a URL de webhook via POST.

Seguranca — Assinatura HMAC

Toda requisicao de webhook inclui o header X-Webhook-Signature com uma assinatura HMAC-SHA256. Use o webhook_secret disponivel na pagina API Keys para validar a autenticidade.

const crypto = require('crypto');
const signature = req.headers['x-webhook-signature'];
const expected = crypto.createHmac('sha256', webhookSecret)
    .update(JSON.stringify(req.body)).digest('hex');
const valid = signature === expected;

Retry automatico

Se a entrega falhar, o sistema faz ate 3 tentativas com backoff: imediato, 5s, 30s, 120s. Todas as tentativas sao registradas e visiveis em GET /session/{number}/webhook-logs.

Evento: message_received

{
  "event": "message_received",
  "phoneNumber": "5511999998888",
  "message": {
    "id": "ABCDEF123456",
    "body": "Ola!",
    "type": "chat",
    "from": "5521988887777",
    "to": "5511999998888",
    "timestamp": 1708800000,
    "hasMedia": false,
    "pushName": "Joao"
  }
}

Evento: message_status_updated

Enviado quando o status de uma mensagem muda (entregue, lido, etc.).

{
  "event": "message_status_updated",
  "phoneNumber": "5511999998888",
  "messageId": "BAE5F2A7C4B8D123",
  "status": "delivered",
  "timestamp": 1708800005000
}

Evento: webhook_test

Enviado ao clicar em "Testar Webhook" no painel. Use para validar que a URL esta acessivel e a assinatura HMAC esta correta.

{
  "event": "webhook_test",
  "phoneNumber": "5511999998888",
  "timestamp": 1708800000000,
  "message": "This is a test event from WA Gateway"
}

Evento: session_disconnected

Enviado sempre que o numero desconecta, seja por logout ou por queda temporaria (perda de conexao, reinicio, etc). O campo reason diferencia os casos:

reason	Descricao
logged_out	O usuario fez logout do WhatsApp (sessao encerrada permanentemente)
disconnected	Desconexao temporaria (queda de rede, reinicio). O sistema tentara reconectar automaticamente

{
  "event": "session_disconnected",
  "phoneNumber": "5511999998888",
  "reason": "logged_out" // ou "disconnected"
}

Codigo	Descricao
`400`	Requisicao invalida (parametros faltando ou sessao nao pronta)
`403`	API Key invalida ou conta inativa
`404`	Numero nao encontrado ou sessao pendente expirada
`429`	Rate limit excedido — muitas requisicoes. Verifique os headers `X-RateLimit-*`
`500`	Erro interno do servidor

Documentacao da API

Autenticacao

Rate Limiting

Headers de resposta

Fluxo de uso

Conectar um novo numero

Rotas de Conexao

Body (JSON, opcional)

Resposta

Resposta

Body (JSON)

Resposta

Resposta (aguardando)

Resposta (conectado)

Rotas Operacionais

Resposta

Resposta

Body (JSON)

Exemplo

Resposta

Opcao 1 — File upload (multipart/form-data)

Opcao 2 — Base64 (application/json)

Exemplo base64

Resposta

Query params

Resposta

Resposta

Webhook

Seguranca — Assinatura HMAC

Retry automatico

Evento: message_received

Evento: message_status_updated

Evento: webhook_test

Evento: session_disconnected

Codigos de Erro