Eventos de Webhook

O WaGo envia eventos de webhook quando a sessão do WhatsApp conectada recebe mensagens, confirmações de leitura, atualizações de presença, atualizações de chamadas, eventos de logout e outras alterações na conta.

Formato de entrega

O WaGo envia webhooks como requisições POST usando form data, não um corpo de requisição JSON bruto. Todo webhook normal contém:

Campo do formulário	Significado
`token`	O token de sessão do WaGo que gerou o evento. Use-o para mapear o evento para um de seus usuários ou dispositivos.
`jsonData`	Uma string JSON. Analise (parse) este campo para obter o payload do evento.

Quando o encaminhamento de arquivos de mídia está habilitado e o WaGo baixa um arquivo de mídia recebido, o webhook é enviado como multipart form data com os mesmos campos, além de:

Campo do formulário	Significado
`file`	O arquivo de imagem, áudio, vídeo, documento ou figurinha baixado.

Exemplo de receptor:

app.post("/wago/webhook", upload.single("file"), (req, res) => {
  const token = req.body.token;
  const event = JSON.parse(req.body.jsonData);
  const file = req.file;

  res.sendStatus(200);
});

Envelope do evento

A maioria dos valores de jsonData segue este formato:

{
  "type": "Message",
  "event": {}
}

type é o nome da assinatura/evento do WaGo. event é o objeto de evento subjacente do WhatsApp, com campos como Info, Message, MessageIDs, Timestamp, From, State ou metadados de chamada, dependendo do tipo de evento. Alguns tipos de evento incluem campos extras do WaGo ao lado de event:

Campo	Adicionado para	Significado
`state`	`ReadReceipt`, `Presence`	Status normalizado como `Delivered`, `Read`, `ReadSelf`, `online` ou `offline`.
`decryptVote`	Atualizações de enquete em `Message`	Hash hexadecimal para uma opção de enquete selecionada e descriptografada.
`orderDetails`	Mensagens de pedido em `Message`	Dados do pedido obtidos do WhatsApp quando uma mensagem de pedido contém `orderID` e `token`.

Valores de assinatura

As assinaturas são definidas em POST /session/connect ou POST /session/pair.

{
  "Subscribe": ["Message", "ReadReceipt", "Presence", "ChatPresence", "Call", "LoggedOut"],
  "Immediate": true,
  "Phone": ""
}

Nomes de assinatura públicos suportados:

Valor de assinatura	Eventos incluídos
`All`	Envia todos os tipos de eventos de webhook públicos.
`Message`	Eventos de mensagens recebidas e enviadas de chats.
`Newsletter`	Eventos de mensagens cuja origem é uma newsletter/canal.
`ReadReceipt`	Confirmações de entrega/leitura de mensagens.
`Presence`	Atualizações de online/offline para usuários.
`ChatPresence`	Indicadores de digitação e gravação dentro de um chat.
`HistorySync`	Payloads de sincronização histórica do WhatsApp após login ou reconexão.
`Call`	Oferta de chamada, aceite, encerramento, latência de relay e eventos de estado de chamada gerenciada pelo WaGo.
`LoggedOut`	A sessão foi desconectada ou desvinculada.

Use All durante a integração. Em produção, assine apenas os tipos de evento que sua aplicação precisa.

Evento de mensagem

Use eventos Message para processar mensagens de chat recebidas, mensagens enviadas de dispositivos vinculados, mensagens de mídia, atualizações de enquetes, mensagens de pedido, edições e mensagens de newsletter. Exemplo de mensagem de texto:

{
  "type": "Message",
  "event": {
    "Info": {
      "Chat": "[email protected]",
      "Sender": "[email protected]",
      "IsFromMe": false,
      "IsGroup": false,
      "ID": "3EB0F7A1B2C3D4E5",
      "PushName": "Customer",
      "Timestamp": "2026-06-25T10:30:00Z",
      "Type": "text"
    },
    "Message": {
      "conversation": "Hello"
    },
    "IsEphemeral": false,
    "IsViewOnce": false,
    "IsEdit": false
  }
}

Campos importantes:

