better_messages_unread_counter

info

Display the unread messages counter badge anywhere on your WordPress site — header, menu item, custom dashboard widget, or sidebar. Updates in real-time (instantly on the WebSocket version, on poll on the free version). The badge respects the global unread counter mode (per-message vs per-conversation).

When to use it#

Location	Why a counter badge
Site header / menu	Most common — let users see "Messages (3)" at a glance
Member dashboard	Compact summary of pending communications
Mobile floating button	Pair with the floating chat button for an icon + count
User profile dropdown	Personal-area "you have N unread messages" indicator
Sticky sidebar	Persistent visibility on long content pages

Attributes#

Attribute	What it does	Default
`hide_when_no_messages`	If `1`, the counter is hidden when there are zero unread messages	`0` (always show)
`preserve_space`	If `1` AND counter is hidden, the space is reserved invisibly — smoother animation when a new message arrives	`0`

Usage#

Always-visible counter#

[better_messages_unread_counter]

Renders the counter regardless of unread state. Shows "0" when nothing is unread.

Hide when zero#

[better_messages_unread_counter hide_when_no_messages="1"]

Counter only appears when there are unread messages — cleaner UX for most sites.

Hide with reserved space#

[better_messages_unread_counter hide_when_no_messages="1" preserve_space="1"]

Best for menus: counter is invisible when zero but reserves the space, so new-message animations don't push other menu items around.

The recommended pattern for adding the counter to your WordPress menu:

Install the Shortcode in Menus plugin
Appearance → Menus → Add a Custom Link
URL: [better_messages_my_messages_url] (links to the inbox)
Label: Messages [better_messages_unread_counter hide_when_no_messages="1" preserve_space="1"]

The result: a "Messages" menu item with a counter badge that appears when there are unread messages.

Frequently asked questions#

Does the counter update in real-time?#

On the WebSocket version, yes — instantly as new messages arrive. On the free version, the counter updates every few seconds (matching the polling interval).

What does the counter count — messages or conversations?#

Whichever you've configured in Settings → Messaging → Unread Counter. See Unread filter for the counter mode options.

Can I style the badge?#

Yes — the counter renders with stable class names (.better-messages-unread-counter). Override via your theme's Additional CSS.

Does the counter appear for non-logged-in users?#

No — guests don't have a personal inbox, so the counter renders empty. For guest sites with guest chat, the counter reflects unread messages in their guest sessions.

How can I hook into the counter value (for custom UI)?#

Listen for the bp-better-messages-update-unread CustomEvent on document. The new count is in event.detail.unread:

document.addEventListener('bp-better-messages-update-unread', (e) => {
    console.log('Unread count:', e.detail.unread);
});