WhatsmiauWhatsmiau
Chave API

Webhooks

Configure webhooks para receber eventos em tempo real via HTTP POST.

POST

Configurar Webhook

/webhook/set/:instance

Define ou atualiza a configuração de webhook para uma instância. Permite configurar URL de destino, eventos que serão enviados e formato do payload.

webhook.enabledbooleanOpcional

Ativa ou desativa o webhook.

webhook.urlstringOpcional

URL que receberá os eventos via POST.

webhook.headersobjectOpcional

Headers HTTP enviados junto com cada evento (ex: Authorization). Aceita até 20, nomes únicos ignorando maiúsculas, e exige URL https.

webhook.eventsstring[]Opcional

Lista de eventos para filtrar. Se omitida, nenhum evento é entregue

webhook.base64booleanOpcional

Se true, codifica o payload em base64.

curl -X POST https://api.whatsmiau.dev/v2/webhook/set/MinhaInstancia \
  -H "Content-Type: application/json" \
  -H "apikey: SUA_CHAVE_AQUI" \
  -d '{
    "webhook": {
      "enabled": true,
      "url": "https://meusite.com/webhook",
      "events": ["messages.upsert", "connection.update", "call"]
    }
  }'
GET

Consultar Webhook

/webhook/find/:instance

Retorna a configuração atual de webhook para uma instância.

curl -X GET https://api.whatsmiau.dev/v2/webhook/find/MinhaInstancia \
  -H "apikey: SUA_CHAVE_AQUI"

Eventos de Webhook

Todos os eventos são enviados como HTTP POST para a URL configurada, dentro de um envelope padrão. O campo data varia conforme o tipo de evento.

Envelope

{
  event: string           // Tipo do evento (ex: "messages.upsert")
  instance: string        // ID da instância
  data: T                 // Payload específico do evento (ver abaixo)
  date_time: string       // Timestamp ISO 8601
  sender: string          // Remetente (quando aplicável)
  server_url: string      // URL do servidor
}
EVENT

messages.upsert

Disparado quando uma nova mensagem é recebida ou enviada. Inclui mensagens de texto, imagens, vídeos, áudios, documentos, reações, contatos, listas e botões.

Campos do payload (data)

keyobject

Identificador da mensagem.

remoteJid string

JID do chat (ex: 5511999999999@s.whatsapp.net).

fromMe boolean

Se a mensagem foi enviada por você.

id string

ID único da mensagem.

participant string?

JID do remetente em grupos.

pushName string

Nome de exibição do remetente.

status string

"sent" ou "received".

messageobject

Conteúdo da mensagem. Apenas um dos campos abaixo estará presente por vez:

conversation string?

Mensagem de texto simples.

imageMessage ImageMessage?

Imagem com url, mimetype, caption, width, height.

videoMessage VideoMessage?

Vídeo com url, mimetype, caption, seconds.

audioMessage AudioMessage?

Áudio com url, mimetype, seconds, ptt (voz).

documentMessage DocumentMessage?

Documento com url, mimetype, fileName, title.

reactionMessage ReactionMessage?

Reação com key (mensagem alvo) e text (emoji).

contactMessage ContactMessage?

Contato com displayName e vCard.

listResponseMessage ListResponseMessage?

Resposta de lista com title e singleSelectReply.selectedRowId.

mediaUrl string?

URL pública da mídia (imagem, áudio, vídeo, documento) após upload no storage.

messageType string

Tipo da mensagem (ex: "conversation", "imageMessage", "audioMessage").

messageTimestamp number

Unix timestamp em segundos.

instanceId string

ID da instância que recebeu a mensagem.

contextInfoobject?

Contexto da mensagem (presente quando é resposta, menção ou mensagem efêmera).

stanzaId string?

ID da mensagem original (quando é resposta).

participant string?

JID do autor da mensagem original.

quotedMessage Message?

Conteúdo da mensagem citada (mesma estrutura de message).

mentionedJid string[]?

Lista de JIDs mencionados na mensagem.

expiration number?

Tempo de expiração em segundos (mensagens efêmeras).

{
  "event": "messages.upsert",
  "instance": "Atendimento01",
  "date_time": "2026-03-30T14:32:00Z",
  "data": {
    "key": {
      "remoteJid": "5511999999999@s.whatsapp.net",
      "fromMe": false,
      "id": "3EB04A2D1F75..."
    },
    "pushName": "Maria Silva",
    "status": "received",
    "message": {
      "conversation": "Olá! Gostaria de saber o status do meu pedido."
    },
    "messageType": "conversation",
    "messageTimestamp": 1743349920,
    "instanceId": "Atendimento01",
    "source": "android"
  }
}
EVENT

messages.edited

Disparado quando uma mensagem é editada. O campo key identifica a mensagem original e editedMessage traz o conteúdo novo.

Campos do payload (data)

key object

Chave da mensagem original (remoteJid, id, fromMe).