Campo	Significado
`event.Info.ID`	ID da mensagem do WhatsApp. Armazene isso para respostas, reações, edições, exclusões, confirmações ou logs de auditoria.
`event.Info.Chat`	JID do chat ao qual a mensagem pertence.
`event.Info.Sender`	JID do remetente. Em grupos, este é o participante que a enviou.
`event.Info.IsFromMe`	`true` quando a mensagem foi enviada pela conta conectada ou outro dispositivo vinculado.
`event.Info.IsGroup`	`true` para contextos de grupo ou transmissão.
`event.Message`	O payload real da mensagem do WhatsApp. O campo interno depende do tipo de mensagem.

Ramificações comuns de event.Message:

Campo da mensagem	Significado
`conversation`	Mensagem de texto simples.
`extendedTextMessage`	Texto com contexto, pré-visualização, citação ou dados de formatação.
`imageMessage`	Metadados da imagem e legenda.
`audioMessage`	Metadados do áudio.
`videoMessage`	Metadados do vídeo e legenda.
`documentMessage`	Metadados do documento, nome do arquivo e legenda.
`stickerMessage`	Metadados da figurinha.
`locationMessage`	Mensagem de latitude/longitude.
`contactMessage`	Mensagem de contato vCard.
`pollUpdateMessage`	Atualização de voto em enquete. O WaGo tenta descriptografar o voto e adiciona `decryptVote`.
`orderMessage`	Mensagem de pedido comercial. O WaGo tenta buscar `orderDetails`.

Mensagem de mídia com upload de arquivo

Se o binário for executado com o encaminhamento de arquivos de webhook habilitado, o WaGo baixa a mídia recebida suportada e envia o arquivo com a requisição do webhook. Exemplo de jsonData para mídia de imagem:

{
  "type": "Message",
  "event": {
    "Info": {
      "Chat": "[email protected]",
      "Sender": "[email protected]",
      "ID": "3EB0IMAGE",
      "Timestamp": "2026-06-25T10:31:00Z",
      "MediaType": "image"
    },
    "Message": {
      "imageMessage": {
        "caption": "Payment proof",
        "mimetype": "image/jpeg",
        "fileLength": 54231
      }
    }
  }
}

A requisição HTTP também inclui file. Salve-o em sua aplicação antes de responder. Tipos de arquivo com encaminhamento automático suportados no WaGo:

Mensagem do WhatsApp	Comportamento do arquivo
Imagem	Baixado e anexado como `file`.
Áudio	Baixado e anexado como `file`.
Documento	Baixado e anexado como `file`.
Vídeo	Baixado e anexado como `file`.
Figurinha	Baixado e anexado como `file`.

Se o encaminhamento de arquivos estiver desabilitado, use os metadados da mensagem e os endpoints de download de mídia para buscar a mídia posteriormente.

Evento de confirmação de leitura

Use eventos ReadReceipt para atualizar o estado de entrega da mensagem em sua aplicação.

{
  "type": "ReadReceipt",
  "state": "Delivered",
  "event": {
    "Chat": "[email protected]",
    "Sender": "[email protected]",
    "IsFromMe": true,
    "MessageIDs": ["3EB0F7A1B2C3D4E5"],
    "Timestamp": "2026-06-25T10:32:00Z",
    "Type": "delivered",
    "MessageSender": "[email protected]"
  }
}

Valores de state adicionados pelo WaGo:

Estado	Significado
`Delivered`	O WhatsApp entregou a mensagem.
`Read`	O destinatário leu a mensagem.
`ReadSelf`	Outro dispositivo vinculado à mesma conta leu a mensagem.

Evento de presença

Use eventos Presence para o estado online/offline do usuário.

{
  "type": "Presence",
  "state": "online",
  "event": {
    "From": "[email protected]",
    "Unavailable": false,
    "LastSeen": "0001-01-01T00:00:00Z"
  }
}

Quando o state é offline, LastSeen pode ser zero se o contato ocultar o visto por último.

Evento de presença no chat

Use ChatPresence para indicadores de digitação e gravação.

{
  "type": "ChatPresence",
  "event": {
    "Chat": "[email protected]",
    "Sender": "[email protected]",
    "IsFromMe": false,
    "IsGroup": false,
    "State": "composing",
    "Media": "text"
  }
}

Valores comuns:

Campo	Valores
`State`	`composing`, `paused`
`Media`	`text`, `audio`

Evento de chamada

