Skip to main content
WhatsApp organizes chats with labels, which in recent versions of the app appear as Lists. These webhooks notify you when a label is created, edited or deleted, and when it is applied to or removed from a chat or a message. All of them follow the common envelope — the specific content is in data.
Webhooks deliver changes. When it connects, the session syncs all of the account’s labels and associations, but that sync does not produce webhooks (it would be the same state resent on every reconnection). For the full state, use GET /labels/list and GET /labels/contact-labels.

labels.edit

string
required
Label identifier.
string
Label name.
number
Label color code.
boolean
true when the label was deleted.
string
List type. custom for lists created by the user; WhatsApp’s own lists come as unread (Unread), favorites (Favorites), groups (Groups), predefined (suggested by the app, such as “New order”), among others. Older labels may come as none.
number
Identifier of the list suggested by WhatsApp, when list_type is predefined. 0 otherwise.
number
Position of the list in the app.
boolean
Whether the list is active in the app.
boolean
true for system lists, which the user cannot rename or delete.
number
Time of the event in milliseconds (epoch).

labels.association.chat

string
required
Label identifier.
string | null
Label name. null if it has not been synced yet.
number | null
Label color. null if it has not been synced yet.
string
required
JID of the chat (...@s.whatsapp.net or ...@g.us). When the contact’s number is not known to the session, it comes as a LID (...@lid).
boolean
required
true applies the label to the chat; false removes it.

labels.association.message

Same fields as labels.association.chat, plus the message identifier.
string
required
Message identifier.