editedMessage object

Conteúdo novo da mensagem.

messageType string

Tipo da mensagem (ex: conversation).

pushName string

Nome de exibição de quem editou.

status "received" | "sent"

Se a edição foi recebida ou enviada pela instância.

messageTimestamp number

Timestamp da edição.

source string

Sempre "whatsapp".

instanceId string

ID da instância.

{
  "event": "messages.edited",
  "instance": "Atendimento01",
  "date_time": "2026-03-30T16:00:00Z",
  "data": {
    "key": {
      "remoteJid": "5511999999999@s.whatsapp.net",
      "id": "3EB04A2D1F75...",
      "fromMe": false
    },
    "editedMessage": {
      "conversation": "Texto editado"
    },
    "messageType": "conversation",
    "instanceId": "Atendimento01",
    "pushName": "Pedro Client",
    "status": "received",
    "messageTimestamp": 1708123456,
    "source": "whatsapp"
  }
}
EVENT

messages.update

Disparado quando o status de entrega de uma mensagem muda. Ocorre quando a mensagem é entregue no dispositivo do destinatário (DELIVERY_ACK) ou quando é lida (READ).

Campos do payload (data)

messageId string

ID interno da mensagem.

keyId string

ID da chave da mensagem.

remoteJid string

JID do chat.

fromMe boolean

Se a mensagem foi enviada por você.

participant string

JID do participante (em grupos).

status "DELIVERY_ACK" | "READ"

Novo status da mensagem.

instanceId string

ID da instância.

{
  "event": "messages.update",
  "instance": "Atendimento01",
  "date_time": "2026-03-30T14:33:00Z",
  "data": {
    "messageId": "3EB04A2D1F75...",
    "keyId": "3EB04A2D1F75...",
    "remoteJid": "5511999999999@s.whatsapp.net",
    "fromMe": true,
    "participant": "",
    "status": "DELIVERY_ACK",
    "instanceId": "Atendimento01"
  }
}
EVENT

messages.set

Disparado durante a sincronização do histórico completo ao conectar a instância. O WhatsApp envia lotes (batches) de mensagens antigas. Este evento é emitido para cada lote recebido. O payload é um array de mensagens no mesmo formato do messages.upsert.

Para receber este evento, é necessário habilitar a opção Sincronizar Histórico no momento da criação de uma nova instância (parâmetro syncFullHistory: true) e adicionar o evento messages.set na lista de eventos do webhook.

Campos extras do envelope

isLatest boolean

Indica se é o último lote da sincronização (true quando progress ≥ 100).

progress number

Percentual da sincronização (0–100). Útil para mostrar barra de progresso.

Campos do payload (data[])

Cada item do array segue o mesmo formato de mensagem do evento messages.upsert.

key object

Chave da mensagem (remoteJid, id, fromMe).

pushName string

Nome de exibição do remetente.

message object

Conteúdo da mensagem (mesmo formato do messages.upsert).

messageType string

Tipo da mensagem (conversation, imageMessage, etc).

messageTimestamp number

Timestamp Unix da mensagem original.

instanceId string

ID da instância.

{
  "event": "messages.set",
  "instance": "Atendimento01",
  "date_time": "2026-07-04T10:00:00Z",
  "isLatest": false,
  "progress": 45,
  "data": [
    {
      "key": {
        "remoteJid": "5511999999999@s.whatsapp.net",
        "id": "3EB04A2D1F75...",
        "fromMe": false
      },
      "pushName": "5511999999999",
      "message": {
        "conversation": "Olá, tudo bem?"
      },
      "messageType": "conversation",
      "messageTimestamp": 1719878400,
      "instanceId": "Atendimento01"
    }
  ]
}
EVENT

connection.update

Disparado quando o estado da conexão muda. Ocorre ao conectar com sucesso (escaneou QR Code), ao desconectar (logout, perda de sessão) ou em falhas de conexão.

Campos do payload (data)

instance string

ID da instância.

wuid string

WhatsApp UID (número conectado). Presente apenas quando state = "open".

profileName string

Nome do perfil do WhatsApp. Presente apenas quando state = "open".

profilePictureUrl string?

URL da foto de perfil (quando disponível).

state "open" | "close"

Estado atual da conexão.

statusReason number

Código do motivo (200 = sucesso, outros = erro).

{
  "event": "connection.update",
  "instance": "Atendimento01",
  "date_time": "2026-03-30T10:00:00Z",
  "data": {
    "instance": "Atendimento01",
    "wuid": "5511999998888@s.whatsapp.net",
    "profileName": "Meu Negócio",
    "profilePictureUrl": "https://pps.whatsapp.net/v/t61...",
    "state": "open",
    "statusReason": 200
  }
}
EVENT

contacts.upsert

Disparado quando um contato ou grupo é criado ou atualizado. Inclui mudanças de nome de exibição (push name), nome comercial, foto de perfil, informações de grupo e sincronização de histórico. O payload é um array de contatos.