O WaGo envia dois tipos de webhooks relacionados a chamadas:

Eventos brutos de chamada do WhatsApp, como oferta, aceite, encerramento, aviso de oferta e latência de relay.
Eventos de chamada gerenciada da camada de chamadas do WaGo, como incoming, state, ready e ended.

Exemplo de oferta de chamada bruta:

{
  "type": "Call",
  "event": {
    "From": "[email protected]",
    "Timestamp": "2026-06-25T10:33:00Z",
    "CallCreator": "[email protected]",
    "CallID": "CALL_ID",
    "RemotePlatform": "android",
    "RemoteVersion": "2.26.1"
  }
}

Exemplo de chamada recebida gerenciada:

{
  "type": "Call",
  "event": {
    "action": "incoming",
    "callID": "CALL_ID",
    "peer": "[email protected]",
    "phase": "ringing",
    "phaseCode": 2
  }
}

Exemplo de estado de chamada gerenciada:

{
  "type": "Call",
  "event": {
    "action": "state",
    "callID": "CALL_ID",
    "peer": "[email protected]",
    "phase": "active",
    "phaseCode": 4
  }
}

Use callID com os endpoints /call/answer, /call/reject, /call/hangup, /call/status e de áudio ao vivo.

Evento de logout

Use LoggedOut para detectar que a sessão do WhatsApp não está mais vinculada.

{
  "type": "LoggedOut",
  "event": {
    "Reason": 401
  }
}

Quando o WaGo recebe este evento, ele marca a sessão como desconectada. Sua aplicação deve exibir ao usuário um fluxo de reconexão ou leitura de QR code.

Evento de sincronização de histórico

HistorySync chega quando o WhatsApp envia mensagens históricas após login ou reconexão.

{
  "type": "HistorySync",
  "event": {
    "Data": {
      "syncType": "INITIAL_BOOTSTRAP"
    }
  }
}

Payloads de sincronização de histórico podem ser grandes. Se sua aplicação não precisa de importação histórica, não assine HistorySync.

Eventos de conta e estado do aplicativo

O WaGo também encaminha vários tipos de eventos de estado da conta. Eles são úteis para dashboards e tarefas de sincronização, mas a maioria das aplicações pode ignorá-los, a menos que precisem de detalhes de administração da conta.

Tipo	O que significa
`SyncComplete`	Sincronização offline concluída após reconexão.
`LabelEdit`	Um rótulo do WhatsApp foi editado.
`LabelAssociationChat`	Um rótulo foi aplicado ou removido de um chat.
`LabelAssociationMessage`	Um rótulo foi aplicado ou removido de uma mensagem.
`ClientOutdated`	O WhatsApp informa que esta versão do cliente está desatualizada.
`TemporaryBan`	A conta recebeu um evento de banimento temporário.
`TemporaryBanReason`	Detalhes do motivo de um banimento temporário.
`JoinedGroup`	A conta entrou ou foi adicionada a um grupo.
`Blocklist`	Contatos bloqueados alterados.
`PrivacySettings`	Configurações de privacidade alteradas.
`ClearChat`	Um chat foi limpo.
`Contact`	Estado do contato alterado.
`MarkChatAsRead`	O estado de lido/não lido de um chat foi alterado.
`UserAbout`	O texto de recado (about) de um usuário foi alterado.

Regras do receptor

Seu endpoint de webhook deve:

Responder com 2xx rapidamente.
Analisar jsonData após ler os dados do formulário.
Armazenar token, type, IDs de mensagem e timestamps.
Desduplicar por event.Info.ID para mensagens ou por type + message ID + timestamp para confirmações.
Salvar o file enviado antes de retornar.
Lidar com campos que você não reconhece. Objetos de evento do WhatsApp podem ganhar novos campos.
Evitar processamento lento dentro da requisição. Coloque tarefas de acompanhamento em uma fila após armazenar o evento.

​Formato de entrega

​Envelope do evento

​Valores de assinatura

​Evento de mensagem

​Mensagem de mídia com upload de arquivo

​Evento de confirmação de leitura

​Evento de presença

​Evento de presença no chat

​Evento de chamada

​Evento de logout

​Evento de sincronização de histórico

​Eventos de conta e estado do aplicativo

​Regras do receptor