Documentação da API

Conexão, envio, verificação e webhook por REST.

Introdução

URL base: https://waapi.apphub.com.br

Requisições e respostas em JSON (Content-Type: application/json). Cada instância representa um número de WhatsApp e tem uma chave própria.

Telefones: DDI + DDD + número, só dígitos. Exemplo: 5511999998888.

Horários em UTC, no formato ISO 8601 (2026-11-19T15:00:00.000Z).

Autenticação

Envie a chave da instância no header Authorization.

Authorization: Bearer wk_sua_chave
A chave dá acesso total à instância. Guarde no servidor e nunca exponha no navegador ou no app.

Conexão

GET/instance

Retorna o status da instância.

Exemplo

  
Resposta 200
{
  "id": "inst_a1b2c3d4e5f6a7b8",
  "name": "Clínica Centro",
  "status": "open",
  "phone": "5511999998888"
}
Status
ValorSignificado
openConectada
connectingConectando
qrAguardando leitura do QR Code
pairingAguardando o código por telefone
disconnectedDesconectada
POST/instance/connect

Inicia a conexão por QR Code ou por código de telefone.

Corpo
CampoTipoDescrição
phonestringOpcional. Com telefone, retorna pairingCode. Sem, retorna QR Code.
Exemplo

  
Resposta 200 (QR Code)
{
  "status": "qr",
  "phone": null,
  "qr": "2@AbCd...",
  "qrImage": "data:image/png;base64,iVBORw0KGgo..."
}
Resposta 200 (código por telefone)
{ "status": "pairing", "phone": null, "pairingCode": "ABCD1234" }

Consulte GET /instance a cada 2 ou 3 segundos até status ser open. O QR Code renova a cada cerca de 20 segundos.

GET/instance/qr

Retorna o QR Code atual. Sem QR disponível, responde 404 QR_NOT_AVAILABLE.


POST/instance/restart

Reinicia a conexão e mantém a sessão. Sem sessão salva, responde 409 NO_SESSION.


POST/instance/logout

Desconecta e apaga a sessão. É preciso conectar de novo para enviar.


  
Resposta 200
{ "status": "disconnected" }

Envio

POST/messages/send

Envia texto ou mídia.

Corpo
CampoTipoDescrição
chatIdstringObrigatório. Telefone do destinatário.
messagestringTexto. Em mídia, vira a legenda.
mediaURLstringURL pública do arquivo.
mediaBase64stringArquivo em base64. Não use com mediaURL.
fileNamestringNome do arquivo.
mimetypestringTipo do arquivo. Detectado se omitido.
pttbooleanÁudio como mensagem de voz.
asDocumentbooleanEnvia como documento.
replyIdstringid da mensagem a responder.
Texto

  
Arquivo

  
Resposta 201
{
  "id": "3EB0C431D5A2F1E0A9B7",
  "chatId": "5511999998888@s.whatsapp.net",
  "timestamp": 1763520000,
  "status": "sent"
}

Guarde o id: ele identifica a mensagem nos webhooks. Grupos não são aceitos. Corpo máximo: 25 MB.

Ações em mensagens

Usam o id da mensagem retornado no envio ou no webhook.

MétodoRotaCorpo
POST/messages/react{ "messageId", "emoji" } (emoji vazio remove)
POST/messages/edit{ "messageId", "message" }
POST/messages/delete{ "messageId" } (apaga para todos)
POST/messages/read{ "messageIds": [] }
POST/messages/presence{ "chatId", "presence" }: composing, recording, paused, available, unavailable
GET/messages/:id/mediaBaixa a mídia de uma mensagem
GET/messages/recentÚltimas mensagens guardadas. Query: chatId, limit (até 100), before. Para depuração.

Editar e apagar valem só para mensagens enviadas pela instância.

Verificação

POST/messages/check

Verifica se um número tem WhatsApp, sem enviar mensagem. A instância precisa estar conectada.