Campos do payload (data[])

remoteJid string

JID do contato ou grupo.

remoteLid string

LID do contato (identificador alternativo).

pushName string

Nome de exibição do contato.

profilePicUrl string

URL da foto de perfil.

instanceId string

ID da instância.

Gatilhos: Mudança de push name, nome comercial (WhatsApp Business), foto de perfil, criação/atualização de grupo, sincronização de histórico de contatos.

{
  "event": "contacts.upsert",
  "instance": "Atendimento01",
  "date_time": "2026-03-30T15:00:00Z",
  "data": [
    {
      "remoteJid": "5511999999999@s.whatsapp.net",
      "remoteLid": "",
      "pushName": "Maria Silva",
      "profilePicUrl": "https://pps.whatsapp.net/v/t61...",
      "instanceId": "Atendimento01"
    }
  ]
}
EVENT

messages.delete

Disparado quando uma mensagem é apagada para todos (revoke). Ocorre quando o remetente apaga uma mensagem que já foi entregue — o WhatsApp envia um protocolo de revogação que dispara este evento.

Campos do payload (data)

id string

ID da mensagem apagada.

remoteJid string

JID do chat.

fromMe boolean

Se a mensagem apagada era sua.

participant string

JID do participante (em grupos).

status "DELETED"

Sempre "DELETED".

instanceId string

ID da instância.

{
  "event": "messages.delete",
  "instance": "Atendimento01",
  "date_time": "2026-03-30T16:00:00Z",
  "data": {
    "id": "3EB04A2D1F75...",
    "remoteJid": "5511999999999@s.whatsapp.net",
    "fromMe": false,
    "participant": "",
    "status": "DELETED",
    "instanceId": "Atendimento01"
  }
}
EVENT

group-participants.update

Disparado quando a composição de participantes de um grupo é alterada — adição, remoção, promoção ou rebaixamento de membros. O campo action indica qual tipo de alteração ocorreu.

Campos do payload (data)

id string

JID do grupo (ex: 120363429994246808@g.us).

author string

LID de quem executou a ação (ex: 158437669392517@lid).

action "add" | "remove" | "promote" | "demote"

Tipo da alteração ocorrida.

participants array

Lista de participantes afetados. Cada item contém:

id string

LID do participante.

phoneNumber string

Número do WhatsApp.

admin boolean | null

true se promovido a admin, false se rebaixado, null em add/remove.

participantsData array

Mesmos dados de participants em formato aninhado (compatibilidade Evolution API).

instanceId string

ID da instância.

{
  "event": "group-participants.update",
  "instance": "Atendimento01",
  "date_time": "2026-03-30T16:00:00Z",
  "data": {
    "id": "120363429994246808@g.us",
    "author": "158437669392517@lid",
    "participants": [
      {
        "id": "35026011992289@lid",
        "phoneNumber": "558599999999@s.whatsapp.net",
        "admin": false
      }
    ],
    "action": "promote",
    "participantsData": [
      {
        "jid": {
          "id": "35026011992289@lid",
          "phoneNumber": "558599999999@s.whatsapp.net",
          "admin": false
        }
      }
    ]
  },
  "sender": "558590909090@s.whatsapp.net"
}
EVENT

call

Somente Evolution

Disparado durante o ciclo de vida de uma ligação. Adicione call à lista de eventos do webhook para recebê-lo. Os status possíveis são offer, preaccept, accept, transport, relaylatency, reject e terminate.

Este é um evento de sinalização segura: não inclui conteúdo ou binários de áudio/vídeo, SDP, endpoints de relay, mídia criptografada nem chaves da chamada. Não há tradução nem entrega deste evento no formato Z-API.

Campos do payload (data)

callId string

ID usado nos endpoints de controle e áudio.

from string?

JID que originou o evento.

callCreator / callCreatorAlt string?

Identificadores do criador da ligação, quando disponíveis.

groupJid string?

JID do grupo em sinalizações de grupo.

status string

Transição do ciclo de vida da ligação.

media "audio" | "video" | ""

Tipo anunciado na oferta, quando conhecido.

isVideo / isGroup boolean?

Características da ligação.

remotePlatform / remoteVersion string?

Metadados do cliente remoto, quando informados.

reason string?

Motivo informado ao encerrar a ligação.

rtcMediaAvailable boolean

Permanece false; a mídia RTC bruta não é exposta no webhook.

{
  "event": "call",
  "instance": "Atendimento01",
  "date_time": "2026-08-15T12:00:00Z",
  "data": {
    "callId": "ABCD1234",
    "from": "5511999999999@s.whatsapp.net",
    "callCreator": "5511999999999@s.whatsapp.net",
    "status": "offer",
    "media": "audio",
    "isVideo": false,
    "isGroup": false,
    "rtcMediaAvailable": false
  }
}

© 2026 Whatsmiau Cloud API Reference.