Webhook events - WaGo API

WaGo sends webhook events when the connected WhatsApp session receives messages, receipts, presence updates, call updates, logout events, and other account changes.

Delivery format

WaGo sends webhooks as POST requests using form data, not a raw JSON request body. Every normal webhook contains:

Form field	Meaning
`token`	The WaGo session token that produced the event. Use it to map the event to one of your users or devices.
`jsonData`	A JSON string. Parse this field to get the event payload.

When media file forwarding is enabled and WaGo downloads an inbound media file, the webhook is sent as multipart form data with the same fields plus:

Form field	Meaning
`file`	The downloaded image, audio, video, document, or sticker file.

Receiver example:

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);
});

Event envelope

Most jsonData values follow this shape:

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

type is the WaGo subscription/event name. event is the underlying WhatsApp event object, with fields such as Info, Message, MessageIDs, Timestamp, From, State, or call metadata depending on event type. Some event types include extra WaGo fields next to event:

Field	Added for	Meaning
`state`	`ReadReceipt`, `Presence`	Normalized status such as `Delivered`, `Read`, `ReadSelf`, `online`, or `offline`.
`decryptVote`	`Message` poll updates	Hex hash for a decrypted selected poll option.
`orderDetails`	`Message` order messages	Order data fetched from WhatsApp when an order message contains `orderID` and `token`.

Subscriptions are set in POST /session/connect or POST /session/pair.

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

Supported public subscription names:

Subscribe value	Events included
`All`	Sends all public webhook event types.
`Message`	Inbound and outbound message events from chats.
`Newsletter`	Message events whose source is a newsletter/channel.
`ReadReceipt`	Delivered/read receipts for messages.
`Presence`	Online/offline updates for users.
`ChatPresence`	Typing and recording indicators inside a chat.
`HistorySync`	Historical sync payloads from WhatsApp after login or reconnect.
`Call`	Call offer, accept, terminate, relay latency, and WaGo managed-call state events.
`LoggedOut`	Session was logged out or unpaired.

Use All while integrating. In production, subscribe only to the event types your app needs.

Message event

Use Message events to process inbound chat messages, outgoing messages from linked devices, media messages, poll updates, order messages, edits, and newsletter messages. Example text message:

{
  "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
  }
}

Important fields:

Field	Meaning
`event.Info.ID`	WhatsApp message ID. Store this for replies, reactions, edits, deletes, receipts, or audit logs.
`event.Info.Chat`	Chat JID where the message belongs.
`event.Info.Sender`	Sender JID. In groups this is the participant who sent it.
`event.Info.IsFromMe`	`true` when the message was sent by the connected account or another linked device.
`event.Info.IsGroup`	`true` for group or broadcast contexts.
`event.Message`	The actual WhatsApp message payload. The inner field depends on message type.

Common event.Message branches:

Message field	Meaning
`conversation`	Simple text message.
`extendedTextMessage`	Text with context, preview, quote, or formatting data.
`imageMessage`	Image metadata and caption.
`audioMessage`	Audio metadata.
`videoMessage`	Video metadata and caption.
`documentMessage`	Document metadata, file name, and caption.
`stickerMessage`	Sticker metadata.
`locationMessage`	Latitude/longitude message.
`contactMessage`	vCard contact message.
`pollUpdateMessage`	Poll vote update. WaGo tries to decrypt the vote and adds `decryptVote`.
`orderMessage`	Business order message. WaGo tries to fetch `orderDetails`.

Media message with file upload

If the binary runs with webhook file forwarding enabled, WaGo downloads supported inbound media and sends the file with the webhook request. Example jsonData for image media:

{
  "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
      }
    }
  }
}

The HTTP request also includes file. Save it in your app before responding. Supported auto-forwarded file types in WaGo:

WhatsApp message	File behavior
Image	Downloaded and attached as `file`.
Audio	Downloaded and attached as `file`.
Document	Downloaded and attached as `file`.
Video	Downloaded and attached as `file`.
Sticker	Downloaded and attached as `file`.

If file forwarding is disabled, use the message metadata and media download endpoints to fetch media later.

Read receipt event

Use ReadReceipt events to update message delivery state in your app.

{
  "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]"
  }
}

state values added by WaGo:

State	Meaning
`Delivered`	WhatsApp delivered the message.
`Read`	Recipient read the message.
`ReadSelf`	Another linked device for the same account read the message.

Presence event

Use Presence events for online/offline user state.

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

When state is offline, LastSeen may be zero if the contact hides last seen.

Chat presence event

Use ChatPresence for typing and recording indicators.

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

Common values:

Field	Values
`State`	`composing`, `paused`
`Media`	`text`, `audio`

Call event

WaGo sends two kinds of call-related webhooks:

Raw WhatsApp call events such as offer, accept, terminate, offer notice, and relay latency.
Managed-call events from the WaGo call layer, such as incoming, state, ready, and ended.

Raw call offer example:

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

Managed incoming call example:

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

Managed call state example:

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

Use callID with /call/answer, /call/reject, /call/hangup, /call/status, and live audio endpoints.

Logged out event

Use LoggedOut to detect that the WhatsApp session is no longer linked.

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

When WaGo receives this event, it marks the session disconnected. Your app should show the user a reconnect or scan flow.

History sync event

HistorySync arrives when WhatsApp sends historical messages after login or reconnect.

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

History sync payloads can be large. If your app does not need historical import, do not subscribe to HistorySync.

Account and app-state events

WaGo also forwards several account-state event types. These are useful for dashboards and sync jobs, but most apps can ignore them unless they need account administration details.

Type	What it means
`SyncComplete`	Offline sync finished after reconnect.
`LabelEdit`	A WhatsApp label was edited.
`LabelAssociationChat`	A label was applied to or removed from a chat.
`LabelAssociationMessage`	A label was applied to or removed from a message.
`ClientOutdated`	WhatsApp says this client version is outdated.
`TemporaryBan`	Account received a temporary ban event.
`TemporaryBanReason`	Reason details for a temporary ban.
`JoinedGroup`	The account joined or was added to a group.
`Blocklist`	Blocked contacts changed.
`PrivacySettings`	Privacy settings changed.
`ClearChat`	A chat was cleared.
`Contact`	Contact state changed.
`MarkChatAsRead`	A chat read/unread state changed.
`UserAbout`	A user’s about text changed.

Receiver rules

Your webhook endpoint should:

Respond with 2xx quickly.
Parse jsonData after reading form data.
Store token, type, message IDs, and timestamps.
Deduplicate by event.Info.ID for messages or by type + message ID + timestamp for receipts.
Save uploaded file before returning.
Handle fields you do not recognize. WhatsApp event objects can gain new fields.
Avoid slow work inside the request. Queue follow-up jobs after storing the event.

​Delivery format

​Event envelope

​Subscribe values

​Message event

​Media message with file upload

​Read receipt event

​Presence event

​Chat presence event

​Call event

​Logged out event

​History sync event

​Account and app-state events

​Receiver rules