> ## Documentation Index > Fetch the complete documentation index at: https://docs.ryzeapi.cloud/llms.txt > Use this file to discover all available pages before exploring further. # Catálogo de eventos > Schemas, enums e exemplos dos 6 tipos de evento entregues por webhook e WebSocket Webhook e WebSocket compartilham o **mesmo envelope** e o **mesmo catálogo** de eventos. A única diferença é o canal de entrega, o `data` é idêntico. Esta página documenta os 6 tipos: **`message.exchange`**, **`message.status`**, **`call.update`**, **`group.flow`**, **`instance.state`** e **`label.update`**. ## Envelope ```json theme={null} { "event": "", "data": { /* payload específico */ }, "instanceData": { "baseUrl": "https://api.example.com", "instance": "", "token": "" } } ``` Filtragem é feita pelo nome do `event` no campo `events` da config. Vazio = todos os tipos. ## Filtragem e roteamento ```json theme={null} { "events": ["message.exchange", "call.update", "instance.state"] } ``` Quando `byEvents=true` (apenas em webhook), o nome do evento é **anexado à URL**: * Config: `url: "https://app/wh"`, `byEvents: true` * Delivery: `POST https://app/wh/message.exchange` Útil para roteamento por endpoint sem precisar inspecionar o payload. *** ## `message.exchange` Mensagens enviadas e recebidas (texto, mídia, sticker, documento, áudio, enquete, contato, localização, etc.), edits e revogações. ### Payload ```json theme={null} { "id": "wamid.msg.123", "message": { "id": "wamid.msg.123", "direction": "incoming | outgoing", "timestamp": "2026-04-28T10:30:00Z", "chat": { "jid": "5511999999999", "lid": "100@s.whatsapp.net", "name": "João Silva", "type": "private | group | newsletter", "isCommunity": true }, "sender": { "jid": "5511999999999", "lid": "100@s.whatsapp.net", "name": "João Silva" }, "content": { "text": "Ola" }, "media": { "type": "image | video | audio | document | sticker | ptt | ptv", "url": "https://media-...whatsapp.net/...", "s3Url": "https://bucket.s3.amazonaws.com/...", "base64": "iVBORw0KGgo...", "mimetype": "image/jpeg", "size": 45678, "caption": "Foto do evento", "fileName": "doc.pdf" }, "edit": { "original_id": "wamid.original", "originalContent": "Texto antigo", "text": "Texto novo" }, "forward": { "count": 2 }, "reply": { "message_id": "wamid.replied", "sender": { "jid": "...", "name": "..." }, "text": "...", "media": { /* objeto media simplificado */ } }, "poll": { "title": "Qual sabor?", "options": [{ "name": "Chocolate", "count": 0 }] }, "location": { "latitude": -23.5505, "longitude": -46.6333, "address": "Av. Paulista, 1374" }, "contact": { "display_name": "Maria", "phone_number": "5511987654321", "vcard": "BEGIN:VCARD..." }, "list_response": { "title": "...", "body": "...", "list_type": "single_select", "single_select_reply": { "option_name": "p1" } }, "button_response": { "title": "Comprar", "body": "...", "selected_button_id": "buy_camiseta" }, "interactive": { /* form / native flow / outras superfícies */ } } } ``` ### Campos condicionais Apenas os campos relevantes para o tipo da mensagem são preenchidos. Edits têm `edit` populado; revogações chegam com `type: "message_revoke"` em `data.message.type`. `chat.isCommunity` aparece **apenas quando `true`**, indica que o chat é o canal de aviso (parent / announcement channel) de uma comunidade WhatsApp. Subgrupos vinculados a uma comunidade continuam com `type: "group"` e **sem** o campo `isCommunity`. Em grupos comuns e DMs o campo também é omitido. `media.base64` só aparece quando `mediaBase64=true` na config (webhook ou WebSocket). Caso contrário, use `media.url` (whatsapp.net, expira) ou `media.s3Url` (se S3 estiver configurado na instância). ### Exemplo (recebimento de imagem) ```json theme={null} { "event": "message.exchange", "data": { "id": "wamid.123", "message": { "id": "wamid.123", "direction": "incoming", "timestamp": "2026-04-28T10:30:00Z", "chat": { "jid": "5511999999999", "name": "João", "type": "private" }, "sender": { "jid": "5511999999999", "name": "João" }, "media": { "type": "image", "url": "https://media-abc.whatsapp.net/...", "mimetype": "image/jpeg", "size": 45678, "caption": "Foto" } } }, "instanceData": { "baseUrl": "https://api...", "instance": "minha", "token": "..." } } ``` *** ## `message.status` Recibos de entrega: delivered, read, played, etc. ### Payload ```json theme={null} { "status": "delivered | read | played | sender | read_self | played_self | retry | inactive | server_error", "messageIds": ["wamid.123", "wamid.124"], "timestamp": "2026-04-28T10:45:00Z", "chat": { "jid": "5511999999999", "type": "private | group | broadcast", "isCommunity": true }, "recipient": "5511999999999", "messageSender": null, "isFromMe": false } ``` ### Enum `status` | Valor | Significado | | -------------- | ------------------------------------------------------- | | `delivered` | Mensagem chegou no device do destinatário. | | `read` | Destinatário leu (read receipts ativos). | | `played` | Áudio/voice note foi reproduzido. | | `sender` | Eco interno (a própria origem reportando entrega). | | `read_self` | O **próprio usuário** marcou como lido em outro device. | | `played_self` | O próprio usuário reproduziu em outro device. | | `retry` | Servidor pediu reentrega (transient). | | `inactive` | Destinatário offline há tempo demais. | | `server_error` | Erro genérico do servidor WhatsApp. | * `messageSender` em **grupos**: JID do autor original da mensagem (relevante quando alguém leu uma mensagem de outro participante). * `chat.isCommunity` segue a mesma regra de `message.exchange`: presente e `true` apenas quando o chat é o canal de aviso de comunidade. *** ## `call.update` Eventos de chamada: oferta, aceite, recusa, encerramento, latência. ### Payload ```json theme={null} { "type": "offer | accepted | rejected | terminated | notification | latency", "direction": "incoming | outgoing", "callId": "call-abc123", "from": "5511999999999", "to": "5511888888888", "timestamp": "2026-04-28T10:35:00Z", "groupJid": null, "callMedia": "audio | video | null", "remotePlatform": "Android | iPhone | null", "remoteVersion": "2.23.15.74", "noticeType": "group | null", "reason": null, "duration": 123, "latency": 45.6, "latencyStatus": "Excellent | Good | Average | Poor" } ``` ### Enum `type` | Valor | Quando dispara | | -------------- | ------------------------------------------------------------------------- | | `offer` | Chamada recebida/enviada (toque inicial). | | `accepted` | Lado remoto atendeu. | | `rejected` | Lado remoto rejeitou. | | `terminated` | Chamada encerrada, `duration` em segundos vem populado. | | `notification` | Notificação contextual de chamada (ex.: chamada perdida em grupo). | | `latency` | Métrica de latência durante a chamada (`latency` em ms, `latencyStatus`). | Para rejeitar chamadas automaticamente, configure `autoRejectCalls=true` no [bloco settings da instância](/pt/api/instance/settings-update), você ainda recebe os eventos `offer` + `rejected` no webhook. *** ## `group.flow` Mudanças em grupos: membros, metadata, settings. ### Payload, participant change ```json theme={null} { "type": "joined | left | promoted | demoted", "groupJid": "120363406289005073@g.us", "groupName": "Time de Dev", "timestamp": "2026-04-28T11:00:00Z", "participants": [ { "jid": "5511999999999", "action": "joined" } ] } ``` ### Subtipos de metadata | `type` | Significado | | ----------------------------- | --------------------------------------------- | | `name` | Nome do grupo alterado | | `topic` | Descrição alterada | | `locked` / `unlocked` | Members can/cannot edit info | | `announce` / `not_announce` | Members can/cannot send messages | | `ephemeral` / `not_ephemeral` | Mensagens efêmeras on/off | | `invite` | Invite link gerado | | `link` / `unlink` | Subgrupo vinculado/desvinculado de comunidade | | `delete` | Grupo deletado | | `membership_approval` | Modo de aprovação de novos membros alterado | | `suspended` / `unsuspended` | Grupo suspenso/reativado pelo WhatsApp | *** ## `instance.state` Mudanças no estado da própria instância (conexão, QR, ban, pareamento). ### Payload ```json theme={null} { "instance": "minha", "state": "connected | disconnected | logged_out | stream_replaced | temp_banned | client_outdated | connect_failure | stream_error | cat_refresh_error | qr_ready | pair_success | pair_error | qr_scanned_no_multidevice | keepalive_timeout | keepalive_restored | manual_reconnect", "timestamp": "2026-04-28T10:50:00Z", "reason": "...", "reasonCode": 123, "message": "...", "expireAt": "2026-04-28T11:50:00Z", "expireInSeconds": 3600, "onConnect": true, "codes": ["1@abc...,xyz==,base64string"], "jid": "5511999999999@s.whatsapp.net", "platform": "iPhone | Android | Desktop", "errorMsg": "..." } ``` ### Enum `state` | State | Significado | Campos extras populados | | --------------------------- | ---------------------------------------------------------------------------- | --------------------------------------- | | `connected` | Sessão ativa, pronta para enviar/receber. | , | | `disconnected` | Desconectado (transient, geralmente reconecta sozinho). | , | | `logged_out` | Sessão invalidada (precisa novo `connect`). | `reason` | | `stream_replaced` | Outra sessão tomou o lugar (multi-device conflict). | , | | `temp_banned` | Ban temporário aplicado pelo WhatsApp. | `expireAt`, `expireInSeconds`, `reason` | | `client_outdated` | Versão do WhatsApp Web em uso está obsoleta, entre em contato com o suporte. | `message` | | `connect_failure` | Falha durante conexão. | `reason`, `reasonCode` | | `stream_error` | Erro de stream do WhatsApp. | `errorMsg` | | `cat_refresh_error` | Falha ao renovar credenciais (`cat`). | `errorMsg` | | `qr_ready` | Novo QR disponível para pareamento. | `codes[]`, `onConnect` | | `pair_success` | Pareamento concluído. | `jid`, `platform` | | `pair_error` | Erro durante o pareamento. | `errorMsg` | | `qr_scanned_no_multidevice` | QR escaneado mas o device-alvo não tem multidevice. | , | | `keepalive_timeout` | Conexão instável, keepalive não respondido. | , | | `keepalive_restored` | Conexão estabilizou após `keepalive_timeout`. | , | | `manual_reconnect` | Reconexão disparada manualmente via REST. | , | Para o seu cliente saber quando recarregar o QR na UI, escute `instance.state` com `state=qr_ready` e renderize `data.codes[0]`. *** ## `label.update` Edição/associação de etiquetas (WhatsApp Business labels). ### Payload ```json theme={null} { "type": "edit | chat | message", "labelId": "1", "timestamp": "2026-04-28T10:00:00Z", "action": "updated | deleted | add | remove", // type=edit: "name": "Important", "color": 0, "labelType": "CUSTOM", "isActive": true, "isImmutable": false, "orderIndex": 1, "deleted": false, // type=chat: "chatJid": "5511999999999@s.whatsapp.net", "labeled": true, // type=message: "messageId": "wamid.abc" } ``` ### Combinações `type` × `action` | `type` | `action` válida | Campos extras | | --------- | -------------------- | -------------------------------------------------------------------------------- | | `edit` | `updated`, `deleted` | `name`, `color`, `labelType`, `isActive`, `isImmutable`, `orderIndex`, `deleted` | | `chat` | `add`, `remove` | `chatJid`, `labeled` | | `message` | `add`, `remove` | `chatJid`, `messageId` | *** ## Eventos não emitidos (internos) Capturados pelo handler `whatsmeow` mas **não** propagados via webhook/WS: * `*events.Picture`, mudança de foto de perfil (apenas logado). * `*events.FBMessage`, Facebook Business (apenas logado). * `*events.HistorySync`, sync de histórico (processado e gravado em DB). Se você precisar consumir alguma dessas mudanças, faça polling pelos endpoints REST correspondentes (perfil, histórico). ## Referências Filtre os eventos via `events[]` na config. Mesma sintaxe de filtro do webhook. Receba os eventos em tempo real. Comparação webhook x WebSocket.