Exemplo

  
Resposta 200
{ "chatId": "5511999998888", "exists": true, "jid": "5511999998888@s.whatsapp.net" }
GET/health

Verifica se o serviço está no ar. Não exige autenticação.


  
Resposta 200
{ "ok": true }

Webhook

Configurar

MétodoRotaDescrição
GET/instance/webhookConfiguração atual
PUT/instance/webhookDefine a URL e os eventos. URL vazia desativa.
POST/instance/webhook/testEnvia um evento de teste
Corpo do PUT
CampoTipoDescrição
urlstringURL que recebe os eventos.
eventsstring[]Eventos desejados.
fromMebooleanInclui mensagens enviadas pelo celular.
regenerateSecretbooleanGera um novo segredo.

  
GET, resposta 200
{
  "url": "https://seudominio.com.br/webhook",
  "events": ["message.received", "message.status"],
  "fromMe": false,
  "secret": "whsec_...",
  "lastAt": "2026-11-19T15:00:00.000Z",
  "lastStatus": "200",
  "availableEvents": ["connection.update", "message.received", "message.status", "message.reaction"]
}

Eventos

A API envia POST JSON para a sua URL.

{
  "event": "message.received",
  "instanceId": "inst_a1b2c3d4e5f6a7b8",
  "deliveryId": "6f1c0a52-8d0e-4c0e-9d7a-2a1f6c5e0b11",
  "timestamp": 1763520000,
  "data": { }
}
EventoCampos em data
connection.updatestatus, phone
message.receivedid, chatId, phone, fromMe, pushName, timestamp, type, text, replyId, media
message.statusid, chatId, status (sent, delivered, read, played)
message.reactionid, chatId, fromMe, emoji
Entrega
RegraValor
Resposta esperada2xx em até 5 segundos
ReenviosAté 3, após 2 s, 10 s e 30 s
DuplicidadeEventos podem repetir. Use deliveryId para deduplicar.
MídiasFicam disponíveis por 7 dias
Grupos e históricoNão são enviados

Em media, o campo url é um caminho relativo: GET /messages/:id/media com a chave da instância devolve o arquivo. Após 7 dias, responde 410 MEDIA_EXPIRED.

Assinatura

Cada entrega traz o header X-Waapi-Signature: sha256=<hash>. O hash é o HMAC-SHA256 do corpo bruto, com o segredo do webhook. Valide antes de processar.

PHP
$body = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $body, $secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_WAAPI_SIGNATURE'] ?? '')) {
    http_response_code(401);
    exit;
}
Node.js
import { createHmac, timingSafeEqual } from 'node:crypto';

const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
const ok = expected.length === signature.length &&
  timingSafeEqual(Buffer.from(expected), Buffer.from(signature));

Outros headers: X-Waapi-Event e X-Waapi-Delivery.

Erros

Erros retornam o status HTTP e este corpo:

{ "error": { "code": "INSTANCE_NOT_CONNECTED", "message": "A instância não está conectada." } }
HTTPCódigoQuando
400VALIDATION_ERRORCorpo inválido
400INVALID_CHAT_IDTelefone inválido
400INVALID_MEDIAMídia inválida
401UNAUTHORIZEDChave ausente ou inválida
404MESSAGE_NOT_FOUNDMensagem não encontrada
404REPLY_MESSAGE_NOT_FOUNDreplyId desconhecido
404QR_NOT_AVAILABLESem QR Code no momento
410MEDIA_EXPIREDMídia com mais de 7 dias
409INSTANCE_NOT_CONNECTEDInstância desconectada
409NO_SESSIONInstância sem sessão salva
422NUMBER_NOT_ON_WHATSAPPNúmero sem WhatsApp
422GROUPS_DISABLEDEnvio para grupos desativado
422NOT_OWN_MESSAGEMensagem de outra pessoa
429RATE_LIMITEDLimite de envios por hora. Veja details.retryAfterSeconds.
502SEND_FAILEDFalha no envio. Tente novamente.