Skip to main content
These events keep your system in sync with the state of chats, contact data and presence (online, last seen). All of them follow the common envelope — the specific content is in data.

chats.update and chats.upsert

chats.upsert indicates a chat created or received during sync; chats.update indicates an update to an existing chat. Both events have the same data format.
string
required
JID of the chat (contact or group).
string
Chat name (contact or group name).
number
Number of unread messages.
number
Time of the conversation’s last activity in seconds (epoch).
boolean
true when the chat is archived.
number
Indicates whether the chat is pinned (0 when it is not).
number
Time (epoch) when the mute ends; 0 when the chat is not muted.
chats.upsert events go through a 2-second debounce per chat: multiple consecutive updates to the same chat are grouped together.

contacts.update and contacts.upsert

contacts.upsert indicates a contact created or received during sync; contacts.update indicates an update to an existing contact. Both events have the same data format.
string
required
JID of the contact.
string
Display name set by the contact themselves on WhatsApp.
string
Full name of the contact (when saved in the address book).
string
First name of the contact.
string
Business name, when the contact is a business account. Empty string ("") when not applicable.
contacts.upsert events go through a 2-second debounce per contact: multiple consecutive updates to the same contact are grouped together.

presence

Fired when a contact’s presence changes (online/offline, last seen).
string
required
JID of the contact whose presence changed.
string
Contact name.
boolean
true when the contact is offline/unavailable; false when they are online.
number
Time of last access in seconds (epoch), when available.
The presence event goes through a 5-second deduplication per contact and state (online/offline): identical changes within that window do not produce duplicate webhooks.