Custom navigation tabs from code
The messenger has three navigation bars: the mini widgets bar (mini), the side panel
beside the conversations list, with its collapsed rail (side), and the tab bar on phones
(mobile). An admin adds tabs of their own and renames the built-in ones at Settings →
Appearance, as Custom tabs describes. This guide is for doing the
same, and more, from code.
There are two places to do it:
| Where | Filter | Use it to |
|---|---|---|
| In the browser | better_messages_navigation_tabs | Change any tab of any bar, the built-in ones included. Add a tab that draws its own panel, runs a click or carries a badge |
| On the server | better_messages_custom_tabs | Add a tab only for the members who should have it, by what the site knows about them: a membership, a capability, an enrolment |
Both are available since Better Messages 3.1.5.
The JavaScript filter#
The filter runs once for each bar and receives that bar's tabs in order:
wp.hooks.addFilter('better_messages_navigation_tabs', 'my_plugin', function(tabs, surface) {
// tabs: [{ key: 'messages', label: 'Messages', builtIn: true, type: 'builtin', ... }, ...]
// surface: 'mini', 'side' or 'mobile'
return tabs;
});
Load your script after wp-hooks, as for any Better Messages JavaScript hook.
A filter added after the messenger has drawn is picked up at once, so the order of loading does not
matter beyond that.
The built-in tabs have the keys messages, friends, groups, courses, ai-bots, chat-rooms
and users, each present only when it is on for the bar and the member can see it. The admin's
custom tabs have keys starting with ct_. The reference
lists every property of a tab.
Rename, re-icon, reorder or remove a tab#
Return the tabs changed. A built-in tab keeps what it shows, whatever its label or icon:
wp.hooks.addFilter('better_messages_navigation_tabs', 'my_plugin', function(tabs, surface) {
var renamed = tabs.map(function(tab) {
if (tab.key === 'messages') return Object.assign({}, tab, { label: 'Inbox', icon: 'mail' });
if (tab.key === 'chat-rooms') return Object.assign({}, tab, { label: 'Lounges' });
return tab;
});
// Chat rooms first on the phone, Users nowhere on it.
if (surface === 'mobile') {
renamed = renamed.filter(function(tab) { return tab.key !== 'users'; });
renamed.sort(function(a, b) { return (b.key === 'chat-rooms') - (a.key === 'chat-rooms'); });
}
return renamed;
});
The first tab of a bar is the one the messenger opens on, so moving a tab first in the filter also decides that, as dragging it first in the admin does.
Add a link, or a page shown inside the messenger#
wp.hooks.addFilter('better_messages_navigation_tabs', 'my_plugin', function(tabs, surface) {
tabs.push({
key: 'help',
label: 'Help',
icon: 'star',
type: 'link',
url: '/help/',
newWindow: true
});
tabs.push({
key: 'events',
label: 'Events',
icon: 'home',
type: 'page',
url: '/events/'
});
return tabs;
});
A page tab shows the address in a frame inside the messenger. A page of your own site opens its
links in the whole window. A page of another site shows only if that site allows being framed.
Add a tab with a panel of your own#
Give the tab a render function. It is called with an empty element the first time the tab is
opened, and the element stays on screen, hidden while another tab is in front, until the messenger
goes. Return a function to clean up after yourself:
wp.hooks.addFilter('better_messages_navigation_tabs', 'my_plugin', function(tabs, surface) {
tabs.push({
key: 'my-leaderboard',
label: 'Leaderboard',
icon: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M8 21V11M16 21V7M12 21V3"/></svg>',
type: 'custom',
render: function(container, context) {
container.innerHTML = '<div class="my-leaderboard">Loading…</div>';
var load = function() {
fetch('/wp-json/my-plugin/v1/leaderboard', { credentials: 'same-origin' })
.then(function(response) { return response.json(); })
.then(function(rows) {
container.innerHTML = '<ol class="my-leaderboard">' + rows.map(function(row) {
return '<li>' + row.name + ' <b>' + row.points + '</b></li>';
}).join('') + '</ol>';
});
};
load();
var timer = setInterval(load, 60000);
return function() { clearInterval(timer); };
}
});
return tabs;
});
The container scrolls by itself when what you draw is taller than the panel. Plain DOM is enough, the messenger does not need to know how you draw. Style your panel with your own classes. The messenger's colours are available as CSS variables, see the CSS reference.
A tab with an onClick and no render never comes to the front, it only runs the click. Use it for
a tab that opens something of yours, a modal say:
tabs.push({
key: 'new-ticket',
label: 'New ticket',
icon: 'edit',
type: 'custom',
onClick: function(event, context) { openMyTicketForm(); }
});
Keep a badge current#
A tab shows badge over its icon: a number (zero shows nothing) or a short text. Return the
current value from the filter, and ask the bars to run it again when it changes:
var openTickets = 0;
wp.hooks.addFilter('better_messages_navigation_tabs', 'my_plugin', function(tabs) {
return tabs.map(function(tab) {
return tab.key === 'new-ticket' ? Object.assign({}, tab, { badge: openTickets }) : tab;
});
});
document.addEventListener('my-tickets-changed', function(event) {
openTickets = event.detail.count;
wp.hooks.doAction('better_messages_refresh_navigation_tabs');
});
Know when your tab is in front#
render runs once, the first time the tab is opened, and the context it receives is kept up to
date afterwards: context.active is true while the tab is in front and on screen, and false
once another tab comes to the front or the bar is shut. On the mini widgets bar a tab is in front
only while the bar, or the bubble, is open on it and no docked conversation covers it. The
container carries the same as data-active, "1" or "0", turned at the same moment, so you can
read the context when you need it or watch the attribute:
render: function(container, context) {
container.innerHTML = '<div class="my-chat"></div>';
// Mark what the member sees as read, only while the tab is in front.
var observer = new MutationObserver(function() {
if (context.active) markMyMessagesRead();
});
observer.observe(container, { attributes: true, attributeFilter: ['data-active'] });
return function() { observer.disconnect(); };
}
context.surface says which bar the panel belongs to, mini, side or mobile, as before.
context.active is available since Better Messages 3.2.
Bring your tab to the front#
Run the better_messages_open_navigation_tab action with the tab's key, from a button of your
own, a notification, or a link that should land on your tab:
wp.hooks.doAction('better_messages_open_navigation_tab', 'my-leaderboard');
A messenger on screen selects the tab in its strip: the side panel, its collapsed rail, or the phone view. Without one, the mini widgets open their bar, or the bubble, on the tab. On a phone with neither in view, the phone view opens on the tab. A tab asked for while the page is still starting opens as soon as a bar that has it is drawn, within ten seconds, unless the member picks a tab first. On a computer, a key that no bar on the page has does nothing. On a phone the phone view still opens, on its usual tab. Available since Better Messages 3.2.
Add your unread messages to the total#
A plugin with unread messages of its own, shown in its tab, adds them to the total the page shows
with the better_messages_total_unread filter, and runs better_messages_refresh_total_unread
when its count changes:
var myUnread = 0;
wp.hooks.addFilter('better_messages_total_unread', 'my_plugin', function(count) {
return count + myUnread;
});
document.addEventListener('my-chat-unread', function(event) {
myUnread = event.detail.count;
wp.hooks.doAction('better_messages_refresh_total_unread');
});
The total reaches the page title, every .bm-menu-unread counter, the count on the mini widgets
bubble and the better_messages_update_unread action. The Messages tab keeps
Better Messages' own count, so nothing is counted twice, and your tab shows yours with its badge.
A filter added after the page has drawn its counters is picked up at once.
The button that opens the messenger on a phone is printed by the site with the count it has then. Add yours there with the PHP filter of the same name:
<?php
add_filter( 'better_messages_total_unread', function( $count, $user_id ){
return $count + my_plugin_unread_count( $user_id );
}, 10, 2 );
Both filters, and the action, are available since Better Messages 3.2.
Play the sound of a new message#
A plugin that shows messages of its own plays the messenger's notification sound with
window.BetterMessages.playMessageSound(). It stays quiet when the member turned sounds off or is
in Do not disturb, as for Better Messages' own messages. Whether the message is already on screen is
yours to know, so the call plays whenever it is made. It returns a promise of whether the sound
played:
window.BetterMessages.playMessageSound().then(function(played) {
if (!played) showMyOwnNotice();
});
Available since Better Messages 3.2.
When something goes wrong#
A tab without a key or a label, a link or page tab without a url, and a custom tab with
neither render nor onClick are left out, and only the first of two tabs with the same key is
kept. If the filter throws, or returns something that is not an array, the bar shows its own tabs
and the error is logged to the browser console. An error in render or onClick is logged too,
and the rest of the messenger carries on.
The PHP filter#
The JavaScript filter decides what a tab looks like in the browser, but everyone who loads the page runs it. To give a tab only to some members, add it on the server:
<?php
add_filter( 'better_messages_custom_tabs', 'my_staff_tab', 10, 2 );
function my_staff_tab( $tabs, $user_id ){
if ( $user_id <= 0 || ! user_can( $user_id, 'edit_posts' ) ) {
return $tabs;
}
$tabs[] = array(
'key' => 'staff-room',
'label' => 'Staff room',
'icon' => 'users',
'type' => 'content',
'bars' => array( 'side', 'mobile' ),
'content' => '<p>Rota, handbook and contacts:</p>[my_staff_links]',
);
return $tabs;
}
The filter receives the admin's custom tabs, already without the ones hidden from the member's
role, so you can also change or remove those. $user_id is the member, negative for a guest and
0 for a visitor who has not started chatting as a guest yet.
A content tab's content is rendered by the site when the member opens the tab, with its
shortcodes run for that member, and is never part of the page. The same filter runs when the tab
is opened, so a member who does not get the tab from your filter cannot ask for its content either.
For content you build in PHP, give a content_callback instead of content:
<?php
add_filter( 'better_messages_custom_tabs', 'my_orders_tab', 10, 2 );
function my_orders_tab( $tabs, $user_id ){
if ( $user_id <= 0 || ! function_exists( 'wc_get_orders' ) ) {
return $tabs;
}
$tabs[] = array(
'key' => 'my-orders',
'label' => 'Orders',
'icon' => 'inbox',
'type' => 'content',
'bars' => array( 'mini', 'side', 'mobile' ),
'content_callback' => function( $tab, $user_id ) {
$orders = wc_get_orders( array( 'customer_id' => $user_id, 'limit' => 5 ) );
if ( empty( $orders ) ) {
return '<p>No orders yet.</p>';
}
$html = '<ul>';
foreach ( $orders as $order ) {
$html .= '<li><a href="' . esc_url( $order->get_view_order_url() ) . '">#' . esc_html( $order->get_order_number() ) . '</a> ' . esc_html( wc_get_order_status_name( $order->get_status() ) ) . '</li>';
}
return $html . '</ul>';
},
);
return $tabs;
}
To change the content of any content tab after it is rendered, use
better_messages_navigation_tab_content.
A tab added in PHP comes to the browser like the admin's tabs, so the JavaScript filter sees it too. It is not listed in the admin's bar lists, and it comes at the end of each bar it is on. To place it elsewhere, move it in the JavaScript filter.
A tab drawn by your own script#
Decide in PHP who gets the tab and on which bars, and draw it in the browser: add a tab of the type
custom with no address, then give it its render in the JavaScript filter by its key:
<?php
add_filter( 'better_messages_custom_tabs', function( $tabs, $user_id ){
$tabs[] = array(
'key' => 'my-chat',
'label' => 'Support',
'icon' => 'chatbubbles',
'type' => 'custom',
'bars' => array( 'mini', 'side', 'mobile' ),
);
return $tabs;
}, 10, 2 );
wp.hooks.addFilter('better_messages_navigation_tabs', 'my_plugin', function(tabs) {
return tabs.map(function(tab) {
if (tab.key !== 'my-chat') return tab;
return Object.assign({}, tab, {
render: function(container, context) { return myChat.mount(container, context); }
});
});
});
Until your script gives it a render or an onClick, the tab stays off the bars, so a page
without your script shows nothing broken. A site whose only tab on the mini widgets bar is yours
still gets the bar. The admin cannot make a custom tab in Appearance: it is for code. Available
since Better Messages 3.2.
A tab a visitor can open before signing in#
A visitor who has not signed in, or started chatting as a guest, meets the sign-in wall over the
whole messenger. Set guestWall to false on your tab, in PHP or in the JavaScript filter, and the
wall leaves that tab open to them, while it still covers everything that needs an account:
$tabs[] = array(
'key' => 'my-chat',
'label' => 'Support',
'type' => 'custom',
'bars' => array( 'side', 'mobile' ),
'guestWall' => false,
);
With such a tab on a bar, the visitor reaches your tab from the strip, and the strip leads back to the wall. On a wide screen the conversation column carries the wall with its sign-in, and the side panel's other tabs show the wall's surface beside it, never a list the visitor cannot use yet. On a phone, and where the list fills the messenger, each other tab carries the wall. The mini widgets show their wall on the Messages pane alone, as they always have. Without such a tab nothing changes. A built-in tab cannot set it.
Remember that the PHP filter receives 0 as $user_id for a visitor, so a check like
$user_id <= 0 keeps your tab from exactly the visitors you mean it for. Available since Better
Messages 3.2.