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
Conexão
Retorna o status da instância.
{
"id": "inst_a1b2c3d4e5f6a7b8",
"name": "Clínica Centro",
"status": "open",
"phone": "5511999998888"
}
| Valor | Significado |
|---|---|
open | Conectada |
connecting | Conectando |
qr | Aguardando leitura do QR Code |
pairing | Aguardando o código por telefone |
disconnected | Desconectada |
Inicia a conexão por QR Code ou por código de telefone.
| Campo | Tipo | Descrição |
|---|---|---|
phone | string | Opcional. Com telefone, retorna pairingCode. Sem, retorna QR Code. |
{
"status": "qr",
"phone": null,
"qr": "2@AbCd...",
"qrImage": "data:image/png;base64,iVBORw0KGgo..."
}
{ "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.
Retorna o QR Code atual. Sem QR disponível, responde 404 QR_NOT_AVAILABLE.
Reinicia a conexão e mantém a sessão. Sem sessão salva, responde 409 NO_SESSION.
Desconecta e apaga a sessão. É preciso conectar de novo para enviar.
{ "status": "disconnected" }
Envio
Envia texto ou mídia.
| Campo | Tipo | Descrição |
|---|---|---|
chatId | string | Obrigatório. Telefone do destinatário. |
message | string | Texto. Em mídia, vira a legenda. |
mediaURL | string | URL pública do arquivo. |
mediaBase64 | string | Arquivo em base64. Não use com mediaURL. |
fileName | string | Nome do arquivo. |
mimetype | string | Tipo do arquivo. Detectado se omitido. |
ptt | boolean | Áudio como mensagem de voz. |
asDocument | boolean | Envia como documento. |
replyId | string | id da mensagem a responder. |
{
"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étodo | Rota | Corpo |
|---|---|---|
| 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/media | Baixa 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
Verifica se um número tem WhatsApp, sem enviar mensagem. A instância precisa estar conectada.
{ "chatId": "5511999998888", "exists": true, "jid": "5511999998888@s.whatsapp.net" }
Verifica se o serviço está no ar. Não exige autenticação.
{ "ok": true }
Webhook
Configurar
| Método | Rota | Descrição |
|---|---|---|
| GET | /instance/webhook | Configuração atual |
| PUT | /instance/webhook | Define a URL e os eventos. URL vazia desativa. |
| POST | /instance/webhook/test | Envia um evento de teste |
| Campo | Tipo | Descrição |
|---|---|---|
url | string | URL que recebe os eventos. |
events | string[] | Eventos desejados. |
fromMe | boolean | Inclui mensagens enviadas pelo celular. |
regenerateSecret | boolean | Gera um novo segredo. |
{
"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": { }
}
| Evento | Campos em data |
|---|---|
connection.update | status, phone |
message.received | id, chatId, phone, fromMe, pushName, timestamp, type, text, replyId, media |
message.status | id, chatId, status (sent, delivered, read, played) |
message.reaction | id, chatId, fromMe, emoji |
| Regra | Valor |
|---|---|
| Resposta esperada | 2xx em até 5 segundos |
| Reenvios | Até 3, após 2 s, 10 s e 30 s |
| Duplicidade | Eventos podem repetir. Use deliveryId para deduplicar. |
| Mídias | Ficam disponíveis por 7 dias |
| Grupos e histórico | Nã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.
$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;
}
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." } }
| HTTP | Código | Quando |
|---|---|---|
| 400 | VALIDATION_ERROR | Corpo inválido |
| 400 | INVALID_CHAT_ID | Telefone inválido |
| 400 | INVALID_MEDIA | Mídia inválida |
| 401 | UNAUTHORIZED | Chave ausente ou inválida |
| 404 | MESSAGE_NOT_FOUND | Mensagem não encontrada |
| 404 | REPLY_MESSAGE_NOT_FOUND | replyId desconhecido |
| 404 | QR_NOT_AVAILABLE | Sem QR Code no momento |
| 410 | MEDIA_EXPIRED | Mídia com mais de 7 dias |
| 409 | INSTANCE_NOT_CONNECTED | Instância desconectada |
| 409 | NO_SESSION | Instância sem sessão salva |
| 422 | NUMBER_NOT_ON_WHATSAPP | Número sem WhatsApp |
| 422 | GROUPS_DISABLED | Envio para grupos desativado |
| 422 | NOT_OWN_MESSAGE | Mensagem de outra pessoa |
| 429 | RATE_LIMITED | Limite de envios por hora. Veja details.retryAfterSeconds. |
| 502 | SEND_FAILED | Falha no envio. Tente novamente. |