# Better Messages - Hooks & Functions Reference

> PHP and JavaScript hooks, filters, and functions for extending and customizing Better Messages plugin.

This file contains all documentation content in a single document following the llmstxt.org standard.

## Better Messages JavaScript Actions Reference — Client-Side Hooks

# JavaScript Actions Reference

:::info REQUIREMENTS

JavaScript hooks use the WordPress Hooks API (`wp.hooks`). Add your code to a custom JavaScript file enqueued after Better Messages.

:::

This page lists all JavaScript action hooks available in the Better Messages plugin frontend. Actions allow you to execute custom code when specific events occur on the client side.

---

## Messages

### `better_messages_message_received` {#better_messages_message_received}

Fires when a new message is received — via WebSocket, AJAX polling, or BroadcastChannel relay between tabs.

**Parameters:**
- `message_id` *(number)* — The received message ID

```js
wp.hooks.addAction('better_messages_message_received', 'my_plugin', function(messageId) {
    console.log('New message received: #' + messageId);
    // Update external badge, trigger sound, etc.
});
```

---

### `better_messages_on_local_notification` {#better_messages_on_local_notification}

Fires immediately before showing a browser notification for an incoming message. Only fires when the message sender is not the current user, the thread is not muted, and no active tab is present.

**Parameters:**
- `message` *(object)* — Full message object (message_id, thread_id, sender_id, message content, etc.)

```js
wp.hooks.addAction('better_messages_on_local_notification', 'my_plugin', function(message) {
    // Send to custom notification system
    myNotificationService.notify({
        title: 'New message',
        body: message.message,
        threadId: message.thread_id
    });
});
```

---

### `better_messages_realtime_event` {#better_messages_realtime_event}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Receives custom real-time events sent via the WebSocket server. To send events that trigger this hook, use the [`send_realtime_event`](/hooks/php-functions#send_realtime_event) PHP function.

**Parameters:**
- `eventData` *(object)* — Decrypted custom event data (structure defined by sender)

```js
wp.hooks.addAction('better_messages_realtime_event', 'my_plugin', function(eventData) {
    console.log('Custom event received:', eventData);

    if (eventData.type === 'order_update') {
        showOrderNotification(eventData.order_id);
    }
});
```

---

## Unread Counts

### `better_messages_update_unread` {#better_messages_update_unread}

Fires when the total unread message count changes across all threads. Also re-fires on window load for late-loading scripts.

Since 3.2.0 the total includes the unread messages that plugins add with the [`better_messages_total_unread`](/hooks/js-filters#better_messages_total_unread) filter, and the action fires again when one of them runs [`better_messages_refresh_total_unread`](#better_messages_refresh_total_unread).

**Parameters:**
- `unread` *(number)* — Total unread count

```js
wp.hooks.addAction('better_messages_update_unread', 'my_plugin', function(unread) {
    // Update custom badge element
    document.querySelector('.my-badge').textContent = unread > 0 ? unread : '';
    document.querySelector('.my-badge').style.display = unread > 0 ? 'block' : 'none';
});
```

---

### `better_messages_update_thread_unread` {#better_messages_update_thread_unread}

Fires when the unread count for a specific thread changes. Also re-fires on window load.

**Parameters:**
- `threadId` *(number)* — Thread ID
- `unread` *(number)* — Unread count for this thread

```js
wp.hooks.addAction('better_messages_update_thread_unread', 'my_plugin', function(threadId, unread) {
    // Update per-thread badge
    var badge = document.querySelector('[data-thread="' + threadId + '"] .badge');
    if (badge) badge.textContent = unread;
});
```

---

### `better_messages_refresh_total_unread` {#better_messages_refresh_total_unread}

An action you fire rather than listen to: it makes the page run [`better_messages_total_unread`](/hooks/js-filters#better_messages_total_unread) again and show the new total in the page title, the counters, the mini widgets bubble and [`better_messages_update_unread`](#better_messages_update_unread). Fire it when the unread count your filter adds has changed. Adding or removing the filter itself needs no refresh, the page notices it. See [Add your unread messages to the total](/docs/development/guides/custom-tabs/#add-your-unread-messages-to-the-total). Since 3.2.0.

**Parameters:** none

```js
wp.hooks.doAction('better_messages_refresh_total_unread');
```

---

## Online Status

### `better_messages_user_online` {#better_messages_user_online}

Fires when a user transitions to online status in the presence system. The user ID has been added to the online users map with a timestamp. Use this for custom online indicators, activity logging, or triggering UI updates.

**Parameters:**
- `userId` *(number)* — User ID who came online

```js
wp.hooks.addAction('better_messages_user_online', 'my_plugin', function(userId) {
    console.log('User #' + userId + ' is now online');
});
```

---

### `better_messages_user_offline` {#better_messages_user_offline}

Fires when a user transitions to offline status in the presence system. The user ID has been removed from the online users map. Use this for updating status indicators, logging activity, or cleanup operations.

**Parameters:**
- `userId` *(number)* — User ID who went offline

```js
wp.hooks.addAction('better_messages_user_offline', 'my_plugin', function(userId) {
    console.log('User #' + userId + ' is now offline');
});
```

---

### `better_messages_online_users_loaded` {#better_messages_online_users_loaded}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Fires when the initial list of online users is received from the server, and every ~30 seconds on refresh.

**Parameters:**
- `online` *(number[])* — Array of online user IDs

```js
wp.hooks.addAction('better_messages_online_users_loaded', 'my_plugin', function(onlineUsers) {
    console.log('Online users:', onlineUsers.length);
    // Initialize presence indicators
});
```

---

## Group Calls

### `better_messages_group_call_status` {#better_messages_group_call_status}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Fires when the number of people in a conversation's group call changes. The call server pushes the change, so this is event-driven — you do not need to poll anything, and nothing reaches your own server. It needs the visitor to have a chat connection, which means a logged-in member or a visitor registered through guest chat.

**Parameters:**
- `threadId` *(number)* — Conversation ID
- `counts` *(object)* — `{ video, audio }`, the people in each of the two call rooms

```js
wp.hooks.addAction('better_messages_group_call_status', 'my_plugin', function(threadId, counts) {
    const el = document.querySelector('#room-' + threadId + '-count');

    if ( el ) {
        el.textContent = counts.video;
    }
});
```

Conversations the visitor takes part in are watched automatically. For any other room — a public landing page advertising a chat room, say — call [`BetterMessages.subscribeGroupCallStatus()`](/hooks/js-functions/#subscribeGroupCallStatus) first, and this action then fires for it too.

---

## Chat Rooms

### `better_messages_chat_room_join` {#better_messages_chat_room_join}

Fires after the REST API join request completes for a chat room. The `result` parameter indicates success or failure — check it before assuming the join succeeded, as permission checks may deny access.

**Parameters:**
- `result` *(object)* — API response from join request
- `chatId` *(number)* — Chat room ID

```js
wp.hooks.addAction('better_messages_chat_room_join', 'my_plugin', function(result, chatId) {
    if (result) {
        console.log('User joined chat room #' + chatId);
    } else {
        console.log('User was not allowed to join chat room #' + chatId);
    }
});
```

---

### `better_messages_chat_room_leave` {#better_messages_chat_room_leave}

Fires after the REST API leave request completes for a chat room. The `result` parameter indicates success or failure — leaving may be denied if auto_join is enabled for the room.

**Parameters:**
- `result` *(object)* — API response from leave request
- `chatId` *(number)* — Chat room ID

```js
wp.hooks.addAction('better_messages_chat_room_leave', 'my_plugin', function(result, chatId) {
    if (result) {
        console.log('User left chat room #' + chatId);
    } else {
        console.log('User was not allowed to leave chat room #' + chatId);
    }
});
```

---

## Conversations

### `better_messages_conversation_with_user_opened` {#better_messages_conversation_with_user_opened}

Fires after a private conversation with a user is successfully opened or created via the REST API. E2E key setup (if enabled) is complete at this point. Fires before navigation to the thread occurs, giving you a chance to intercept or augment the flow.

**Parameters:**
- `element` *(HTMLElement)* — DOM element that triggered the conversation open
- `thread_id` *(number)* — Thread ID
- `data` *(object)* — API response with thread details
- `uniqueKey` *(string|null)* — Optional unique identifier
- `useMiniChat` *(boolean)* — Whether mini chat was used

```js
wp.hooks.addAction('better_messages_conversation_with_user_opened', 'my_plugin', function(el, threadId, data, key, mini) {
    console.log('Opened conversation thread #' + threadId + (mini ? ' (mini chat)' : ''));
});
```

---

## Navigation

### `better_messages_refresh_navigation_tabs` {#better_messages_refresh_navigation_tabs}

An action you fire rather than listen to: it makes the messenger's navigation bars run [`better_messages_navigation_tabs`](/hooks/js-filters#better_messages_navigation_tabs) again and draw what it returns. Fire it when something your filter reads has changed, a count for a badge say. Adding or removing the filter itself needs no refresh, the bars notice it.

**Parameters:** none

```js
wp.hooks.doAction('better_messages_refresh_navigation_tabs');
```

:::info

Available since Better Messages 3.1.5.

:::

---

### `better_messages_open_navigation_tab` {#better_messages_open_navigation_tab}

An action you fire rather than listen to: it brings a navigation tab to the front, from a button of your own, a notification, or a link that should land on your tab. Pass the tab's `key`, as [`better_messages_navigation_tabs`](/hooks/js-filters#better_messages_navigation_tabs) lists it. See [Bring your tab to the front](/docs/development/guides/custom-tabs/#bring-your-tab-to-the-front). Since 3.2.0.

**Parameters:**
- `key` *(string)* — The tab's key

```js
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 when its bar has it. 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 wide screen, a key that no bar on the page has does nothing.

---

## Calls

### `better_messages_call_accepted` {#better_messages_call_accepted}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Fires when the recipient accepts an incoming call and any pending call timeouts are cleared. Use this to update call UI, start call duration timers, or log call acceptance events.

**Parameters:**
- `message_id` *(number)* — Call message ID
- `thread_id` *(number)* — Thread ID

```js
wp.hooks.addAction('better_messages_call_accepted', 'my_plugin', function(messageId, threadId) {
    console.log('Call accepted in thread #' + threadId);
});
```

---

### `better_messages_call_end` {#better_messages_call_end}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Fires when a call ends, at the beginning of the `endCall()` flow before any cleanup. The `action` parameter indicates the reason: `'abort'` (caller hung up), `'reject'`/`'rejected'` (rejected by either party), or `null` for normal call completion.

**Parameters:**
- `message_id` *(number)* — Call message ID
- `thread_id` *(number)* — Thread ID
- `action` *(string|null)* — End reason: `'abort'`, `'reject'`, `'rejected'`, or `null` (normal end)

```js
wp.hooks.addAction('better_messages_call_end', 'my_plugin', function(messageId, threadId, action) {
    console.log('Call ended in thread #' + threadId + ', reason: ' + (action || 'normal'));
});
```

---

### `better_messages_call_aborted` {#better_messages_call_aborted}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Fires when an incoming call times out with no response within the timeout period. The call video sound has been stopped and the incoming call UI has been hidden before this hook fires. Use this to clean up call UI or log missed calls.

**Parameters:**
- `message_id` *(number)* — Call message ID
- `thread_id` *(number)* — Thread ID

```js
wp.hooks.addAction('better_messages_call_aborted', 'my_plugin', function(messageId, threadId) {
    console.log('Call timed out in thread #' + threadId);
});
```

---

### `better_messages_call_self_rejected` {#better_messages_call_self_rejected}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Fires when the caller cancels their own outgoing call before the recipient responds.

**Parameters:**
- `message_id` *(number)* — Call message ID
- `thread_id` *(number)* — Thread ID

---

### `better_messages_call_user_rejected` {#better_messages_call_user_rejected}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Fires when the recipient explicitly rejects a call or is busy in another call. The `reason` parameter contains a human-readable message distinguishing between active rejection and busy status. Use this to display rejection notifications or update call history.

**Parameters:**
- `message_id` *(number)* — Call message ID
- `thread_id` *(number)* — Thread ID
- `user_id` *(number)* — User who rejected
- `reason` *(string)* — Rejection reason message

```js
wp.hooks.addAction('better_messages_call_user_rejected', 'my_plugin', function(messageId, threadId, userId, reason) {
    console.log('Call rejected by user #' + userId + ': ' + reason);
});
```

---

## Better Messages JavaScript Filters Reference — Client-Side Hooks

# JavaScript Filters Reference

:::info REQUIREMENTS

JavaScript hooks use the WordPress Hooks API (`wp.hooks`). Add your code to a custom JavaScript file enqueued after Better Messages.

:::

This page lists all JavaScript filter hooks available in the Better Messages plugin frontend. Filters allow you to modify data, customize UI elements, and control client-side behavior.

---

## UI Elements

### `better_messages_header_element` {#better_messages_header_element}

Replaces or modifies the header element at the top of the threads list page. Return an HTML string or React JSX element. The `page` parameter identifies which page is rendering (currently `'index'`), and `mobileView` indicates if the mobile layout is active.

**Parameters:**
- `header` *(JSX.Element)* — Default IndexHeader component
- `page` *(string)* — Page identifier (`'index'`)
- `mobileView` *(boolean)* — Whether mobile view is active

**Returns:** `JSX.Element|string` — React component or HTML string

```js
wp.hooks.addFilter('better_messages_header_element', 'my_plugin', function(header, page, mobileView) {
    if (mobileView) {
        return 'Messages';
    }
    return header;
});
```

![Header element example](./img/header_element.png)

---

### `better_messages_footer_element` {#better_messages_footer_element}

Replaces or modifies the footer element at the bottom of the threads list page. Return an HTML string or React JSX element. Works the same as the header element filter with `page` and `mobileView` parameters.

**Parameters:**
- `footer` *(JSX.Element)* — Default ChatFooter component
- `page` *(string)* — Page identifier (`'index'`)
- `mobileView` *(boolean)* — Whether mobile view is active

**Returns:** `JSX.Element|string`

```js
wp.hooks.addFilter('better_messages_footer_element', 'my_plugin', function(footer, page, mobileView) {
    if (page === 'index') {
        return 'Add custom content';
    }
    return footer;
});
```

![Footer element example](./img/footer_element.png)

---

### `better_messages_thread_header_actions` {#better_messages_thread_header_actions}

Filters the complete list of action buttons in the conversation header — the right-side area with the call buttons, minimize/maximize controls and the "More" menu. The filter receives **every built-in button as an array item with a stable `key`**, so custom buttons can be inserted at any position, and built-in buttons can be reordered, removed, or replaced.

This is the supported way to customize the conversation header. Do not insert your own DOM node into `.thread-actions` — that container is rendered by React and re-created whenever the header re-renders, so a manually inserted element is repositioned or removed.

The same filter also runs for [mini chats](/docs/features/mini-widgets/); use the `isMiniChat` argument to tell the surfaces apart.

**Parameters:**
- `actions` *(array)* — The built-in header actions for the current conversation state
- `thread` *(object)* — Thread object
- `anotherUser` *(object|false)* — Other user in a one-to-one conversation, or `false`
- `isMiniChat` *(boolean)* — Whether the actions are being rendered in a mini chat header

**Returns:** `array`

**Built-in action keys** (each present only when the corresponding button applies to the current conversation and state):

| Surface | Keys, in default order |
|---|---|
| Conversation header | `online-users` (chat rooms, WebSocket version), `audio-call`, `video-call`, `group-audio-call`, `group-video-call`, `minimize` (to mini chat), `maximize`, `unmaximize` (restore from maximized), `more` (the ⋯ dropdown) |
| Mini chat, open | `video-call`, `audio-call`, `group-audio-call`, `group-video-call`, `minimize`, `close` |
| Mini chat, collapsed | `open`, `close` |

**Properties of each action:** `key` *(string, required — must be unique)*, `icon` *(string of SVG HTML, or a React node)*, `tooltip` *(string, optional)*, `classes` *(string, optional extra CSS classes)*, `onClick` *(function, optional)*, `onAuxClick` *(function, optional, middle-click)*. Built-in actions additionally carry `builtIn: true`, and the `more` item carries a pre-rendered `element` instead of an `icon` — pass it through unchanged unless you intend to remove it.

Adding a custom button before the window controls:

```js
wp.hooks.addFilter('better_messages_thread_header_actions', 'my_plugin', function(actions, thread, anotherUser, isMiniChat) {
    var anchor = actions.findIndex(function(action) {
        return ['minimize', 'maximize', 'unmaximize', 'more', 'close'].indexOf(action.key) !== -1;
    });

    var item = {
        key: 'safety-menu',
        tooltip: 'Safety options',
        classes: 'my-safety-menu',
        icon: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24" fill="currentColor"><circle cx="12" cy="5" r="2"/><circle cx="12" cy="12" r="2"/><circle cx="12" cy="19" r="2"/></svg>',
        onClick: function(event) {
            openMySafetyMenu(thread.thread_id, event.currentTarget);
        }
    };

    if (anchor === -1) {
        actions.push(item);
    } else {
        actions.splice(anchor, 0, item);
    }

    return actions;
});
```

Removing built-in buttons:

```js
wp.hooks.addFilter('better_messages_thread_header_actions', 'my_plugin', function(actions) {
    return actions.filter(function(action) {
        return action.key !== 'video-call' && action.key !== 'audio-call';
    });
});
```

Replacing the behavior of a built-in button while keeping its position and icon:

```js
wp.hooks.addFilter('better_messages_thread_header_actions', 'my_plugin', function(actions, thread) {
    var index = actions.findIndex(function(action) { return action.key === 'video-call'; });

    if (index !== -1) {
        actions[index] = Object.assign({}, actions[index], {
            onClick: function() {
                openMyCallFlow(thread.thread_id);
            }
        });
    }

    return actions;
});
```

Custom actions inherit the styling of the built-in header buttons — sizing, hover state and theme color are applied automatically, and your `classes` are added alongside `bm-thread-header-action` for further styling. Each button carries a `data-action-key` attribute matching its `key`, which is a stable anchor for a dropdown positioned against it.

:::info

Actions without a `key`, or without both an `icon` and an `element`, are skipped, and duplicate keys keep only the first occurrence. If your callback throws or returns something that is not an array, the error is logged to the browser console and the header falls back to the built-in actions rather than breaking.

:::

To add an entry to the existing "More" dropdown instead of a standalone button, use [`better_messages_thread_context_menu`](#better_messages_thread_context_menu).

---

### `better_messages_navigation_tabs` {#better_messages_navigation_tabs}

Filters the tabs of each navigation bar of the messenger: the [mini widgets bar](/docs/features/mini-widgets/), the side panel beside the conversations list (and its collapsed rail), and the tab bar at the bottom of the screen on phones. The filter receives **every tab of one bar, in order**, the built-in tabs included under stable keys, so you can add tabs, remove them, reorder them, rename them or give them another icon.

The admin's own [custom tabs](/docs/features/custom-tabs/) are in the list too, so a filter sees each bar exactly as it will be drawn.

:::info

Available since Better Messages 3.1.5.

:::

**Parameters:**
- `tabs` *(array)* — The tabs of the bar, in the order the admin set
- `surface` *(string)* — Which bar: `'mini'` (the mini widgets bar), `'side'` (the side panel and its collapsed rail) or `'mobile'` (the tab bar on phones)

**Returns:** `array`

**Built-in tab keys** (each present only when that tab is on for the bar and the member can see it):

| Key | Tab |
|---|---|
| `messages` | Conversations |
| `friends` | Friends |
| `groups` | Groups |
| `courses` | Courses |
| `ai-bots` | AI Bots |
| `chat-rooms` | Chat Rooms |
| `users` | Users |

The admin's custom tabs have keys that start with `ct_`.

**Properties of each tab:**
- `key` *(string, required)* — Unique on the bar. It is also the `data-tab` attribute of a tab you add, and the id the admin's tab order uses
- `label` *(string, required)* — Shown with the icon, or as a tooltip when the bar shows icons only
- `icon` *(string or React element, optional)* — A preset name from the icon picker (`comment`, `users`, `home`, `star`…), SVG markup, or an element. Leave it empty for the stock glyph
- `type` *(string)* — For a tab you add: `'link'` (goes to `url`), `'page'` (shows `url` in a frame inside the messenger) or `'custom'` (your own panel). Built-in tabs carry `'builtin'`, and the admin's content tabs `'content'`
- `url` *(string)* — The address of a `link` or `page` tab
- `newWindow` *(boolean, optional)* — Opens a `link` tab in a new window
- `badge` *(number or string, optional)* — A count or a short text over the icon. Zero shows nothing
- `render` *(function, optional)* — `render( container, context )` draws the panel of a `custom` tab into `container`, a plain DOM element, the first time the tab is opened. It may return a function, called when the panel goes. `context.surface` is the bar. `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: the object is the one `render` received, kept up to date, and the container carries the same as `data-active` (`"1"` or `"0"`). See [Know when your tab is in front](/docs/development/guides/custom-tabs/#know-when-your-tab-is-in-front). Since 3.2.0 for `context.active`
- `onClick` *(function, optional)* — `onClick( event, context )` runs on every press of the tab. A `custom` tab with `onClick` and no `render` never comes to the front, it only runs the click
- `guestWall` *(boolean, optional)* — `false` on a tab a visitor may open before signing in: the sign-in wall leaves that tab open to them and still covers the rest of the messenger. Ignored on a built-in tab. See [A tab a visitor can open before signing in](/docs/development/guides/custom-tabs/#a-tab-a-visitor-can-open-before-signing-in). Since 3.2.0

Built-in tabs also carry `builtIn: true`. You can change their `label`, `icon`, `badge` and `onClick`, or leave them out of the list. What a built-in tab shows stays the plugin's.

Adding a tab with a panel of your own:

```js
wp.hooks.addFilter('better_messages_navigation_tabs', 'my_plugin', function(tabs, surface) {
    tabs.push({
        key: 'my-notes',
        label: 'Notes',
        icon: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M4 4h16v16H4z"/><path d="M8 9h8M8 13h8M8 17h5"/></svg>',
        type: 'custom',
        render: function(container, context) {
            container.innerHTML = 'Loading…';
            var timer = setInterval(function() { refreshMyNotes(container); }, 30000);
            refreshMyNotes(container);
            return function() { clearInterval(timer); };
        }
    });

    return tabs;
});
```

Renaming Conversations and removing the Users tab from the phone bar:

```js
wp.hooks.addFilter('better_messages_navigation_tabs', 'my_plugin', function(tabs, surface) {
    return tabs
        .filter(function(tab) {
            return ! (surface === 'mobile' && tab.key === 'users');
        })
        .map(function(tab) {
            return tab.key === 'messages' ? Object.assign({}, tab, { label: 'Inbox' }) : tab;
        });
});
```

A link to the course catalogue, first on the phone bar only:

```js
wp.hooks.addFilter('better_messages_navigation_tabs', 'my_plugin', function(tabs, surface) {
    if (surface !== 'mobile') return tabs;

    return [{
        key: 'catalogue',
        label: 'Courses',
        icon: 'home',
        type: 'link',
        url: '/courses/'
    }].concat(tabs);
});
```

A tab whose badge follows something of your own: return the count from the filter, and ask the bars to run it again with [`better_messages_refresh_navigation_tabs`](/hooks/js-actions#better_messages_refresh_navigation_tabs) when the count changes.

```js
var pendingTasks = 0;

wp.hooks.addFilter('better_messages_navigation_tabs', 'my_plugin', function(tabs) {
    return tabs.map(function(tab) {
        return tab.key === 'messages' ? Object.assign({}, tab, { badge: pendingTasks }) : tab;
    });
});

function onTasksChanged(count) {
    pendingTasks = count;
    wp.hooks.doAction('better_messages_refresh_navigation_tabs');
}
```

The bars run the filter again by themselves when a filter is added or removed, so a script that loads after the messenger has drawn works as well.

A `custom` tab added on the server with [`better_messages_custom_tabs`](/hooks/php-filters#better_messages_custom_tabs) comes to the filter with no `render`. Give it one by its key, and it shows on the bars the server chose. Without a `render` or an `onClick` it stays off them. Since 3.2.0.

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

To bring a tab to the front from your own code, run [`better_messages_open_navigation_tab`](/hooks/js-actions#better_messages_open_navigation_tab) with its key.

:::info

Tabs without a `key` or a `label`, a `link` or `page` tab without a `url`, and a `custom` tab with neither `render` nor `onClick` are skipped, and duplicate keys keep only the first occurrence. A `content` tab can only be one the site published, as its content is rendered by the site. If your callback throws or returns something that is not an array, the error is logged to the browser console and the bar falls back to its own tabs rather than breaking. An error inside `render` or `onClick` is logged the same way.

:::

To add tabs on the server, for the members who should see them, use the PHP filter [`better_messages_custom_tabs`](/hooks/php-filters#better_messages_custom_tabs).

---

### `better_messages_messages_list_before` {#better_messages_messages_list_before}

Adds HTML content above the messages list, before the message history begins. The HTML is parsed and rendered as React elements. Return an empty string to show nothing. Useful for thread-specific announcements, encryption status banners, or custom info boxes.

**Parameters:**
- `content` *(string)* — Default empty string
- `thread` *(object)* — Thread object

**Returns:** `string` — HTML string

```js
wp.hooks.addFilter('better_messages_messages_list_before', 'my_plugin', function(content, thread) {
    if (thread.type === 'group') {
        return 'Welcome to the group chat!';
    }
    return content;
});
```

![Messages list before example](./img/messages_list_before.png)

---

### `better_messages_send_button_after` {#better_messages_send_button_after}

Adds HTML content after the send button in the reply form area. The HTML is rendered inline with the send button. Useful for adding custom action buttons, emoji shortcuts, or addon-specific controls next to the message composer.

**Parameters:**
- `content` *(string)* — Default empty string
- `thread` *(object)* — Thread object

**Returns:** `string` — HTML string

```js
wp.hooks.addFilter('better_messages_send_button_after', 'my_plugin', function(content, thread) {
    return '<button class="my-custom-btn" onclick="myAction()">+</button>';
});
```

![Send button after example](./img/send_button_after.png)

---

### `better_messages_participants_list_after` {#better_messages_participants_list_after}

Adds HTML content after the participants list in thread information panel.

**Parameters:**
- `content` *(string)* — Default empty string
- `thread` *(object)* — Thread object

**Returns:** `string` — HTML string

```js
wp.hooks.addFilter('better_messages_participants_list_after', 'my_plugin', function(html, thread) {
    html += 'Add custom data';
    return html;
});
```

![Participants list after example](./img/participants_list_after.png)

---

### `better_messages_user_settings_after` {#better_messages_user_settings_after}

Adds custom settings sections after the user settings options.

**Parameters:**
- `elements` *(array)* — Default empty array

**Returns:** `array` — Array of React elements

---

## Guest Authentication Screen

The guest authentication screen appears when a visitor without a WordPress account or guest record tries to start a conversation. By default it shows two stacked sections — **Continue with account** (Login / Register) and **Continue as guest** (display-name form). It is rendered in three places:

- **Modal popup** — when a guest clicks a chat button (live chat, mini-widget "Start a new conversation", chat-room "Join", user / AI bot list item)
- **Mini-widget banner** — inside the floating mini-widget when a guest opens it
- **Full messages page wall** — on the main `/messages/` page (or wherever the messages app is embedded)

The filters below let you inject arbitrary HTML at three positions inside the screen without overriding the component. They fire in **all three locations automatically** because the underlying `AuthScreen` component is shared. Each filter receives the current HTML output (empty string by default) and an `args` object describing which sections are visible. Concatenate your HTML to the input and return the new string; return the input unchanged for no injection. Filters from multiple plugins compose naturally because each receives the previous filter's output.

:::info

The filters work with both the free and WebSocket builds. The injected HTML is rendered into the screen verbatim, so you can include images, links, lists, or any markup. Style your injected content with CSS that targets your custom classes.

:::

![Auth screen with all three filters active in the modal popup](./img/auth_required_filters.png)

The same filters fire inside the mini-widget banner and the full messages page wall:

![Auth screen with all three filters active in the mini-widget banner](./img/auth_required_filters_locations.png)

### `better_messages_auth_required_top` {#better_messages_auth_required_top}

Injects content **above** the "Continue with account" and "Continue as guest" sections. Useful for a welcome message, marketing intro, or context about who the visitor is about to chat with.

**Parameters:**
- `output` *(string)* — Empty by default; concatenate to it (`output + '…'`) to compose with content from other filters
- `args` *(object)* — `{ showLogin: boolean, showGuestSubHeader: boolean, forceGuest: boolean }`

**Returns:** `string` — HTML string to inject (return the input unchanged for no injection)

```js
wp.hooks.addFilter('better_messages_auth_required_top', 'my_plugin', function (output, args) {
    return output + '' +
        'Welcome to our store chat' +
        'Sign in to track your orders or continue as a guest.' +
    '';
});
```

---

### `better_messages_auth_required_between` {#better_messages_auth_required_between}

Injects content **between** the "Continue with account" section and the "Continue as guest" section. Useful for a divider, a "— OR —" label, or contextual help that should sit between the two auth choices.

**Parameters:**
- `output` *(string)*
- `args` *(object)* — `{ showLogin: boolean, showGuestSubHeader: boolean, forceGuest: boolean }`

**Returns:** `string`

```js
wp.hooks.addFilter('better_messages_auth_required_between', 'my_plugin', function (output) {
    return output + 'or';
});
```

---

### `better_messages_auth_required_bottom` {#better_messages_auth_required_bottom}

Injects content **below** the "Continue as guest" section. Useful for legal disclosures, links to your privacy policy, support contacts, or any closing text the visitor should see before chatting.

**Parameters:**
- `output` *(string)*
- `args` *(object)* — `{ showLogin: boolean, showGuestSubHeader: boolean, forceGuest: boolean }`

**Returns:** `string`

```js
wp.hooks.addFilter('better_messages_auth_required_bottom', 'my_plugin', function (output) {
    return output + '' +
        'By continuing you agree to our Privacy Policy.' +
    '';
});
```

---

### Layout tips

The default modal stacks the login section above the guest section vertically. If you want them side-by-side (and your custom content full-width above), use CSS Grid on the modal wrapper:

```css
.bm-modal-window.bm-modal-guest-settings-panel .bm-auth-required-modal {
    display: grid;
    grid-template-columns: 1fr 1fr;
    gap: 16px;
    align-items: start;
}
.bm-modal-window.bm-modal-guest-settings-panel .bm-pre-chat-intro,
.bm-modal-window.bm-modal-guest-settings-panel .my-auth-footnote { grid-column: 1 / -1; }
.bm-modal-window.bm-modal-guest-settings-panel .bm-guest-login { grid-column: 1; }
.bm-modal-window.bm-modal-guest-settings-panel .bm-guest-form { grid-column: 2; }
.bm-modal-window.bm-modal-guest-settings-panel .bm-guest-login-actions { display: flex; flex-direction: column; gap: 8px; }
.bm-modal-window.bm-modal-guest-settings-panel .bm-modal-window-content { overflow-y: auto; }
```

Replace `.bm-pre-chat-intro` and `.my-auth-footnote` with whatever root class names your injected HTML uses.

---

## Message Styling & Context Menu

### `better_messages_single_message_class` {#better_messages_single_message_class}

Adds custom CSS classes to individual message elements in the message list. The `message` object contains all message properties (sender_id, thread_id, content, etc.) so you can conditionally style messages based on sender, content, or metadata.

**Parameters:**
- `className` *(string)* — Current CSS classes
- `message` *(object)* — Message object

**Returns:** `string`

```js
wp.hooks.addFilter('better_messages_single_message_class', 'my_plugin', function(className, message) {
    if (message.sender_id === 1) {
        className += ' admin-message';
    }
    return className;
});
```

---

### `better_messages_single_message_context_menu` {#better_messages_single_message_context_menu}

Modifies the context menu items shown when right-clicking or long-pressing a message. Each menu item should have `key`, `label`, `icon` (SVG string), and `action` (callback function) properties. You can add, remove, or reorder items in the array.

**Parameters:**
- `items` *(array)* — Array of MessageContextMenuItem objects
- `message` *(object)* — Message object
- `thread` *(object)* — Thread object

**Returns:** `array`

**Available properties for menu items:** `key` *(string, required for React)*, `label` *(string)*, `icon` *(string, SVG HTML)*, `action` *(function, callback on click)*.

```js
wp.hooks.addFilter('better_messages_single_message_context_menu', 'my_plugin', function(items, message, thread) {
    items.push({
        key: 'context-report-item',
        icon: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24"><path d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm1 15h-2v-2h2v2zm0-4h-2V7h2v6z"/></svg>',
        label: 'Report',
        action: function() {
            alert('Reported message #' + message.message_id);
        }
    });
    return items;
});
```

![Message context menu example](./img/single_message_context_menu.png)

---

### `better_messages_video_preload_attribute` {#better_messages_video_preload_attribute}

Controls the `preload` attribute for video players in messages.

**Parameters:**
- `preload` *(string)* — Default `'auto'`

**Returns:** `string` — `'none'`, `'metadata'`, or `'auto'`

```js
wp.hooks.addFilter('better_messages_video_preload_attribute', 'my_plugin', function() {
    return 'metadata'; // Save bandwidth
});
```

---

## Thread Styling & Context Menu

### `better_messages_single_thread_class` {#better_messages_single_thread_class}

Adds custom CSS classes to individual thread items in the threads list sidebar. The `thread` object contains all thread properties (thread_id, type, subject, unread_count, etc.) so you can conditionally style threads based on state or metadata.

**Parameters:**
- `className` *(string)* — Current CSS classes
- `thread` *(object)* — Thread object

**Returns:** `string`

```js
wp.hooks.addFilter('better_messages_single_thread_class', 'my_plugin', function(className, thread) {
    if (thread.pinned) {
        className += ' pinned-thread';
    }
    return className;
});
```

---

### `better_messages_thread_context_menu` {#better_messages_thread_context_menu}

Modifies the context menu actions shown when right-clicking or long-pressing a thread in the threads list. Each action should have `key`, `label`, `tooltip`, `icon`, `classes`, `showInThread`, `showInList`, `onClick`, and optionally `onAuxClick` properties.

**Parameters:**
- `actions` *(array)* — Array of ThreadAction objects
- `thread` *(object)* — Thread object
- `anotherUser` *(object|false)* — Other user in PM, or `false`
- `isMiniChat` *(boolean)* — Whether in mini chat mode

**Returns:** `array`

**Available properties for actions:** `key` *(string, required for React)*, `label` *(string)*, `tooltip` *(string)*, `icon` *(string, SVG HTML)*, `classes` *(string, CSS classes)*, `showInThread` *(bool)*, `showInList` *(bool)*, `onClick` *(function)*, `onAuxClick` *(function, middle-click)*.

```js
wp.hooks.addFilter('better_messages_thread_context_menu', 'my_plugin', function(buttons, thread, anotherUser, isMiniChat) {
    buttons.push({
        key: 'custom-action',
        showInThread: true,
        showInList: true,
        tooltip: 'Archive this conversation',
        label: 'Archive',
        icon: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24"><path d="M20.54 5.23l-1.39-1.68C18.88 3.21 18.47 3 18 3H6c-.47 0-.88.21-1.16.55L3.46 5.23C3.17 5.57 3 6.02 3 6.5V19c0 1.1.9 2 2 2h14c1.1 0 2-.9 2-2V6.5c0-.48-.17-.93-.46-1.27zM12 17.5L6.5 12H10v-2h4v2h3.5L12 17.5z"/></svg>',
        classes: 'bm-archive-action',
        onClick: function() {
            alert('Archive thread #' + thread.thread_id);
        }
    });
    return buttons;
});
```

![Thread context menu example](./img/thread_context_menu.png)

To add a standalone button to the conversation header instead of an entry in this menu, use [`better_messages_thread_header_actions`](#better_messages_thread_header_actions).

---

### `better_messages_threads_list_selector` {#better_messages_threads_list_selector}

Filters the database query selector for the threads list.

**Parameters:**
- `selector` *(object)* — Default: `{ isDeleted: 0, isHidden: 0, adminAccess: { $exists: false } }`

**Returns:** `object`

```js
wp.hooks.addFilter('better_messages_threads_list_selector', 'my_plugin', function(selector) {
    // Only show group threads
    selector.type = 'group';
    return selector;
});
```

---

## User Elements

### `better_messages_display_name_allowed_html` {#better_messages_display_name_allowed_html}

Filters the HTML a display name is allowed to carry, in the browser.

A display name is rendered as markup rather than printed as text, which is what lets an integration hang a badge or a rank icon off one. The name is also whatever the member typed into their own profile, so the messenger filters every name through this allowlist before rendering it — including a name it loaded from local storage or received over the realtime connection, neither of which passes through the server on the way in. The allowlist arrived as a security improvement in 3.0.4.

This is the browser half of [the PHP filter of the same name](/hooks/php-filters/#better_messages_display_name_allowed_html). Both lists carry the hook, under the same name and the same shape, and a tag has to be added to both to render everywhere — PHP alone covers wp-admin and server-rendered surfaces, and the messenger still drops it.

**Parameters:**
- `allowed` *(object)* — Tag name to allowed-attribute map. A key ending in `*` matches by prefix, so `'data-*': true` admits every data attribute

**Returns:** `object`

```js
wp.hooks.addFilter(
    'better_messages_display_name_allowed_html',
    'my_plugin',
    function ( allowed ) {
        allowed.ins = { 'class': true, 'data-*': true };

        return allowed;
    }
);
```

Enqueue your script with `wp-hooks` as a dependency so the filter registers before the messenger renders its first name.

:::warning Some things stay refused
Event-handler attributes (`on*`), `srcdoc` and `formaction` are stripped whatever this filter returns, and so are scripting and framing elements — `iframe`, `script`, `object`, `embed`, `form`, `svg`, `math` and the rest. A display name is attacker-controlled on any site where a member can edit their own profile, and putting those back would undo the security improvement this allowlist is. No filter can re-enable them.
:::

---

### `better_messages_avatar_class` {#better_messages_avatar_class}

Adds custom CSS classes to user avatar elements throughout the UI. The default includes `'avatar bbpm-avatar'` and an `'online'` class when the user is online. The `user` object provides user data for conditional styling.

**Parameters:**
- `className` *(string)* — Default `'avatar bbpm-avatar'` + online status
- `user` *(object)* — User object

**Returns:** `string`

```js
wp.hooks.addFilter('better_messages_avatar_class', 'my_plugin', function(className, user) {
    if (user.verified) {
        className += ' verified-avatar';
    }
    return className;
});
```

---

### `better_messages_avatar_attributes` {#better_messages_avatar_attributes}

Adds custom HTML attributes to avatar elements.

**Parameters:**
- `attributes` *(object)* — Default empty object
- `user` *(object)* — User object

**Returns:** `object`

```js
wp.hooks.addFilter('better_messages_avatar_attributes', 'my_plugin', function(attrs, user) {
    attrs['data-role'] = user.role || 'member';
    return attrs;
});
```

---

### `better_messages_before_avatar_click` {#better_messages_before_avatar_click}

Intercepts a click on a member's avatar, or on a mention of them in a message (since 3.0.9), before the default profile navigation occurs. Return `true` to prevent the default behavior and handle the click yourself (e.g., open a custom profile modal). Return `false` to allow normal navigation.

**Parameters:**
- `prevented` *(boolean)* — Default `false`
- `user_id` *(number)* — User ID

**Returns:** `boolean`

```js
wp.hooks.addFilter('better_messages_before_avatar_click', 'my_plugin', function(prevented, userId) {
    // Open custom profile modal instead of navigating
    openProfileModal(userId);
    return true; // Prevent default navigation
});
```

---

### `better_messages_username_class` {#better_messages_username_class}

Adds custom CSS classes to username elements.

**Parameters:**
- `className` *(string)* — Default `'user bm-user'`
- `user` *(object)* — User object

**Returns:** `string`

```js
wp.hooks.addFilter('better_messages_username_class', 'my_plugin', function(classes, user) {
    classes += ' notranslate';
    return classes;
});
```

---

### `better_messages_username_attributes` {#better_messages_username_attributes}

Adds custom HTML attributes to username elements.

**Parameters:**
- `attributes` *(object)* — Default empty object
- `user` *(object)* — User object

**Returns:** `object`

---

### `better_messages_before_username_click` {#better_messages_before_username_click}

Intercepts username click events before the default profile navigation occurs. Return `true` to prevent the default behavior and handle the click yourself. Return `false` to allow normal navigation to the user's profile.

**Parameters:**
- `prevented` *(boolean)* — Default `false`
- `user_id` *(number)* — User ID

**Returns:** `boolean`

```js
wp.hooks.addFilter('better_messages_before_username_click', 'my_plugin', function(prevented, userId) {
    openProfileModal(userId);
    return true;
});
```

---

## Message Sending

### `better_messages_before_message_sent` {#better_messages_before_message_sent}

Prevents message sending or performs custom validation before a message is sent. Return `true` to block the message from being sent (the user stays in the composer). Return `false` to allow sending to proceed normally.

**Parameters:**
- `prevented` *(boolean)* — Default `false`
- `threadId` *(number)* — Thread ID
- `thread` *(object)* — Thread object

**Returns:** `boolean` — `true` to prevent, `false` to allow

```js
wp.hooks.addFilter('better_messages_before_message_sent', 'my_plugin', function(prevented, threadId, thread) {
    if (!confirm('Are you sure you want to send this message?')) {
        return true; // Prevent sending
    }
    return false;
});
```

---

## API & Network

### `better_messages_api_request_config` {#better_messages_api_request_config}

Modifies the axios request configuration before any Better Messages REST API call is made. The config object includes URL, headers, data, and method. Use this to add custom headers, modify URLs, or inject authentication tokens for external auth systems.

**Parameters:**
- `config` *(object)* — Axios request config (URL, headers, data, etc.)

**Returns:** `object`

```js
wp.hooks.addFilter('better_messages_api_request_config', 'my_plugin', function(config) {
    config.headers['X-Custom-Header'] = 'my-value';
    return config;
});
```

---

### `better_messages_api_response` {#better_messages_api_response}

Filters API responses before they are processed by the application. Receives the full axios response object including status, data, and headers. Use this to transform response data, handle custom headers, or log API interactions.

**Parameters:**
- `response` *(object)* — Axios response object

**Returns:** `object`

```js
wp.hooks.addFilter('better_messages_api_response', 'my_plugin', function(response) {
    // Transform or log response data
    console.log('API response:', response.config.url, response.status);
    return response;
});
```

---

### `better_messages_unhandled_api_error` {#better_messages_unhandled_api_error}

Handles unhandled API errors. Return a new config to retry, or `false` to reject.

**Parameters:**
- `retry` *(boolean)* — Default `false`
- `response` *(object)* — Error response
- `config` *(object)* — Original request config

**Returns:** `object|false`

```js
wp.hooks.addFilter('better_messages_unhandled_api_error', 'my_plugin', function(retry, response, config) {
    if (response.status === 401) {
        // Redirect to login
        window.location.href = '/login';
    }
    return false;
});
```

---

## Unread Counts

### `better_messages_total_unread` {#better_messages_total_unread}

Filters the unread count the page shows as the member's total: the page title, every `.bm-menu-unread` counter, the count on the mini widgets bubble and the [`better_messages_update_unread`](/hooks/js-actions#better_messages_update_unread) action. A plugin with unread messages of its own, shown in a navigation tab of its own say, adds them here. The Messages tab keeps Better Messages' own count, so nothing is counted twice. Since 3.2.0.

When your count changes, run [`better_messages_refresh_total_unread`](/hooks/js-actions#better_messages_refresh_total_unread). 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, [`better_messages_total_unread`](/hooks/php-filters#better_messages_total_unread). See [Add your unread messages to the total](/docs/development/guides/custom-tabs/#add-your-unread-messages-to-the-total).

**Parameters:**
- `count` *(number)* — Better Messages' own unread count

**Returns:** `number` — rounded down. A negative value or one that is not a number shows Better Messages' own count, and so does an error in your callback, which is logged to the browser console

```js
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');
});
```

---

## Navigation

### `better_messages_navigate_url` {#better_messages_navigate_url}

Intercepts URL navigation when opening conversations. Return `true` if you handle navigation yourself.

**Parameters:**
- `handled` *(boolean)* — Default `false`
- `url` *(string)* — Target URL

**Returns:** `boolean`

```js
wp.hooks.addFilter('better_messages_navigate_url', 'my_plugin', function(handled, url) {
    // Use SPA router instead of full page reload
    myRouter.push(url);
    return true;
});
```

---

## File Uploads

### `better_messages_uploader_enabled` {#better_messages_uploader_enabled}

Controls whether file drag-and-drop and paste upload functionality is enabled globally. Return `false` to completely disable file uploads in the UI. When disabled, the upload button and drag-drop zones are removed.

**Parameters:**
- `enabled` *(boolean)* — Default `true`

**Returns:** `boolean`

```js
wp.hooks.addFilter('better_messages_uploader_enabled', 'my_plugin', function() {
    return false; // Disable file uploads
});
```

---

### `better_messages_open_uploader_modal` {#better_messages_open_uploader_modal}

Controls whether the file uploader modal opens.

**Parameters:**
- `open` *(boolean)* — Default `true`
- `buttonRef` *(HTMLElement|null)* — Upload button reference

**Returns:** `boolean`

---

## Calls

### `better_messages_call_show_notification` {#better_messages_call_show_notification}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Controls whether to show the incoming call notification.

**Parameters:**
- `show` *(boolean)* — Default `true`
- `message` *(object)* — Incoming call data

**Returns:** `boolean`

```js
wp.hooks.addFilter('better_messages_call_show_notification', 'my_plugin', function(show, message) {
    // Suppress notification for specific threads
    if (message.thread_id === 123) return false;
    return show;
});
```

---

### `better_messages_call_show_incoming_screen` {#better_messages_call_show_incoming_screen}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Controls whether to show the incoming call screen.

**Parameters:**
- `show` *(boolean)* — Default `true`
- `data` *(object)* — Incoming call data

**Returns:** `boolean`

---

### `better_messages_call_answer_force` {#better_messages_call_answer_force}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Indicates whether a call was answered by an external system (e.g., VoIP).

**Parameters:**
- `answered` *(boolean)* — Default `false`
- `messageId` *(number)* — Call message ID
- `threadId` *(number)* — Thread ID

**Returns:** `boolean`

---

### `better_messages_call_create_not_allowed` {#better_messages_call_create_not_allowed}

Controls whether to show error when call creation is denied.

**Parameters:**
- `showError` *(boolean)* — Default `true`
- `thread_id` *(number)* — Thread ID
- `type` *(string)* — `'audio'` or `'video'`

**Returns:** `boolean`

---

### `better_messages_call_join_not_allowed` {#better_messages_call_join_not_allowed}

Controls whether to show error when joining a call is denied.

**Parameters:**
- `showError` *(boolean)* — Default `true`
- `thread_id` *(number)* — Thread ID
- `type` *(string)* — `'audio'` or `'video'`

**Returns:** `boolean`

---

### `better_messages_outgoing_call_not_allowed` {#better_messages_outgoing_call_not_allowed}

Controls whether to show error when starting an outgoing call is denied.

**Parameters:**
- `showError` *(boolean)* — Default `true`
- `user_id` *(number)* — Recipient user ID
- `thread_id` *(number)* — Thread ID
- `type` *(string)* — `'audio'` or `'video'`

**Returns:** `boolean`

---

### `better_messages_group_video_call_items` {#better_messages_group_video_call_items}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Filters the map of participants displayed in group video calls.

**Parameters:**
- `items` *(Map)* — Map of participant identity to GroupVideoParticipantData
- `thread` *(object)* — Thread object

**Returns:** `Map`

---

## Miscellaneous

### `better_messages_max_toasts_limit` {#better_messages_max_toasts_limit}

Limits the maximum number of toast notifications (on-site popups for new messages) displayed at the same time. Return `null` for unlimited toasts, or a number to cap them. Older toasts are removed when the limit is exceeded.

**Parameters:**
- `limit` *(null|number)* — Default `null` (no limit)

**Returns:** `null|number`

```js
wp.hooks.addFilter('better_messages_max_toasts_limit', 'my_plugin', function() {
    return 3; // Max 3 toasts
});
```

![Toast notifications example](./img/max_toasts_limit.png)

---

### `better_messages_emoji_important` {#better_messages_emoji_important}

Controls whether the `!important` flag is applied to emoji CSS styles. Default is `true` to ensure emojis render correctly regardless of theme CSS. Return `false` if emoji styles conflict with your theme and you want to manage emoji sizing yourself.

**Parameters:**
- `useImportant` *(boolean)* — Default `true`

**Returns:** `boolean`

```js
wp.hooks.addFilter('better_messages_emoji_important', 'my_plugin', function() {
    return false; // Remove !important from emoji styles
});
```

---

### `better_messages_no_sleep_enable` {#better_messages_no_sleep_enable}

Controls whether screen lock prevention activates during calls.

**Parameters:**
- `enable` *(boolean)* — Default `true`

**Returns:** `boolean`

---

### `better_messages_no_sleep_disable` {#better_messages_no_sleep_disable}

Controls whether screen lock prevention deactivates after calls.

**Parameters:**
- `disable` *(boolean)* — Default `true`

**Returns:** `boolean`

---

## Better Messages JavaScript Functions Reference — BetterMessages API

# JavaScript Functions Reference

:::info REQUIREMENTS

All functions are available via the global `BetterMessages` object. Add your code to a custom JavaScript file enqueued after Better Messages, or use inline `<script>` tags.

:::

This page lists all public JavaScript functions available in the Better Messages plugin. Use these to programmatically control the messaging UI.

---

## Initialization

### `BetterMessages.initialize()` {#initialize}

Initializes all Better Messages related elements on the page that were not initialized before. Useful for dynamic elements added after page load.

**Returns:** `true`

```js
// After dynamically adding messaging elements to the page
BetterMessages.initialize();
```

---

## Conversations

### `BetterMessages.openChatWithUser( userId )` {#openChatWithUser}

Opens a private conversation with the specified user. If a conversation already exists, it opens it; otherwise creates a new one.

**Parameters:**
- `userId` *(number)* — User ID to open conversation with

```js
var user_id = 3;
BetterMessages.openChatWithUser( user_id );
```

---

### `BetterMessages.openUniqueConversation( key )` {#openUniqueConversation}

Opens or creates a conversation identified by a unique key. For guests, triggers guest authentication first. Opens the conversation in a mini chat.

**Parameters:**
- `key` *(string)* — Unique conversation identifier

```js
BetterMessages.openUniqueConversation( 'order-123-support' );
```

---

## Full Screen

### `BetterMessages.openFullScreen()` {#openFullScreen}

Immediately opens the full-screen user inbox. On mobile-enabled sites, opens the mobile view instead.

```js
BetterMessages.openFullScreen();
```

---

## Mini Chats

### `BetterMessages.miniChatOpen( threadId, open )` {#miniChatOpen}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Opens a mini chat widget for the specified thread. Mini chats are small floating chat windows fixed to the bottom of the screen. The `open` parameter controls whether the chat window starts expanded or minimized.

**Parameters:**
- `threadId` *(number)* — Conversation ID to open
- `open` *(boolean, optional)* — Whether to expand the chat window. Default `true`

```js
var thread_id = 10;
var open = true;
BetterMessages.miniChatOpen( thread_id, open );
```

---

### `BetterMessages.miniChatClose( threadId )` {#miniChatClose}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Closes the mini chat widget for the specified thread and removes it from the screen. The thread remains accessible — it can be reopened at any time.

**Parameters:**
- `threadId` *(number)* — Conversation ID to close

```js
var thread_id = 10;
BetterMessages.miniChatClose( thread_id );
```

---

### `BetterMessages.openNewConversationWidget()` {#openNewConversationWidget}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

When mini chats are active — opens a mini widget to create a new conversation. If mini chats are not active — redirects to the new conversation screen at the messages page.

```js
BetterMessages.openNewConversationWidget();
```

---

## Online Users

### `BetterMessages.getOnlineUsers()` {#getOnlineUsers}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Returns an array of user IDs that are currently online. Only available with WebSocket version — requires an active connection to the presence system. The list updates in real-time as users connect and disconnect.

**Returns:** `array` — Array of online user IDs

```js
var onlineUsers = BetterMessages.getOnlineUsers();
console.log( 'Online users:', onlineUsers );
```

---

## Call Status

### `BetterMessages.isInCall()` {#isInCall}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Returns whether the current user is currently in an active voice or video call. Useful for preventing conflicting actions or showing call status indicators in custom UI elements.

**Returns:** `boolean`

```js
if ( BetterMessages.isInCall() ) {
    console.log( 'User is in a call' );
}
```

---

## Group Calls

### `BetterMessages.getGroupCallParticipants( threadId )` {#getGroupCallParticipants}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Returns how many people are in a conversation's group call right now. The answer comes over the WebSocket connection the page already holds, so it costs your own server nothing — no WordPress request, no database read. This is the right way to show a live "3 people in the room" count beside a Join button.

Group video and group audio are separate rooms, so both counts come back and a conversation can have people in each at the same time.

**Parameters:**
- `threadId` *(number | number[])* — a conversation ID, or an array of them

**Returns:** `Promise` — `{ video, audio }` for a single ID, or an object keyed by conversation ID when you pass an array

```js
const counts = await BetterMessages.getGroupCallParticipants( 123 );

document.querySelector( '#room-123-count' ).textContent = counts.video;
```

Pass an array to price a whole directory of rooms in one round trip:

```js
const rooms = await BetterMessages.getGroupCallParticipants( [ 123, 124, 125 ] );

Object.entries( rooms ).forEach( ( [ threadId, counts ] ) => {
    console.log( threadId, counts.video, counts.audio );
} );
```

To keep a number on screen current, subscribe to [`better_messages_group_call_status`](/hooks/js-actions/#better_messages_group_call_status) rather than calling this on a timer — the server pushes when the count changes.

Both counts are `0` when no call is running, and when the page has no WebSocket connection — which is the case for a visitor who is neither logged in nor registered through guest chat.

---

### `BetterMessages.subscribeGroupCallStatus( threadId )` {#subscribeGroupCallStatus}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Watches one or more conversations and receives their participant counts as they change, through [`better_messages_group_call_status`](/hooks/js-actions/#better_messages_group_call_status). Use this for a room the visitor has not joined — a public page advertising a chat room, or a directory listing a room and its overflow room.

The call server pushes on change, so nothing polls and your own server is never involved.

**Parameters:**
- `threadId` *(number | number[])* — a conversation ID, or an array of them

**Returns:** `Promise<boolean>` — `true` once the subscription is live

```js
await BetterMessages.subscribeGroupCallStatus( [ 123, 124 ] );

wp.hooks.addAction( 'better_messages_group_call_status', 'my_plugin', function( threadId, counts ) {
    document.querySelector( '#room-' + threadId + '-count' ).textContent = counts.video;
} );
```

Subscribing also delivers the current counts straight away, so a page does not need a separate read to paint its first value, and a client that was offline heals by subscribing again.

:::info Requires a chat connection
Counts travel over the visitor's own chat connection, which exists for a logged-in member and for a visitor already registered through guest chat. A visitor who is neither has no connection, so this resolves `false` and the counts read as `0`. On a fully public page, make sure guest chat is enabled if anonymous visitors need to see the number.
:::

---

### `BetterMessages.unsubscribeGroupCallStatus( threadId )` {#unsubscribeGroupCallStatus}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Stops watching one or more conversations. Call it when the element showing the count is removed from the page.

**Parameters:**
- `threadId` *(number | number[])* — a conversation ID, or an array of them

```js
BetterMessages.unsubscribeGroupCallStatus( 123 );
```

### `BetterMessages.openGroupCall( threadId, type )` {#openGroupCall}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Takes the member straight into one conversation's group call from anywhere on the site. The conversation opens full screen and the call is joined for them, so a "Join Room" button on an ordinary page needs no messenger on that page at all. Pair it with [`subscribeGroupCallStatus`](#subscribeGroupCallStatus) to send people to whichever room has space.

Whoever arrives first opens the call and everyone after joins it. When a room is set to let only moderators start a call, a member still joins a call that is already running.

**Parameters:**
- `threadId` *(number)* — the conversation ID
- `type` *(string, optional)* — `'video'` (default) or `'audio'`

**Returns:** `Promise<boolean>` — `true` once the call has been joined

```js
document.querySelector( '#join-crafting-room' ).addEventListener( 'click', async function () {
    await BetterMessages.openGroupCall( 123 );
} );
```

The conversation opens either way. The promise resolves `false` when the call itself could not be joined — group calls switched off for that room, or a member without permission — leaving them in the room, where they can still read and write.

---

---

## WebSocket

### `BetterMessages.getSocket()` {#getSocket}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Returns the raw socket.io client instance for advanced integrations. Use this to listen to custom socket events, emit custom data, or check connection state. Returns null if WebSocket is not connected.

**Returns:** `Socket|null`

```js
var socket = BetterMessages.getSocket();
if ( socket ) {
    console.log( 'Socket connected:', socket.connected );
}
```

---

## API Access

### `BetterMessages.getApi()` {#getApi}

Returns the internal API instance for making direct REST API calls to Better Messages endpoints. The promise waits for the client-side database to be fully initialized before resolving, ensuring all dependencies are ready.

**Returns:** `Promise<object>` — The API instance

```js
var api = await BetterMessages.getApi();
// Use api to make custom API calls
```

---

## Thread Management

### `BetterMessages.updateThreadsLists()` {#updateThreadsLists}

Forces a refresh of the threads list in the UI by triggering the threads list update observable. Use this after programmatically modifying threads (creating, deleting, or updating) to ensure the UI reflects the changes.

```js
// After programmatically modifying threads
BetterMessages.updateThreadsLists();
```

---

### `BetterMessages.resetMainVisibleThread()` {#resetMainVisibleThread}

Resets the currently visible thread on the main screen, returning the user to the threads list view. Dispatches a `better-messages-main-screen-change` custom DOM event. Useful for programmatic navigation when you need to close the current conversation.

```js
BetterMessages.resetMainVisibleThread();
```

---

## Settings Storage

### `BetterMessages.getDbSetting( key, standard )` {#getDbSetting}

Retrieves a setting value from the client-side IndexedDB/SQLite database. Returns the `standard` default value if the setting hasn't been stored yet. Settings persist across page reloads and browser sessions.

**Parameters:**
- `key` *(string)* — Setting key
- `standard` *(any, optional)* — Default value if setting is not found

**Returns:** `Promise<any>`

```js
var value = await BetterMessages.getDbSetting( 'my_custom_setting', 'default' );
```

---

### `BetterMessages.updateSetting( key, value )` {#updateSetting}

Stores a setting value in the client-side IndexedDB/SQLite database. The value persists across page reloads and browser sessions. Use this for custom user preferences that should survive page navigation.

**Parameters:**
- `key` *(string)* — Setting key
- `value` *(any)* — Value to store

**Returns:** `Promise`

```js
await BetterMessages.updateSetting( 'my_custom_setting', 'new_value' );
```

---

### `BetterMessages.deleteSetting( key )` {#deleteSetting}

Removes a setting from the client-side IndexedDB/SQLite database permanently. After deletion, `getDbSetting()` for this key will return the default value.

**Parameters:**
- `key` *(string)* — Setting key to remove

**Returns:** `Promise`

```js
await BetterMessages.deleteSetting( 'my_custom_setting' );
```

---

## Sounds

### `BetterMessages.playMessageSound()` {#playMessageSound}

Plays the messenger's sound of a new message, for a plugin that shows messages of its own, in a navigation tab of its own say. 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. See [Play the sound of a new message](/docs/development/guides/custom-tabs/#play-the-sound-of-a-new-message). Since 3.2.0.

**Returns:** `Promise<boolean>` — whether the sound played

```js
BetterMessages.playMessageSound().then(function(played) {
    if (!played) showMyOwnNotice();
});
```

---

## Utility

### `BetterMessages.parseHash()` {#parseHash}

Parses URL hash variables to handle deep links and navigation parameters. Call this after programmatically changing the URL hash to trigger Better Messages navigation logic (e.g., opening a specific thread or view).

```js
// After programmatically changing the URL hash
BetterMessages.parseHash();
```

---

## Better Messages PHP Actions Reference — WordPress do_action Hooks

# PHP Actions Reference

:::info REQUIREMENTS

To be able to implement this guide, you need to learn how to insert PHP snippets to your website.

You can find guide here: [WP Beginner](https://www.wpbeginner.com/beginners-guide/beginners-guide-to-pasting-snippets-from-the-web-into-wordpress/)

:::

This page lists all PHP action hooks available in the Better Messages plugin. Actions allow you to execute custom code when specific events occur (messages sent, threads created, users joining, etc.).

---

## Messages

### `better_messages_message_sent` {#better_messages_message_sent}

Fires when a new message is sent successfully. The message object is already saved to the database at this point and contains all properties including sender ID, recipients, thread ID, content, and timestamps. Use this hook to trigger external notifications, log messages to analytics, sync with CRM systems, or perform any post-send processing.

**Parameters:**
- `$message` *(BM_Messages_Message)* — The message object (passed by reference)

```php
add_action( 'better_messages_message_sent', 'on_message_sent', 10, 1 );
function on_message_sent( $message ){
    $user_id   = (int) $message->sender_id;    // Sender User ID
    $recipients = (array) $message->recipients; // Recipients User IDs
    $thread_id = $message->thread_id;           // Conversation ID
    $message_id = $message->id;                 // Message ID
    $content   = $message->message;             // Message content
}
```

---

### `better_messages_before_message_send` {#better_messages_before_message_send}

Allows preventing message sending based on custom conditions. This action only prevents new replies — to restrict new conversations use [`better_messages_before_new_thread`](#better_messages_before_new_thread).

**Parameters (by reference):**
- `&$args` *(array)* — Message arguments (`sender_id`, `content`, `thread_id`)
- `&$errors` *(array)* — Error array. Add entries to prevent sending.

```php
add_action( 'better_messages_before_message_send', 'custom_before_message_send', 20, 2 );
function custom_before_message_send( &$args, &$errors ){
    $sender_id = isset($args['sender_id']) ? $args['sender_id'] : get_current_user_id();
    $content   = $args['content'];
    $thread_id = $args['thread_id'];

    $user_allowed_to_send = true; // Your custom logic

    if( ! $user_allowed_to_send ){
        $errors['my_custom_error'] = 'You are not allowed to send this message';
    }
}
```

![Error popup example](./img/before_message_send.png)

---

### `better_messages_message_reply` {#better_messages_message_reply}

Fires when a message is sent as a reply to another message. Only triggers for non-pending messages that have a `reply_to` meta value.

**Parameters:**
- `$message` *(object)* — The new reply message object
- `$replied_to_message` *(object)* — The original message being replied to

```php
add_action( 'better_messages_message_reply', 'on_message_reply', 10, 2 );
function on_message_reply( $message, $replied_to_message ){
    $reply_id     = $message->id;
    $original_id  = $replied_to_message->id;
    $thread_id    = $message->thread_id;
    $replier_id   = $message->sender_id;
    $original_sender = $replied_to_message->sender_id;

    // Example: notify the original sender that someone replied
}
```

---

### `better_messages_before_message_delete` {#better_messages_before_message_delete}

Fires immediately before a message is deleted from the database. Use this to clean up associated data before removal.

**Parameters:**
- `$message_id` *(int)* — The message ID being deleted
- `$thread_id` *(int|false)* — The thread ID, or `false` if unknown
- `$deleteMethod` *(string)* — `'delete'` (hard delete) or `'softdelete'` (soft delete)

```php
add_action( 'better_messages_before_message_delete', 'before_message_delete', 10, 3 );
function before_message_delete( $message_id, $thread_id, $deleteMethod ){
    if( $deleteMethod === 'delete' ){
        // Clean up custom data associated with this message
        delete_metadata( 'message', $message_id, 'my_custom_meta' );
    }
}
```

---

### `bp_better_messages_message_deleted` {#bp_better_messages_message_deleted}

Fires after a message has been completely deleted from the database. Unlike `better_messages_before_message_delete`, this fires after all cleanup is complete.

**Parameters:**
- `$message_id` *(int)* — The deleted message ID

```php
add_action( 'bp_better_messages_message_deleted', 'after_message_deleted', 10, 1 );
function after_message_deleted( $message_id ){
    // Log deletion or update external systems
    error_log( 'Message #' . $message_id . ' was deleted' );
}
```

---

### `better_messages_message_meta_updated` {#better_messages_message_meta_updated}

Fires when message metadata is updated (reactions, voice transcriptions, AI data, etc.). Used internally to broadcast metadata changes via WebSocket so participants see updates in real-time.

**Parameters:**
- `$thread_id` *(int)* — The thread ID containing the message
- `$message_id` *(int)* — The message ID whose meta was updated
- `$meta_key` *(string)* — The meta key (e.g., `'bm_reactions'`, `'bm_voice_transcription'`)
- `$meta_value` *(mixed)* — The new meta value

```php
add_action( 'better_messages_message_meta_updated', 'on_message_meta_updated', 10, 4 );
function on_message_meta_updated( $thread_id, $message_id, $meta_key, $meta_value ){
    if( $meta_key === 'bm_reactions' ){
        // Custom logic when reactions are updated
    }
}
```

---

### `better_messages_message_reported` {#better_messages_message_reported}

Fires when a user reports a message for moderator review. The `$reports` array contains all reports filed against this message (keyed by user ID), allowing you to check the total report count. Use this hook to send admin notifications, integrate with external moderation tools, or trigger automated actions like auto-hiding messages after a threshold of reports.

**Parameters:**
- `$message_id` *(int)* — The reported message ID
- `$thread_id` *(int)* — The thread ID
- `$user_id` *(int)* — The user who filed the report
- `$category` *(string)* — Report category
- `$description` *(string)* — Report description from user
- `$reports` *(array)* — All reports on this message (keyed by user ID)

```php
add_action( 'better_messages_message_reported', 'on_message_reported', 10, 6 );
function on_message_reported( $message_id, $thread_id, $user_id, $category, $description, $reports ){
    // Send notification to admin
    wp_mail( get_option('admin_email'), 'Message Reported',
        sprintf( 'Message #%d reported by user #%d. Category: %s', $message_id, $user_id, $category )
    );
}
```

---

### `better_messages_on_message_not_sent` {#better_messages_on_message_not_sent}

Fires when a message fails to send due to validation errors, permission issues, or authentication failures.

**Parameters:**
- `$thread_id` *(int)* — The thread ID where the message was intended
- `$temp_id` *(string)* — Temporary message ID from the frontend
- `$errors` *(array)* — Array of error messages preventing delivery

```php
add_action( 'better_messages_on_message_not_sent', 'on_message_failed', 10, 3 );
function on_message_failed( $thread_id, $temp_id, $errors ){
    error_log( sprintf( 'Message failed in thread #%d: %s', $thread_id, implode(', ', $errors) ) );
}
```

---

## Threads

### `better_messages_before_new_thread` {#better_messages_before_new_thread}

Allows preventing new conversation creation based on custom conditions.

**Parameters (by reference):**
- `&$args` *(array)* — Thread arguments including `recipients` array
- `&$errors` *(array)* — Error array. Add entries to prevent creation.

```php
add_action( 'better_messages_before_new_thread', 'restrict_new_thread', 10, 2 );
function restrict_new_thread( &$args, &$errors ){
    $user_id    = Better_Messages()->functions->get_current_user_id();
    $recipients = $args['recipients'];

    $can_create = true; // Your custom logic

    if( ! $can_create ){
        $errors['custom_error'] = 'You cannot start new conversations at this time.';
    }
}
```

![Error message example](./img/before_new_thread.png)

---

### `bp_better_messages_new_thread_created` {#bp_better_messages_new_thread_created}

Fires after a new conversation thread is successfully created. When created via the REST API, the first message has already been sent and E2E encryption processing is complete. The `$message_id` is `null` when the thread is created programmatically via batch operations without an initial message. Use this hook to log new conversations, notify moderators, or initialize thread-specific data.

**Parameters:**
- `$thread_id` *(int)* — The newly created thread ID
- `$message_id` *(int|null)* — The first message ID, or `null` when created via batch

```php
add_action( 'bp_better_messages_new_thread_created', 'on_thread_created', 10, 2 );
function on_thread_created( $thread_id, $message_id ){
    // Log new conversation
    error_log( sprintf( 'New thread #%d created with message #%s', $thread_id, $message_id ?? 'none' ) );
}
```

---

### `better_messages_thread_updated` {#better_messages_thread_updated}

Generic thread update hook. Fires when thread state changes — metadata changes, messages deleted, participants added/removed, thread cleared, etc. Used internally to trigger WebSocket broadcasts.

**Parameters:**
- `$thread_id` *(int)* — The updated thread ID

```php
add_action( 'better_messages_thread_updated', 'on_thread_updated', 10, 1 );
function on_thread_updated( $thread_id ){
    // Invalidate external cache for this thread
}
```

---

### `better_messages_info_changed` {#better_messages_info_changed}

Fires when thread display info changes (subject, avatar, participant list, settings like `allow_invite`). Triggers UI refresh for participants.

**Parameters:**
- `$thread_id` *(int)* — The thread ID
- `$user_ids` *(array, optional)* — Specific user IDs affected by the change

```php
add_action( 'better_messages_info_changed', 'on_info_changed', 10, 2 );
function on_info_changed( $thread_id, $user_ids = array() ){
    // React to thread info changes
}
```

---

### `better_messages_thread_self_update` {#better_messages_thread_self_update}

Fires when user-specific thread data is updated (e.g., last_update timestamp). Different from `better_messages_thread_updated` which is global — this is per-user.

**Parameters:**
- `$thread_id` *(int)* — The thread ID
- `$user_id` *(int)* — The user whose thread state was updated

```php
add_action( 'better_messages_thread_self_update', 'on_thread_self_update', 10, 2 );
function on_thread_self_update( $thread_id, $user_id ){
    // Handle per-user thread state change
}
```

---

### `better_messages_change_thread_meta` {#better_messages_change_thread_meta}

Fires when thread metadata is changed via the REST API (excludes `allow_invite` which is handled separately).

**Parameters:**
- `$thread_id` *(int)* — The thread ID
- `$key` *(string)* — The metadata key being changed
- `$value` *(mixed)* — The new value

```php
add_action( 'better_messages_change_thread_meta', 'on_thread_meta_change', 10, 3 );
function on_thread_meta_change( $thread_id, $key, $value ){
    // React to specific meta changes
    if( $key === 'my_custom_setting' ){
        // Handle custom thread setting
    }
}
```

---

### `better_messages_thread_cleared` {#better_messages_thread_cleared}

Fires when all messages in a thread are deleted (cleared). Messages are hard-deleted and unread counters reset.

**Parameters:**
- `$thread_id` *(int)* — The cleared thread ID

```php
add_action( 'better_messages_thread_cleared', 'on_thread_cleared', 10, 1 );
function on_thread_cleared( $thread_id ){
    // Clean up search indexes, archives, etc.
}
```

---

### `better_messages_thread_erased` {#better_messages_thread_erased}

Fires after an entire thread is completely deleted (all messages, metadata, and participant records removed).

**Parameters:**
- `$thread_id` *(int)* — The erased thread ID

```php
add_action( 'better_messages_thread_erased', 'on_thread_erased', 10, 1 );
function on_thread_erased( $thread_id ){
    // Remove external references to this thread
}
```

---

### `better_messages_mark_thread_read` {#better_messages_mark_thread_read}

Fires after a specific thread is marked as read by a user.

**Parameters:**
- `$thread_id` *(int)* — The thread marked as read
- `$user_id` *(int)* — The user who marked it read

```php
add_action( 'better_messages_mark_thread_read', 'on_thread_read', 10, 2 );
function on_thread_read( $thread_id, $user_id ){
    // Update notification badges in external system
}
```

---

### `better_messages_thread_marked_unread` {#better_messages_thread_marked_unread}

Fires after a user marks a conversation as unread again ([Mark as unread](/docs/features/mark-as-unread/)). The `unread_count` of the user for the conversation is `-1` by then. It counts in no unread total, and opening the conversation or a new message in it ends it. Since 3.2.0.

**Parameters:**
- `$thread_id` *(int)* — The conversation marked as unread
- `$user_id` *(int)* — The user who marked it, negative for a guest

```php
add_action( 'better_messages_thread_marked_unread', 'on_thread_marked_unread', 10, 2 );
function on_thread_marked_unread( $thread_id, $user_id ){
    // Keep a reminder in an external task list
}
```

---

### `better_messages_mark_all_read` {#better_messages_mark_all_read}

Fires when a user marks all conversations as read at once.

**Parameters:**
- `$user_id` *(int)* — The user ID

```php
add_action( 'better_messages_mark_all_read', 'on_all_read', 10, 1 );
function on_all_read( $user_id ){
    // Clear all notification badges for this user
}
```

---

## Participants

### `better_messages_participant_added` {#better_messages_participant_added}

Fires when a single user is added to a thread via `add_participant_to_thread()`. The database insert has already succeeded at this point. Use this hook to send welcome notifications, initialize per-user thread settings, log membership changes, or sync with external group systems.

**Parameters:**
- `$thread_id` *(int)* — The thread ID
- `$user_id` *(int)* — The added user's ID

```php
add_action( 'better_messages_participant_added', 'on_participant_added', 10, 2 );
function on_participant_added( $thread_id, $user_id ){
    // Send welcome notification to new participant
}
```

---

### `better_messages_participant_removed` {#better_messages_participant_removed}

Fires when a single user is removed from a thread via `remove_participant_from_thread()`. The database delete has already succeeded at this point. Use this hook to clean up user-specific thread data, revoke access in external systems, or send departure notifications.

**Parameters:**
- `$thread_id` *(int)* — The thread ID
- `$user_id` *(int)* — The removed user's ID

```php
add_action( 'better_messages_participant_removed', 'on_participant_removed', 10, 2 );
function on_participant_removed( $thread_id, $user_id ){
    // Clean up user-specific thread data
}
```

---

### `better_messages_participants_added` {#better_messages_participants_added}

Fires when multiple users are bulk-added to a thread (e.g., via BuddyPress/PeepSo/Ultimate Member group sync).

**Parameters:**
- `$thread_id` *(int)* — The thread ID
- `$user_ids` *(array)* — Array of added user IDs

```php
add_action( 'better_messages_participants_added', 'on_participants_added', 10, 2 );
function on_participants_added( $thread_id, $user_ids ){
    foreach( $user_ids as $user_id ){
        // Initialize per-user settings for the thread
    }
}
```

---

### `better_messages_participants_removed` {#better_messages_participants_removed}

Fires when multiple users are bulk-removed from a thread, typically during BuddyPress/PeepSo/Ultimate Member/Fluent Community group membership syncs. Use this hook for batch cleanup operations, updating member statistics, or notifying remaining participants.

**Parameters:**
- `$thread_id` *(int)* — The thread ID
- `$removed_ids` *(array)* — Array of removed user IDs

```php
add_action( 'better_messages_participants_removed', 'on_participants_removed', 10, 2 );
function on_participants_removed( $thread_id, $removed_ids ){
    // Batch cleanup for removed users
}
```

---

## Real-time Access

### `better_messages_revoke_user` {#better_messages_revoke_user}

An action you call, not one you listen to. It cuts a user off the WebSocket server at once: every session of the user is closed on every server, so a browser or app that is already open stops receiving messages, and new connections are refused until you call [`better_messages_restore_user`](#better_messages_restore_user). Use it when your own rules make a member ineligible, such as a suspension. WebSocket version, 3.0.13 or newer.

**Parameters:**
- `$user_id` *(int)* — The user (negative for guests)

```php
// The member is suspended
do_action( 'better_messages_revoke_user', $user_id );
```

See [Revoke a user's access](/docs/development/guides/revoke-user-access/).

---

### `better_messages_restore_user` {#better_messages_restore_user}

An action you call: it lets a user revoked with [`better_messages_revoke_user`](#better_messages_revoke_user) connect again. Their next page load connects as usual. WebSocket version, 3.0.13 or newer.

**Parameters:**
- `$user_id` *(int)* — The user (negative for guests)

```php
// The member is reinstated
do_action( 'better_messages_restore_user', $user_id );
```

---

### `better_messages_user_unrestricted` {#better_messages_user_unrestricted}

Fires when a mute or ban on a user in a conversation or chat room ends — lifted by a moderator or expired.

Since 3.2.0 it also fires when a ban from the conversation's group calls ends, the ban of [Remove and Ban from Calls](/docs/websocket/group-video-chat/#remove-and-ban-from-calls), lifted with **Lift call ban** or expired. `$type` is then `call_ban`.

**Parameters:**
- `$thread_id` *(int)* — The conversation
- `$user_id` *(int)* — The user, negative for a guest
- `$type` *(string)* — `ban`, `mute` or `call_ban`

```php
add_action( 'better_messages_user_unrestricted', 'on_user_unrestricted', 10, 3 );
function on_user_unrestricted( $thread_id, $user_id, $type ){
    if( $type === 'ban' ){
        // The user may use the conversation again
    }
}
```

---

## Chat Rooms

### `better_messages_after_chat_join` {#better_messages_after_chat_join}

Fires after a user successfully joins a public/semi-public chat room.

**Parameters:**
- `$thread_id` *(int)* — The message thread ID
- `$chat_id` *(int)* — The chat room post ID (`bpbm-chat` post type)

```php
add_action( 'better_messages_after_chat_join', 'on_chat_join', 10, 2 );
function on_chat_join( $thread_id, $chat_id ){
    $user_id = get_current_user_id();
    // Send welcome message, log join event, etc.
}
```

---

### `better_messages_after_chat_left` {#better_messages_after_chat_left}

Fires after a user leaves a chat room and is removed from the recipients list. The thread cache has been cleared before this hook fires. Use this hook to log departure events, update member counts, or clean up user-specific chat room data.

**Parameters:**
- `$thread_id` *(int)* — The message thread ID
- `$chat_id` *(int)* — The chat room post ID

```php
add_action( 'better_messages_after_chat_left', 'on_chat_left', 10, 2 );
function on_chat_left( $thread_id, $chat_id ){
    $user_id = get_current_user_id();
    // Log departure, update member counts
}
```

---

## Calls

### `better_messages_call_created` {#better_messages_call_created}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Fires when a user initiates a private call. This does not mean the call was answered — only that the call initiation started.

**Parameters:**
- `$message_id` *(int)* — The call message ID
- `$thread_id` *(int)* — The thread ID
- `$user_id` *(int)* — The user who initiated the call
- `$type` *(string)* — `'audio'` or `'video'`

```php
add_action( 'better_messages_call_created', 'on_call_created', 10, 4 );
function on_call_created( $message_id, $thread_id, $user_id, $type ){
    // Log call initiation
    error_log( sprintf( 'User #%d started %s call in thread #%d', $user_id, $type, $thread_id ) );
}
```

---

### `better_messages_group_call_joined` {#better_messages_group_call_joined}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Fires when a user joins a group call, after receiving the room token from the cloud server. The `$is_started` parameter indicates whether this user is creating a new call room or joining an existing one. Use this hook to track group call participation, enforce call duration limits, or log analytics.

**Parameters:**
- `$thread_id` *(int)* — The group thread ID
- `$type` *(string)* — `'audio'` or `'video'`
- `$user_id` *(int)* — The user who joined
- `$is_started` *(bool)* — `true` if the user is starting a new call, `false` if joining an existing one

```php
add_action( 'better_messages_group_call_joined', 'on_group_call_joined', 10, 4 );
function on_group_call_joined( $thread_id, $type, $user_id, $is_started ){
    if( $is_started ){
        // New group call started
    } else {
        // User joined existing call
    }
}
```

**Notify the group when a call starts.** The "started a group call" notice in the conversation is a [system message](/docs/features/system-messages/), and system messages never play a sound, send a push or send an email. To alert members who aren't looking at the conversation, send a normal message in the caller's name when the first person starts the call. A normal message goes through all the usual notifications (sounds and popups for members online, push notifications and email for the rest):

```php
add_action( 'better_messages_group_call_joined', function( $thread_id, $type, $user_id, $is_started ){
    if( ! $is_started ) return; // only the person who starts the call

    Better_Messages()->functions->new_message( array(
        'sender_id'       => $user_id,
        'thread_id'       => $thread_id,
        'content'         => $type === 'video' ? 'I started a video call. Join me!' : 'I started an audio call. Join me!',
        'skip_moderation' => true,
    ) );
}, 10, 4 );
```

---

### `better_messages_register_call_usage` {#better_messages_register_call_usage}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Fires during call lifecycle — when a call is accepted and when it ends. Use for tracking call duration and usage.

**Parameters:**
- `$message_id` *(int)* — The call message ID
- `$thread_id` *(int)* — The thread ID
- `$user_id` *(int)* — The user accepting/ending the call

```php
add_action( 'better_messages_register_call_usage', 'track_call_usage', 10, 3 );
function track_call_usage( $message_id, $thread_id, $user_id ){
    // Track call usage for billing or analytics
}
```

---

## Guests

### `better_messages_guest_registered` {#better_messages_guest_registered}

Fires when a new guest (non-WordPress user) successfully registers. The guest has been inserted into the database with a unique secret token, display name, and email. Use this hook to send welcome emails, initialize guest preferences, log signups for analytics, or trigger CRM integrations.

**Parameters:**
- `$guest_id` *(int)* — The guest ID from the plugin's guests table

```php
add_action( 'better_messages_guest_registered', 'on_guest_registered', 10, 1 );
function on_guest_registered( $guest_id ){
    // Send welcome email, initialize preferences, log signup
}
```

---

### `better_messages_guest_updated` {#better_messages_guest_updated}

Fires when a guest's profile is updated (name, email, etc.). The WebSocket profile has already been rebuilt at this point, so real-time connections reflect the new data. Note that the user ID is a negative integer for guests. Use this hook to sync profile changes to external services or update cached data.

**Parameters:**
- `$user_id` *(int)* — Negative integer representing the guest (e.g., `-5` for guest ID `5`)

```php
add_action( 'better_messages_guest_updated', 'on_guest_updated', 10, 1 );
function on_guest_updated( $user_id ){
    // Sync guest profile changes to external system
}
```

---

### `better_messages_guest_deleted` {#better_messages_guest_deleted}

Fires after a guest is deleted from the guests table and removed from all conversation threads. All cleanup is complete at this point. Use this hook for final data removal, compliance logging, or notifying threads about the guest's departure.

**Parameters:**
- `$user_id` *(int)* — The guest user ID

```php
add_action( 'better_messages_guest_deleted', 'on_guest_deleted', 10, 1 );
function on_guest_deleted( $user_id ){
    // Final cleanup for guest data
}
```

---

### `better_messages_user_updated` {#better_messages_user_updated}

Generic hook that fires when any user (guest) profile changes or is deleted. Fires alongside `better_messages_guest_updated` and `better_messages_guest_deleted`.

**Parameters:**
- `$user_id` *(int)* — The user ID (negative for guests)

```php
add_action( 'better_messages_user_updated', 'on_user_updated', 10, 1 );
function on_user_updated( $user_id ){
    // Invalidate user cache
    wp_cache_delete( 'bm_user_' . $user_id );
}
```

---

## Notifications

### `better_messages_send_pushs` {#better_messages_send_pushs}

Fires when push notifications are being sent to users. Allows integration with third-party push services.

**Parameters:**
- `$user_ids` *(array)* — Array of user IDs receiving push notifications
- `$notification` *(array)* — Notification data (title, body, icon, tag, URL, etc.)
- `$message` *(object, optional)* — The message object that triggered the notification
- `$all_recipients` *(array, optional)* — All thread recipients

```php
add_action( 'better_messages_send_pushs', 'custom_push_handler', 10, 4 );
function custom_push_handler( $user_ids, $notification, $message = null, $all_recipients = array() ){
    // Send push via Firebase, OneSignal, etc.
    foreach( $user_ids as $user_id ){
        // my_push_service_send( $user_id, $notification['title'], $notification['body'] );
    }
}
```

---

### `better_messages_send_unread_notification` {#better_messages_send_unread_notification}

Fires during the email notification cron job, after recording the last email time for a user in a thread.

**Parameters:**
- `$user_id` *(int)* — The user receiving the notification
- `$thread_id` *(int)* — The thread with unread messages

```php
add_action( 'better_messages_send_unread_notification', 'custom_unread_notification', 10, 2 );
function custom_unread_notification( $user_id, $thread_id ){
    // Send SMS, Slack message, or custom notification
}
```

---

### `better_messages_set_user_thread_unread_count` {#better_messages_set_user_thread_unread_count}

Fires after updating a user's unread message count for a specific thread in the database. The count is always >= 0 and fires before the thread is marked as updated for the user. Use this hook to sync unread counts to external badge systems, mobile push badge numbers, or custom notification widgets.

**Parameters:**
- `$user_id` *(int)* — The user ID
- `$thread_id` *(int)* — The thread ID
- `$unread_count` *(int)* — The new unread count

```php
add_action( 'better_messages_set_user_thread_unread_count', 'on_unread_count_changed', 10, 3 );
function on_unread_count_changed( $user_id, $thread_id, $unread_count ){
    // Sync unread count to external badge system
}
```

---

### `better_messages_user_emails_enabled_update` {#better_messages_user_emails_enabled_update}

Fires when a user's email notification preference is updated via the settings panel or the unsubscribe link. The preference is stored in user meta. Use this hook to sync email preferences to CRM systems, mailing list providers, or external notification services, or to make emails opt-in (see [`better_messages_is_user_emails_enabled`](/hooks/php-filters#better_messages_is_user_emails_enabled)).

**Parameters:**
- `$user_id` *(int)* — The user ID
- `$enabled` *(string)* — New setting (`'yes'` or `'no'`)

```php
add_action( 'better_messages_user_emails_enabled_update', 'on_email_pref_changed', 10, 2 );
function on_email_pref_changed( $user_id, $enabled ){
    // Sync preference to CRM
}
```

---

## AI

### `better_messages_ai_response_completed` {#better_messages_ai_response_completed}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Fires after an AI bot response has been completed, saved to the database, and cost calculated. The `$cost_data` array structure varies by provider — OpenAI includes `prompt_tokens`, `completion_tokens`, and `cost`. Use this hook to track AI usage per user, deduct credits from a billing system, log interactions for analytics, or send webhooks to external systems.

**Parameters:**
- `$ai_message_id` *(int)* — The AI response message ID
- `$message_id` *(int)* — The user's original message ID
- `$cost_data` *(array)* — Token counts and cost data (structure varies by provider)
- `$bot_id` *(int)* — The AI bot ID
- `$recipient_user_id` *(int)* — The user who received the AI response

```php
add_action( 'better_messages_ai_response_completed', 'on_ai_response', 10, 5 );
function on_ai_response( $ai_message_id, $message_id, $cost_data, $bot_id, $recipient_user_id ){
    // Track AI usage, deduct user credits, log interactions
    $total_tokens = ($cost_data['prompt_tokens'] ?? 0) + ($cost_data['completion_tokens'] ?? 0);
}
```

---

## File Uploads

### `better_messages_post_before_upload` {#better_messages_post_before_upload}

Fires before a file is uploaded to WordPress media library, after file type and size validation has passed. Use this hook to log file uploads for audit purposes, enforce additional validation rules (e.g., virus scanning), or track upload activity per user.

**Parameters:**
- `$upload_meta` *(array)* — Upload metadata (`filename`, `filetype`)

```php
add_action( 'better_messages_post_before_upload', 'before_file_upload', 10, 1 );
function before_file_upload( $upload_meta ){
    // Log upload, enforce additional rules
    error_log( 'Uploading: ' . $upload_meta['filename'] . ' (' . $upload_meta['filetype'] . ')' );
}
```

---

### `better_messages_tus_before_finalize` {#better_messages_tus_before_finalize}

Fires before a TUS (resumable upload protocol) file is finalized and attached to a message. The upload directory path is structured as `{year}/{month}/{thread_id}/{uuid}`. Use this hook for custom file processing, metadata enrichment, or logging before the attachment is created.

**Parameters:**
- `$meta` *(array)* — File metadata including upload path

```php
add_action( 'better_messages_tus_before_finalize', 'before_tus_finalize', 10, 1 );
function before_tus_finalize( $meta ){
    // Custom processing before file attachment
}
```

---

## Plugin Lifecycle

### `better_messages_activation` {#better_messages_activation}

Fires at the end of plugin activation, after all database tables have been created and migrations have been run. Used internally to install BuddyPress email templates and set up database tables. Use this hook to initialize custom options, create data structures, or schedule cron events that depend on Better Messages being active.

**Parameters:** None

```php
add_action( 'better_messages_activation', 'on_bm_activation' );
function on_bm_activation(){
    // Initialize custom options, create data structures
}
```

---

### `better_messages_deactivation` {#better_messages_deactivation}

Fires during plugin deactivation. Used internally to unschedule the `better_messages_send_notifications` cron event. Use this hook to clean up custom cron events, remove temporary data, or deactivate dependent features when Better Messages is turned off.

**Parameters:** None

```php
add_action( 'better_messages_deactivation', 'on_bm_deactivation' );
function on_bm_deactivation(){
    // Unschedule custom cron events, cleanup
    wp_clear_scheduled_hook( 'my_custom_cron' );
}
```

---

### `better_messages_reset_database` {#better_messages_reset_database}

Fires after the database has been completely reset (all tables dropped and recreated). Admin-only action.

**Parameters:** None

```php
add_action( 'better_messages_reset_database', 'on_db_reset' );
function on_db_reset(){
    // Rebuild custom data structures
}
```

---

### `better_messages_register_script_dependencies` {#better_messages_register_script_dependencies}

Fires before registering core script dependencies. Allows registering additional scripts that Better Messages depends on.

**Parameters:** None (or `'mobile-app'` context string when called from mobile app)

```php
add_action( 'better_messages_register_script_dependencies', 'register_custom_deps' );
function register_custom_deps(){
    wp_register_script( 'my-bm-addon', plugins_url( 'my-addon.js', __FILE__ ), array(), '1.0' );
}
```

---

## Mobile App

### `better_messages_mobile_app_auth` {#better_messages_mobile_app_auth}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Fires after a mobile app device is successfully authenticated via JWT token verification. The device is already marked as active and the app scripts hash is prepared at this point. Use this hook to log mobile authentications, update user last-seen timestamps, or trigger device-specific initialization logic.

**Parameters:**
- `$user_id` *(int)* — Authenticated user ID
- `$device` *(array)* — Device info (`device_id`, `user_id`, `device_public_key`, etc.)

```php
add_action( 'better_messages_mobile_app_auth', 'on_mobile_auth', 10, 2 );
function on_mobile_auth( $user_id, $device ){
    // Log mobile authentication, update last-seen
    update_user_meta( $user_id, 'last_mobile_auth', current_time('mysql') );
}
```

---

### `better_messages_mobile_app_web_auth` {#better_messages_mobile_app_web_auth}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Fires when a mobile app user authenticates for web access via OpenSSL signature verification. At this point, the user is already logged into WordPress (current user and auth cookie are set). Use this hook to log web-based mobile authentications or apply web-specific initialization for mobile users.

**Parameters:**
- `$user_id` *(int)* — Authenticated user ID
- `$device` *(array)* — Device info

```php
add_action( 'better_messages_mobile_app_web_auth', 'on_mobile_web_auth', 10, 2 );
function on_mobile_web_auth( $user_id, $device ){
    // Handle web-based mobile app authentication
}
```

---

### `better_messages_mobile_app_login` {#better_messages_mobile_app_login}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Fires after a member signs in to the mobile app, with the password form or through the website, once the device is saved. See [Sign-in and two-factor authentication](/docs/mobile-app/sign-in/). Since 3.2.0.

**Parameters:**
- `$user_id` *(int)* — The member
- `$device` *(array)* — The device the app sends (`id`, `app` and the details of the phone)
- `$method` *(string)* — `password` or `website`

```php
add_action( "better_messages_mobile_app_login", function( $user_id, $device, $method ) {
    update_user_meta( $user_id, "last_app_sign_in", time() );
}, 10, 3 );
```

---

### `better_messages_mobile_app_device_signed_out` {#better_messages_mobile_app_device_signed_out}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Fires for each device signed out of the mobile app, after its row is deleted. See [Signed-in devices](/docs/mobile-app/signed-in-devices/). Since 3.2.0.

**Parameters:**
- `$user_id` *(int)* — The member of the device
- `$device` *(array)* — The deleted row: `id`, `user_id`, `device_id`, `platform`, `environment`, `app_id`, `push_token` and `push_token_voip`
- `$reason` *(string)* — `logout` (the member on the phone itself), `member` (the member from the list of devices), `admin`, `deleted`, `revoked`, `refused` or `password`

---

### `better_messages_mobile_app_account_deleted` {#better_messages_mobile_app_account_deleted}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Fires after a member deleted their account with Delete Account in the mobile app. See [Delete Account](/docs/mobile-app/delete-account/). Since 3.2.0.

**Parameters:**
- `$user_id` *(int)* — The deleted member
- `$user` *(WP_User)* — The member as it was before the deletion

---

### `better_messages_mobile_app_account_deletion_requested` {#better_messages_mobile_app_account_deletion_requested}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Fires after a member sent a request to delete their account from the mobile app, with Send a request to the administrator. The request is already confirmed and the administrator notified. Since 3.2.0.

**Parameters:**
- `$user_id` *(int)* — The member
- `$request_id` *(int)* — The id of the personal data erasure request

---

## Encryption

### `better_messages_e2e_wrap_task` {#better_messages_e2e_wrap_task}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Fires when E2E encryption keys need to be re-wrapped for a user. Delegated to the WebSocket server for execution.

**Parameters:**
- `$pending_threads` *(array)* — Thread IDs needing key re-wrapping
- `$user_id` *(int)* — User who needs key wrapping

```php
add_action( 'better_messages_e2e_wrap_task', 'on_e2e_wrap', 10, 2 );
function on_e2e_wrap( $pending_threads, $user_id ){
    // Monitor E2E key distribution
}
```

---

## Template Rendering

### `bp_better_messages_before_chat` {#bp_better_messages_before_chat}

Fires before rendering a chat widget HTML. Errors are cleared to a global `$bpbm_errors` array and CSS customizations are queued for footer output at this point. Use this hook to inject custom HTML before the chat, add error notices, or perform thread-specific setup.

**Parameters:**
- `$chat_id` *(string)* — Unique chat instance identifier
- `$thread_id` *(int)* — Thread ID

```php
add_action( 'bp_better_messages_before_chat', 'before_chat_render', 10, 2 );
function before_chat_render( $chat_id, $thread_id ){
    // Inject custom HTML or setup before chat renders
}
```

---

### `bp_better_messages_after_chat` {#bp_better_messages_after_chat}

Fires after the chat HTML has been generated and output buffering is complete. The minified HTML is returned after this hook. Use this hook to inject tracking code, add custom JavaScript, or modify the final chat output.

**Parameters:**
- `$chat_id` *(string)* — Unique chat instance identifier
- `$thread_id` *(int)* — Thread ID

```php
add_action( 'bp_better_messages_after_chat', 'after_chat_render', 10, 2 );
function after_chat_render( $chat_id, $thread_id ){
    // Add tracking code or custom modifications
}
```

---

### `bp_better_messages_before_main_template_rendered` {#bp_better_messages_before_main_template_rendered}

Fires before the main messaging template begins rendering.

**Parameters:** None

```php
add_action( 'bp_better_messages_before_main_template_rendered', 'before_main_template' );
function before_main_template(){
    // Output custom HTML at the start of the messaging template
}
```

---

### `bp_better_messages_after_main_template_rendered` {#bp_better_messages_after_main_template_rendered}

Fires after the main messaging template is rendered.

**Parameters:** None

```php
add_action( 'bp_better_messages_after_main_template_rendered', 'after_main_template' );
function after_main_template(){
    // Add modals, debug info, or other markup after the template
}
```

---

### `bp_better_messages_before_generation` {#bp_better_messages_before_generation}

Fires before generating the Ultimate Member group messaging template. Errors are reset and the template loading context is prepared at this point. Use this hook for Ultimate Member-specific initialization or custom error handling for group messaging.

**Parameters:** None

```php
add_action( 'bp_better_messages_before_generation', 'before_um_generation' );
function before_um_generation(){
    // Ultimate Member group-specific initialization
}
```

---

### `bp_better_messages_screen` {#bp_better_messages_screen}

Fires when setting up the BuddyPress messages screen/tab. Earliest hook point for the messages screen.

**Parameters:** None

```php
add_action( 'bp_better_messages_screen', 'on_messages_screen' );
function on_messages_screen(){
    // Register custom tabs or modify screen setup
}
```

---

## Better Messages PHP Filters Reference — WordPress apply_filters Hooks

# PHP Filters Reference

:::info REQUIREMENTS

To be able to implement this guide, you need to learn how to insert PHP snippets to your website.

You can find guide here: [WP Beginner](https://www.wpbeginner.com/beginners-guide/beginners-guide-to-pasting-snippets-from-the-web-into-wordpress/)

:::

This page lists all PHP filter hooks available in the Better Messages plugin. Filters allow you to modify data as it passes through the plugin — changing permissions, content, display, and behavior.

---

## Permissions & Access

### `better_messages_can_send_message` {#better_messages_can_send_message}

Filters whether a user can send a message in a thread. To display a custom error message when blocking, use the global `$bp_better_messages_restrict_send_message` array.

It runs when a member sends a message in an existing conversation or chat room, when the conversation list decides whether to show the reply box, and before an audio or video call starts in a conversation. It does **not** run when a member starts a new conversation, so a rule that should also stop new conversations needs [`better_messages_before_new_thread`](/hooks/php-actions#better_messages_before_new_thread) as well.

**Parameters:**
- `$allowed` *(bool)* — Whether the user is allowed
- `$user_id` *(int)* — User attempting to send
- `$thread_id` *(int)* — The thread ID

**Returns:** `bool`

```php
add_filter( 'better_messages_can_send_message', 'restrict_sending', 10, 3 );
function restrict_sending( $allowed, $user_id, $thread_id ){
    global $bp_better_messages_restrict_send_message;

    $user_allowed_to_send = true; // Your custom logic

    if( ! $user_allowed_to_send ){
        // Add error message shown to user in the reply form area
        $bp_better_messages_restrict_send_message['my_custom_error'] = 'You are not allowed to reply to this thread';
        return false;
    }

    return $allowed;
}
```

![Restricted message example](./img/can_send_message.png)

---

### `better_messages_can_forward_message` {#better_messages_can_forward_message}

Filters whether a user can forward a message. Return `null` to allow, `WP_Error` to deny.

**Parameters:**
- `$error` *(null|WP_Error)* — Default `null`
- `$original_message` *(object)* — The message being forwarded
- `$current_user_id` *(int)* — User forwarding the message

**Returns:** `null|WP_Error`

```php
add_filter( 'better_messages_can_forward_message', 'restrict_forwarding', 10, 3 );
function restrict_forwarding( $error, $message, $user_id ){
    if( ! user_can( $user_id, 'edit_posts' ) ){
        return new WP_Error( 'no_forward', 'Forwarding is not allowed for your role' );
    }
    return $error;
}
```

---

### `better_messages_can_invite` {#better_messages_can_invite}

Filters whether a user can invite others to a thread. The default value is based on the thread's `allow_invite` setting and user permissions. Return `true` to allow inviting, `false` to deny.

**Parameters:**
- `$can_invite` *(bool)* — Default based on thread settings
- `$user_id` *(int)* — User inviting
- `$thread_id` *(int)* — The thread

**Returns:** `bool`

```php
add_filter( 'better_messages_can_invite', 'custom_invite_rules', 10, 3 );
function custom_invite_rules( $can_invite, $user_id, $thread_id ){
    // Only moderators can invite
    if( user_can( $user_id, 'moderate_comments' ) ){
        return true;
    }
    return false;
}
```

---

### `better_messages_can_pin_messages` {#better_messages_can_pin_messages}

Filters whether a user can pin/unpin messages in a thread. Default is `false` — pinning must be explicitly enabled. Only one message can be pinned per thread at a time.

**Parameters:**
- `$can_pin` *(bool)* — Default `false`
- `$user_id` *(int)* — Current user
- `$thread_id` *(int)* — The thread

**Returns:** `bool`

```php
add_filter( 'better_messages_can_pin_messages', 'allow_pinning', 10, 3 );
function allow_pinning( $can_pin, $user_id, $thread_id ){
    return user_can( $user_id, 'edit_posts' );
}
```

---

### `better_messages_chat_user_can_join` {#better_messages_chat_user_can_join}

Filters whether a user can join a chat room. The default is based on the room's role-based `can_join` setting. Receives both the chat room post ID and the associated thread ID for flexible permission logic.

**Parameters:**
- `$has_access` *(bool)* — Default based on user role check
- `$user_id` *(int)* — User attempting to join
- `$chat_id` *(int)* — Chat room post ID
- `$thread_id` *(int)* — Associated thread ID

**Returns:** `bool`

```php
add_filter( 'better_messages_chat_user_can_join', 'custom_chat_access', 10, 4 );
function custom_chat_access( $has_access, $user_id, $chat_id, $thread_id ){
    // Allow all logged-in users
    return is_user_logged_in();
}
```

---

### `better_messages_check_access_override` {#better_messages_check_access_override}

Completely overrides the default access check for a thread. Return `null` to use default logic, or `bool` to override.

**Parameters:**
- `$override` *(null|bool)* — Default `null` (use default checks)
- `$thread_id` *(int)* — The thread
- `$user_id` *(int)* — User checking access
- `$access_type` *(string)* — Type of access (`'read'`, `'reply'`, etc.)

**Returns:** `null|bool`

```php
add_filter( 'better_messages_check_access_override', 'custom_access', 10, 4 );
function custom_access( $override, $thread_id, $user_id, $access_type ){
    // Grant read access to all admins
    if( $access_type === 'read' && user_can( $user_id, 'manage_options' ) ){
        return true;
    }
    return null; // Use default logic
}
```

---

### `better_messages_has_access_to_group_chat` {#better_messages_has_access_to_group_chat}

Filters access to group chat threads (type `'group'`). Default is `false`, meaning group chat access must be explicitly granted. BuddyPress, PeepSo, and other group plugins use this filter to integrate their membership checks.

**Parameters:**
- `$has_access` *(bool)* — Default `false`
- `$thread_id` *(int)* — Group chat thread
- `$user_id` *(int)* — User checking access

**Returns:** `bool`

```php
add_filter( 'better_messages_has_access_to_group_chat', 'group_chat_access', 10, 3 );
function group_chat_access( $has_access, $thread_id, $user_id ){
    // Integrate with custom group system
    $group_id = Better_Messages()->functions->get_thread_meta( $thread_id, 'my_group_id' );
    return my_is_group_member( $group_id, $user_id );
}
```

---

### `better_messages_is_moderation_enabled` {#better_messages_is_moderation_enabled}

Filters whether message moderation (approval queue) is enabled for a user.

**Parameters:**
- `$enabled` *(bool)* — Default based on settings
- `$user_id` *(int)* — The user
- `$thread_id` *(int)* — The thread
- `$is_new_conversation` *(bool)* — Whether this is the first message

**Returns:** `bool`

```php
add_filter( 'better_messages_is_moderation_enabled', 'custom_moderation', 10, 4 );
function custom_moderation( $enabled, $user_id, $thread_id, $is_new_conversation ){
    // Skip moderation for trusted users
    if( user_can( $user_id, 'edit_posts' ) ){
        return false;
    }
    return $enabled;
}
```

---

### `better_messages_guest_register_allowed` {#better_messages_guest_register_allowed}

Filters whether a guest is allowed to register for chat access. The default is based on the `guest_access_enabled` plugin setting. The `$registerData` array contains the submitted form data (name, email) for custom validation logic.

**Parameters:**
- `$allowed` *(bool)* — Default based on `guest_access_enabled` setting
- `$registerData` *(array|null)* — Registration form data

**Returns:** `bool`

```php
add_filter( 'better_messages_guest_register_allowed', 'validate_guest', 10, 2 );
function validate_guest( $allowed, $data ){
    if( $data && isset( $data['email'] ) ){
        // Only allow specific email domains
        if( ! str_ends_with( $data['email'], '@example.com' ) ){
            return false;
        }
    }
    return $allowed;
}
```

---

### `better_messages_rest_is_user_authorized` {#better_messages_rest_is_user_authorized}

Filters REST API authorization for non-logged-in users. Default is `false` — logged-in users always pass automatically. Use this to implement API token authentication, JWT validation, or other custom auth systems for headless/mobile integrations.

**Parameters:**
- `$authorized` *(bool)* — Default `false`
- `$request` *(WP_REST_Request)* — The REST request

**Returns:** `bool`

```php
add_filter( 'better_messages_rest_is_user_authorized', 'api_token_auth', 10, 2 );
function api_token_auth( $authorized, $request ){
    $token = $request->get_header('X-BM-Token');
    if( $token && my_validate_token( $token ) ){
        return true;
    }
    return $authorized;
}
```

---

### `bp_better_messages_can_block_user` {#bp_better_messages_can_block_user}

Filters whether a user can block another user.

**Parameters:**
- `$can_block` *(bool)* — Default based on role/immunity rules
- `$user_id` *(int)* — User attempting to block
- `$blocked_id` *(int)* — User to be blocked

**Returns:** `bool`

```php
add_filter( 'bp_better_messages_can_block_user', 'prevent_blocking_staff', 10, 3 );
function prevent_blocking_staff( $can_block, $user_id, $blocked_id ){
    if( user_can( $blocked_id, 'manage_options' ) ){
        return false; // Cannot block admins
    }
    return $can_block;
}
```

---

### `bp_better_messages_can_unblock_user` {#bp_better_messages_can_unblock_user}

Filters whether a user can unblock a previously blocked user. Default is `true`.

**Parameters:**
- `$can_unblock` *(bool)* — Default `true`
- `$user_id` *(int)* — User unblocking
- `$blocked_id` *(int)* — User to unblock

**Returns:** `bool`

---

### `bp_better_messages_can_clear_thread` {#bp_better_messages_can_clear_thread}

Filters whether a user can clear all messages from a thread. Default: only users with `bm_can_administrate` capability.

**Parameters:**
- `$can_clear` *(bool)* — Default based on `bm_can_administrate` capability
- `$user_id` *(int)* — The user
- `$thread_id` *(int)* — The thread

**Returns:** `bool`

---

### `bp_better_messages_can_delete_thread` {#bp_better_messages_can_delete_thread}

Filters whether a user can delete a thread from their conversation list.

**Parameters:**
- `$has_access` *(bool)* — Whether user is a thread recipient
- `$thread_id` *(int)* — The thread
- `$user_id` *(int)* — The user

**Returns:** `bool`

---

### `bp_better_messages_can_erase_thread` {#bp_better_messages_can_erase_thread}

Filters whether a user can permanently erase a thread. Default: only `bm_can_administrate`.

**Parameters:**
- `$can_erase` *(bool)* — Default based on capability
- `$user_id` *(int)* — The user
- `$thread_id` *(int)* — The thread

**Returns:** `bool`

---

### `bp_better_messages_user_can_upload_files` {#bp_better_messages_user_can_upload_files}

Filters whether a user can upload file attachments in a thread.

**Parameters:**
- `$can_upload` *(bool)* — Default based on reply access
- `$user_id` *(int)* — The user
- `$thread_id` *(int)* — The thread (or `0` for new messages)

**Returns:** `bool`

```php
add_filter( 'bp_better_messages_user_can_upload_files', 'restrict_uploads', 10, 3 );
function restrict_uploads( $can_upload, $user_id, $thread_id ){
    // Only premium users can upload
    return my_is_premium_user( $user_id );
}
```

---

### `bp_better_messages_enable_groups_tab` {#bp_better_messages_enable_groups_tab}

Filters whether the Messages tab is visible in BuddyPress group navigation. Default `true`.

**Parameters:**
- `$enabled` *(bool)* — Default `true`

**Returns:** `bool`

---

### `better_messages_user_can_connect` {#better_messages_user_can_connect}

Filters whether a user may hold a connection to the WebSocket server. A page is not given connection details for a user the filter says no to, and Better Messages checks it again whenever a user's role changes: it closes the open sessions of a user it now says no to, and lets back a user it had cut off itself once it says yes again. A user revoked with [`better_messages_revoke_user`](/hooks/php-actions/#better_messages_revoke_user) stays revoked until [`better_messages_restore_user`](/hooks/php-actions/#better_messages_restore_user). WebSocket version, 3.0.13 or newer.

**Parameters:**
- `$can_connect` *(bool)* — Default `true`
- `$user_id` *(int)* — The user (negative for guests)

**Returns:** `bool`

```php
add_filter( 'better_messages_user_can_connect', 'only_eligible_members_connect', 10, 2 );
function only_eligible_members_connect( $can_connect, $user_id ){
    if( $user_id > 0 && get_user_meta( $user_id, 'my_suspended', true ) ){
        return false;
    }

    return $can_connect;
}
```

See [Revoke a user's access](/docs/development/guides/revoke-user-access/).

---

## Message Content

### `better_messages_allowed_tags` {#better_messages_allowed_tags}

Filters the allowed HTML tags in message content, used by `wp_kses()` sanitization. The default allows basic formatting: `p`, `b`, `i`, `u`, `strong`, `br`, `strike`, `sub`, `sup`. Add tags to this array to permit richer HTML in messages.

**Parameters:**
- `$tags` *(array)* — Default: `p`, `b`, `i`, `u`, `strong`, `br`, `strike`, `sub`, `sup`

**Returns:** `array`

```php
add_filter( 'better_messages_allowed_tags', 'add_custom_tags' );
function add_custom_tags( $tags ){
    $tags['a'] = array( 'href' => true, 'target' => true );
    $tags['code'] = array();
    return $tags;
}
```

---

### `better_messages_filter_message_content_overwrite` {#better_messages_filter_message_content_overwrite}

Allows completely bypassing the default message content filtering pipeline. If you return a non-empty string, it replaces all default tag stripping and cleanup entirely. Return an empty string (default) to let the standard filtering proceed. Runs before any other content processing.

**Parameters:**
- `$overwrite` *(string)* — Default empty string
- `$content` *(string)* — Raw message content

**Returns:** `string` — Non-empty to override, empty to use default filtering

```php
add_filter( 'better_messages_filter_message_content_overwrite', 'custom_filter', 10, 2 );
function custom_filter( $overwrite, $content ){
    // Apply custom sanitization instead of default
    return wp_kses_post( $content );
}
```

---

### `better_messages_message_content_before_save` {#better_messages_message_content_before_save}

Filters message content immediately before it is inserted into the database. This is the last chance to modify the text after all sanitization has been applied. Called both when creating new messages and when editing existing ones.

**Parameters:**
- `$message` *(string)* — Message content
- `$message_id` *(int)* — Message ID

**Returns:** `string`

```php
add_filter( 'better_messages_message_content_before_save', 'modify_before_save', 10, 2 );
function modify_before_save( $message, $message_id ){
    // Replace profanity
    return str_replace( $bad_words, '***', $message );
}
```

---

### `better_messages_send_message_content` {#better_messages_send_message_content}

Final filter for message content when sending a message via the REST API. Receives both the pre-filtered content and the original raw message, plus the thread ID. Use this for addon-specific content transformations that need access to the unfiltered input.

**Parameters:**
- `$filtered_content` *(string)* — Pre-filtered content
- `$raw_message` *(string)* — Original raw message
- `$thread_id` *(int)* — The thread

**Returns:** `string`

---

### `better_messages_moderation_message_content` {#better_messages_moderation_message_content}

Filters the message content preview displayed in moderation notification emails sent to admins. The default is a 50-word trimmed, tag-stripped version of the message. Use this to customize or redact content in moderation alerts.

**Parameters:**
- `$content` *(string)* — Trimmed, tag-stripped message preview (50 words max)
- `$message` *(object)* — Full message object

**Returns:** `string`

---

### `bp_better_messages_pre_format_message` {#bp_better_messages_pre_format_message}

Filters message content at the very beginning of the formatting pipeline, before any HTML processing occurs. The `$context` parameter is `'stack'` for message list rendering or `'site'` for notification previews (which truncate to 100 characters).

**Parameters:**
- `$message` *(string)* — Message content
- `$message_id` *(int)* — Message ID
- `$context` *(string)* — `'stack'` or `'site'`
- `$user_id` *(int|false)* — Current user or `false`

**Returns:** `string`

---

### `bp_better_messages_after_format_message` {#bp_better_messages_after_format_message}

Filters message content after all HTML formatting is complete but before URLs are converted to clickable links. This is the last stage of the format pipeline — use it for final content transformations that should not affect link detection.

**Parameters:**
- `$message` *(string)* — Formatted message
- `$message_id` *(int)* — Message ID
- `$context` *(string)* — `'stack'` or `'site'`
- `$user_id` *(int|false)* — Current user or `false`

**Returns:** `string`

---

### `better_messages_message_sender_id_before_save` {#better_messages_message_sender_id_before_save}

Filters the sender ID before the message is saved to the database. Use this to override who appears as the message sender, for example when sending messages on behalf of another user or a system account.

**Parameters:**
- `$sender_id` *(int)* — Sender user ID
- `$message_id` *(int)* — Message ID

**Returns:** `int`

---

### `better_messages_message_thread_id_before_save` {#better_messages_message_thread_id_before_save}

Filters the thread ID before the message is saved to the database. Use this to redirect a message to a different thread than originally intended, for example in message routing or forwarding scenarios.

**Parameters:**
- `$thread_id` *(int)* — Thread ID
- `$message_id` *(int)* — Message ID

**Returns:** `int`

---

### `better_messages_message_subject_before_save` {#better_messages_message_subject_before_save}

Filters the message subject/thread subject before the message is saved to the database. The subject is typically set when creating a new conversation thread.

**Parameters:**
- `$subject` *(string)* — Subject text
- `$message_id` *(int)* — Message ID

**Returns:** `string`

---

### `better_messages_message_is_pending_before_save` {#better_messages_message_is_pending_before_save}

Filters the pending status flag before the message is saved. A value of `1` puts the message in the moderation queue for admin approval. A value of `0` delivers the message immediately. Custom moderation logic can use this to dynamically approve or hold messages.

**Parameters:**
- `$is_pending` *(int)* — Pending flag
- `$message_id` *(int)* — Message ID

**Returns:** `int`

---

### `better_messages_message_get_recipient_ids` {#better_messages_message_get_recipient_ids}

Filters the array of recipient user IDs after usernames have been converted to IDs. Use this to dynamically add or remove recipients from a new conversation, for example to auto-include a support agent or exclude banned users.

**Parameters:**
- `$recipient_ids` *(array)* — Array of user IDs
- `$recipient_usernames` *(array)* — Original usernames

**Returns:** `array`

---

### `better_messages_message_created_at_before_save` {#better_messages_message_created_at_before_save}

Filters the message creation timestamp before saving to the database. The timestamp format is milliseconds × 10 (i.e., `Date.toMillis() * 10`). To convert to a PHP DateTime: `new DateTime('@' . ($value / 10000))`.

**Parameters:**
- `$created_at` *(int)* — Timestamp (ms × 10)
- `$message_id` *(int)* — Message ID

**Returns:** `int`

---

### `better_messages_message_date_sent_before_save` {#better_messages_message_date_sent_before_save}

Filters the message sent date timestamp before saving to the database. This is the human-readable sent date, separate from the `created_at` internal timestamp.

**Parameters:**
- `$date_sent` *(int|string)* — Sent timestamp
- `$message_id` *(int)* — Message ID

**Returns:** `int|string`

---

### `better_messages_message_updated_at_before_save` {#better_messages_message_updated_at_before_save}

Filters the message update timestamp before saving to the database. Stored in milliseconds × 10 format, same as `created_at`. Updated when a message is edited.

**Parameters:**
- `$updated_at` *(int)* — Timestamp (ms × 10)
- `$message_id` *(int)* — Message ID

**Returns:** `int`

---

### `better_messages_message_temp_id_before_save` {#better_messages_message_temp_id_before_save}

Filters the temporary message ID (UUID) before saving. The temp_id is generated on the client for offline-first message tracking and is used to match sent messages with their server-assigned IDs.

**Parameters:**
- `$temp_id` *(string)* — UUID tracking identifier
- `$message_id` *(int)* — Message ID

**Returns:** `string`

---

### `better_messages_client_message_meta_keys` {#better_messages_client_message_meta_keys}

Filters which message meta keys a browser is allowed to send with a message. Anything the client posts in `meta` that is not on this list is discarded before the message is saved — silently, with no error, so a key you forget to add here simply never appears in the database.

The default list is `reply_to`, `location` and `e2eFileKeys`, the three keys the messenger itself sends. Every other meta key the plugin stores — the call record, the forwarding attribution, the integration keys — is written on the server and is not a client's to set. The allowlist is what keeps it that way, and it arrived as a security improvement in 3.0.4.

Add a key here when your own code posts custom data alongside a message and needs it stored. Values are still sanitized with `sanitize_text_field()` before saving, so treat what arrives as untrusted input and validate it in `better_messages_before_message_send` if it has to be a number, an id or a known set of values.

**Parameters:**
- `$keys` *(array)* — Allowed meta keys. Default `['reply_to', 'location', 'e2eFileKeys']`

**Returns:** `array`

```php
add_filter( 'better_messages_client_message_meta_keys', 'allow_my_crm_reference' );
function allow_my_crm_reference( $keys ){
    $keys[] = 'my_crm_ref';

    return $keys;
}
```

The same list governs voice and video messages sent through the Voice and Video Messages add-on from version 2.0.2.

---

### `better_messages_change_subject_content` {#better_messages_change_subject_content}

Filters the thread subject text before it is saved to the database when changed via the REST API. Receives both the sanitized and original subject text, plus the thread ID, allowing custom sanitization or transformation rules.

**Parameters:**
- `$sanitized_subject` *(string)* — Sanitized subject
- `$original_subject` *(string)* — Original input
- `$thread_id` *(int)* — The thread

**Returns:** `string`

---

### `better_messages_embed_sandbox` {#better_messages_embed_sandbox}

:::info
Available since Better Messages 2.15.26
:::

Filters the `sandbox` attribute applied to the video player embedded when someone shares a YouTube, Vimeo, VideoPress, Dailymotion or Kickstarter link in a conversation.

The default value is `allow-scripts allow-same-origin allow-presentation allow-popups allow-popups-to-escape-sandbox`.

It deliberately leaves out `allow-top-navigation`, which is what stops the player from moving the page: YouTube draws the video title, the channel name and a *Watch on YouTube* button over the preview, and each of those is a link that takes the whole browser tab to YouTube. On a phone the preview is small enough that those links sit right next to the play button, so a slightly-off tap used to throw the viewer out of the conversation. Sandboxed, the conversation stays open. Playback and the full screen player are unaffected — those are governed by the separate `allowfullscreen` attribute.

`allow-popups` and `allow-popups-to-escape-sandbox` (added in 2.15.27) are what keep those links useful: they are `target="_blank"` links, so they open the video on YouTube in a **new** tab and leave the conversation where it is. Without them the tap is swallowed and the title and logo look broken. A new tab is a separate browsing context, so this does not give the player any way back into the page.

Return an empty string to remove the sandbox entirely and restore the previous behaviour.

**Parameters:**
- `$sandbox` *(string)* — Space-separated sandbox tokens
- `$provider` *(string)* — Lowercased provider name, for example `youtube` or `vimeo`

**Returns:** `string`

```php
add_filter( 'better_messages_embed_sandbox', 'my_embed_sandbox', 10, 2 );
function my_embed_sandbox( $sandbox, $provider ){
    if ( $provider === 'vimeo' ) {
        return '';
    }

    return $sandbox . ' allow-popups allow-popups-to-escape-sandbox';
}
```

Adding `allow-popups allow-popups-to-escape-sandbox`, as above, is the middle ground: the title and *Watch on YouTube* button open in a new tab instead of being dead, and the conversation is left untouched in the original tab.

The attribute is applied when the message is rendered rather than when the link is first fetched, so changing this filter affects videos already sitting in existing conversations without clearing any cache.

---

### `better_messages_youtube_playsinline_fullscreen` {#better_messages_youtube_playsinline_fullscreen}

:::info
Available since Better Messages 2.15.25
:::

Controls whether `playsinline=0` is appended to the source of an embedded YouTube player.

iPhone and iPad have no full screen mode for embedded players, so YouTube's own expand button does nothing there. `playsinline=0` asks YouTube to hand playback to the built-in iOS full screen video player instead, which is what makes a shared video open full screen on tap rather than staying locked at message size. Desktop browsers ignore the parameter and keep playing in place.

Return `false` to leave the player source untouched. A `playsinline` value already present in the source is always respected and never overwritten.

**Parameters:**
- `$enabled` *(bool)* — `true` by default
- `$src` *(string)* — The player URL about to be rewritten

**Returns:** `bool`

```php
add_filter( 'better_messages_youtube_playsinline_fullscreen', '__return_false' );
```

---

## REST API

### `better_messages_rest_thread_item` {#better_messages_rest_thread_item}

Filters thread/conversation data before it is returned in REST API responses. Each thread item includes properties like `isHidden`, `subject`, `title`, `url`, `img`, and `threadInfo`. Use this to add custom fields, modify display data, or hide specific threads.

**Parameters:**
- `$thread_item` *(array)* — Thread data
- `$thread_id` *(int)* — Thread ID
- `$type` *(string)* — `'group'` or `'pm'`
- `$personal_data` *(bool)* — Whether personal data is included
- `$current_user_id` *(int)* — Current user

**Returns:** `array`

**Modifiable fields in `$thread_item`:** `isHidden`, `threadInfo`, `subject`, `title`, `url`, `img`, `participantOverrides` (see the [per-thread fake users](/docs/development/guides/per-thread-fake-users/) guide), and more.

```php
add_filter( 'better_messages_rest_thread_item', 'modify_thread_item', 10, 5 );
function modify_thread_item( $item, $thread_id, $type, $personal, $user_id ){
    // Hide specific threads from the list
    // $item['isHidden'] = 1;

    // Override thread subject/title
    // $item['subject'] = 'Custom Subject';
    // $item['title']   = 'Custom Title';

    // Set custom thread URL and image
    // $item['url'] = 'https://example.com/thread/' . $thread_id;
    // $item['img'] = 'https://example.com/avatar.png';

    // Add custom data
    $item['my_custom_field'] = get_post_meta( $thread_id, 'my_meta', true );

    return $item;
}
```

---

### `better_messages_rest_user_item` {#better_messages_rest_user_item}

Filters user profile data before it is returned in REST API responses. Each user item includes `url`, `avatar`, `name`, `canVideo`, `canAudio`, and other properties. Use this to add custom user fields like badges, roles, or membership levels.

**Parameters:**
- `$item` *(array)* — User data (avatar, name, canVideo, canAudio, etc.)
- `$user_id` *(int)* — User ID
- `$include_personal` *(bool)* — Whether personal call preferences are included

**Returns:** `array`

**Modifiable fields in `$item`:** `url`, `avatar`, `name`, `canVideo`, `canAudio`, and more.

Since 3.0.4, an `$item['name']` set here is filtered through the display name allowlist after this filter runs, the same as a name coming from `bp_better_messages_display_name` — see [`better_messages_display_name_allowed_html`](#better_messages_display_name_allowed_html).

```php
add_filter( 'better_messages_rest_user_item', 'modify_user_item', 10, 3 );
function modify_user_item( $item, $user_id, $include_personal ){
    // Override profile URL
    // $item['url'] = 'https://example.com/members/' . $user_id;

    // Override avatar URL
    // $item['avatar'] = 'https://example.com/avatars/' . $user_id . '.png';

    // Override display name
    // $item['name'] = 'Custom Name';

    // Add custom data
    $item['badge'] = get_user_meta( $user_id, 'membership_level', true );

    return $item;
}
```

---

### `better_messages_rest_message_meta` {#better_messages_rest_message_meta}

Filters the metadata object attached to each message in REST API responses. Default includes `isPending` and `lastEdit` fields. Addons use this to attach additional data like E2E encryption keys, read receipts, or custom annotations per message.

**Parameters:**
- `$meta` *(array)* — Message metadata
- `$message_id` *(int)* — Message ID
- `$thread_id` *(int)* — Thread ID
- `$message_content` *(string)* — Message text

**Returns:** `array`

```php
add_filter( 'better_messages_rest_message_meta', 'add_message_meta', 10, 4 );
function add_message_meta( $meta, $message_id, $thread_id, $content ){
    $meta['priority'] = get_metadata( 'message', $message_id, 'priority', true );
    return $meta;
}
```

---

### `better_messages_rest_response_headers` {#better_messages_rest_response_headers}

Adds custom HTTP headers to all Better Messages REST API responses. Default is an empty array. Use this to add security headers, CORS headers, cache-control directives, or custom version headers for API clients.

**Parameters:**
- `$headers` *(array)* — Default empty array
- `$result` *(WP_REST_Response)* — Response object
- `$request` *(WP_REST_Request)* — Request object

**Returns:** `array`

```php
add_filter( 'better_messages_rest_response_headers', 'add_custom_headers', 10, 3 );
function add_custom_headers( $headers, $result, $request ){
    $headers['X-BM-Version'] = '2.10.0';
    return $headers;
}
```

---

### `better_messages_rest_api_update_data` {#better_messages_rest_api_update_data}

Filters the complete response data for the main update/polling endpoint (`checkNew` and `get_threads`). The response includes threads, users, messages, and `currentTime`. Use this to inject additional data that the frontend needs during sync cycles.

**Parameters:**
- `$return` *(array)* — Response with threads, users, messages, currentTime, etc.
- `$current_user_id` *(int)* — Current user
- `$lastClient` *(int)* — Last client sync timestamp

**Returns:** `array`

---

### `better_messages_predefined_suggestions_user_ids` {#better_messages_predefined_suggestions_user_ids}

Defines predefined user IDs to suggest as recipients when starting a new conversation. Return empty array for default behavior.

**Parameters:**
- `$user_ids` *(array)* — Default empty array

**Returns:** `array`

```php
add_filter( 'better_messages_predefined_suggestions_user_ids', 'suggest_staff' );
function suggest_staff( $user_ids ){
    // Always suggest support staff
    return array( 1, 2, 3 ); // Staff user IDs
}
```

---

### `better_messages_get_unique_conversation` {#better_messages_get_unique_conversation}

Resolves a unique conversation key string to a thread ID for custom conversation routing. Default returns `0` (not found). The E2E encryption addon and custom integrations use this to map unique identifiers to specific conversations.

**Parameters:**
- `$thread_id` *(int)* — Default `0` (not found)
- `$key` *(string)* — Unique key parameter
- `$current_user_id` *(int)* — Current user

**Returns:** `int`

---

### `better_messages_new_thread_after_create` {#better_messages_new_thread_after_create}

Filters the result after a new thread is created via the REST API. The `$sent` array contains `thread_id` and `message_id`. Used by the E2E encryption addon to encrypt and send the initial thread data to the server.

**Parameters:**
- `$sent` *(array)* — Array with `thread_id` and `message_id`
- `$request` *(WP_REST_Request)* — The request
- `$current_user_id` *(int)* — Creator user ID

**Returns:** `array`

---

### `better_messages_new_thread_attachments` {#better_messages_new_thread_attachments}

Filters the array of uploaded file attachments before they are attached to a new thread's first message. Receives the file info array and the REST request object. Use this to validate, transform, or filter attachments during thread creation.

**Parameters:**
- `$uploaded_files` *(array)* — Attachment file info
- `$request` *(WP_REST_Request)* — The request

**Returns:** `array`

---

### `better_messages_new_thread_e2e_init` {#better_messages_new_thread_e2e_init}

Allows E2E encryption addons to intercept content before default sanitization. Return array with `subject` and `content` keys to override.

**Parameters:**
- `$e2e_init` *(null|array)* — Default `null`
- `$request` *(WP_REST_Request)* — The request
- `$recipients` *(array)* — Recipient user IDs

**Returns:** `null|array`

---

### `better_messages_private_thread_result` {#better_messages_private_thread_result}

Filters the result when getting or creating a private 1-on-1 thread via the `suggest_thread` endpoint. The result includes `thread_id` and a status string. Used by the E2E encryption addon to apply encryption setup to newly created PM threads.

**Parameters:**
- `$result` *(array)* — Result with `thread_id` and `result` status
- `$user_id` *(int)* — Other user
- `$current_user_id` *(int)* — Current user

**Returns:** `array`

---

## User Identity & Display

### `better_messages_get_member_id` {#better_messages_get_member_id}

Allows customization of the member ID used in shortcodes like `[better_messages_pm_button]`, `[better_messages_mini_chat_button]`, `[better_messages_audio_call_button]`, and `[better_messages_video_call_button]`.

**Parameters:**
- `$user_id` *(null|int)* — Default `null`

**Returns:** `int|null`

```php
add_filter( 'better_messages_get_member_id', 'custom_member_id' );
function custom_member_id( $user_id ){
    if( is_singular('product') ){
        // Return the product author as the message recipient
        return get_post_field( 'post_author', get_the_ID() );
    }
    return $user_id;
}
```

---

### `better_messages_get_user_roles` {#better_messages_get_user_roles}

Filters user roles used by the plugin for role-based restrictions, limitations, and feature access. Returns `['bm-guest']` for guest users. Modify this to add custom roles or override WordPress roles for Better Messages-specific permission logic.

**Parameters:**
- `$roles` *(array)* — User roles array
- `$user_id` *(int)* — User ID

**Returns:** `array`

```php
add_filter( 'better_messages_get_user_roles', 'add_custom_role', 10, 2 );
function add_custom_role( $roles, $user_id ){
    if( my_is_vip( $user_id ) ){
        $roles[] = 'vip';
    }
    return $roles;
}
```

The role restrictions under **Settings → Restrictions** read roles through this filter, and so do **Calls → Call Restrictions** and the restrictions of **Group Calls**, so it also works for memberships that aren't WordPress roles. For example, when every member is a Subscriber and MemberPress decides who is VIP, swap Subscriber for a role of your own for active VIP members. Then pick Subscriber in **Restrict New Conversations** and only VIPs can start conversations, while everyone can still reply:

```php
add_filter( 'better_messages_get_user_roles', function( $roles, $user_id ){
    if( $user_id > 0 && class_exists( 'MeprUser' ) ){
        $member = new MeprUser( $user_id );
        if( $member->is_already_subscribed_to( 123 ) ){ // your VIP membership ID
            $roles   = array_diff( (array) $roles, array( 'subscriber' ) );
            $roles[] = 'vip';
        }
    }
    return array_values( $roles );
}, 10, 2 );
```

A role added only through this filter isn't listed in the role pickers of the settings page. Restrict the roles that are listed (here Subscriber) and let the filter move members out of them.

---

### `better_messages_is_verified` {#better_messages_is_verified}

Determines if a user is verified and should display a verification badge next to their name. Default is `false` — verification must be implemented via this filter. Integrate with membership plugins, manual verification systems, or custom logic.

**Parameters:**
- `$verified` *(bool)* — Default `false`
- `$user_id` *(int)* — User ID

**Returns:** `bool`

```php
add_filter( 'better_messages_is_verified', 'verify_premium_users', 10, 2 );
function verify_premium_users( $verified, $user_id ){
    return my_is_premium_user( $user_id );
}
```

---

### `better_messages_forced_current_user_id` {#better_messages_forced_current_user_id}

Forces a different user ID to be used instead of the currently logged-in WordPress user. Return `null` to use the default user detection logic. Useful for impersonation features, admin viewing as another user, or testing scenarios.

**Parameters:**
- `$user_id` *(null|int)* — Default `null` (use WordPress current user)

**Returns:** `int|null`

---

### `better_messages_logged_in_user_id` {#better_messages_logged_in_user_id}

Filters the user ID returned for logged-in WordPress users. Default is `get_current_user_id()`. Use this to override user identity for specific contexts without affecting the WordPress session.

**Parameters:**
- `$user_id` *(int)* — Default `get_current_user_id()`

**Returns:** `int`

---

### `better_messages_guest_user_id` {#better_messages_guest_user_id}

Returns the user ID for non-logged-in (guest) users. Default is `0`. Guest addon sets this to a negative number representing the guest's internal ID.

**Parameters:**
- `$user_id` *(int)* — Default `0`

**Returns:** `int`

---

### `better_messages_generated_guest_name` {#better_messages_generated_guest_name}

Customizes the randomly generated display name for new guest users. The default uses an alliterative name generator (e.g., 'Cheerful Chipmunk'). Return a custom string to use your own naming convention.

**Parameters:**
- `$name` *(string)* — Generated alliterative name

**Returns:** `string`

```php
add_filter( 'better_messages_generated_guest_name', 'custom_guest_name' );
function custom_guest_name( $name ){
    return 'Guest #' . wp_rand( 1000, 9999 );
}
```

---

### `better_messages_guest_display_name` {#better_messages_guest_display_name}

Customizes the display name for guest users when their profile is loaded. Default is an empty string (the plugin uses the stored guest name). Override this to apply formatting or add prefixes like 'Guest: ' to guest names.

**Parameters:**
- `$name` *(string)* — Default empty string
- `$user_id` *(int)* — Guest user ID (negative)

**Returns:** `string`

Whatever this filter returns passes through the display name allowlist before it reaches a reader — see [`better_messages_display_name_allowed_html`](#better_messages_display_name_allowed_html) below.

---

### `bp_better_messages_display_name` {#bp_better_messages_display_name}

Filters the display name for registered WordPress users throughout the messaging UI. The default is the user's fullname or display_name. Use this to add role badges, format names differently, or integrate with custom profile systems.

**Parameters:**
- `$name` *(string)* — User's display name
- `$user_id` *(int)* — User ID

**Returns:** `string`

```php
add_filter( 'bp_better_messages_display_name', 'add_role_badge', 10, 2 );
function add_role_badge( $name, $user_id ){
    if( user_can( $user_id, 'manage_options' ) ){
        return $name . ' [Admin]';
    }
    return $name;
}
```

Whatever this filter returns passes through the display name allowlist before it reaches a reader — see [`better_messages_display_name_allowed_html`](#better_messages_display_name_allowed_html) below.

---

### `better_messages_display_name_allowed_html` {#better_messages_display_name_allowed_html}

Filters the HTML a display name is allowed to carry.

Names are rendered as markup rather than printed as text, which is what lets an integration hang a badge, a rank icon or a verification mark off one. The name itself is whatever the member typed into their own profile, though, so every name is filtered through this allowlist before it reaches a reader. The allowlist arrived as a security improvement in 3.0.4.

The default list covers decoration: `img`, `a`, `span`, `i`, `b`, `strong`, `em`, `small`, `sup`, `sub`, `u`, `s`, `mark`, `abbr`, `bdi` and `br`, each carrying `class`, `id`, `title`, `style`, `dir`, `lang`, `role` and any `data-*` or `aria-*` attribute. An element that is not on the list keeps its contents and loses only its own tag, so a wrapper never takes a badge down with it.

**Parameters:**
- `$allowed` *(array)* — Tag name to allowed-attribute map, in [`wp_kses()`](https://developer.wordpress.org/reference/functions/wp_kses/) format

**Returns:** `array`

```php
add_filter( 'better_messages_display_name_allowed_html', 'allow_rank_ribbon' );
function allow_rank_ribbon( $allowed ){
    $allowed['ins'] = array(
        'class'  => true,
        'data-*' => true,
    );

    return $allowed;
}
```

:::warning Some things stay refused
Event-handler attributes (`on*`), `srcdoc` and `formaction` are stripped whatever this filter returns, and so are scripting and framing elements — `iframe`, `script`, `object`, `embed`, `form`, `svg`, `math` and the rest. A display name is attacker-controlled on any site where a member can edit their own profile, and putting those back would undo the security improvement this allowlist is. No filter can re-enable them.
:::

:::note Register it twice — the messenger filters again
The allowlist runs on the server and a second time in the browser, so that a name cached from before an update, or one relayed by the realtime server, is filtered at the point it is rendered rather than only at the point it was sent. The two halves are separate lists and both carry this hook, under the same name and the same shape.

Adding a tag in PHP alone covers wp-admin and server-rendered surfaces, and the messenger still drops it. Add it in both to have it render everywhere:

```js
wp.hooks.addFilter(
    'better_messages_display_name_allowed_html',
    'my-plugin/rank-ribbon',
    function ( allowed ) {
        allowed.ins = { 'class': true, 'data-*': true };

        return allowed;
    }
);
```

Enqueue that with `wp-hooks` as a dependency so it registers before the messenger renders its first name.
:::

---

### `bp_better_messages_avatar_extra_attr` {#bp_better_messages_avatar_extra_attr}

Adds custom HTML attributes to the `` tag of user avatars. Default includes `data-size` and `data-user-id` attributes. Use this to add `data-*` attributes, `aria-` labels, or other custom HTML attributes for styling or JavaScript hooks.

**Parameters:**
- `$attributes` *(string)* — Default data attributes (size, user-id)
- `$user_id` *(int)* — User ID
- `$size` *(int)* — Avatar size in px

**Returns:** `string`

---

## Thread Display

### `better_messages_thread_title` {#better_messages_thread_title}

Customizes thread/conversation titles displayed in the UI. The default is the thread subject, or an auto-generated title from participant names when subjects are disabled. The `$thread` object provides full thread data for conditional logic.

**Parameters:**
- `$title` *(string)* — Thread subject or auto-generated title
- `$thread_id` *(int)* — Thread ID
- `$thread` *(object)* — Thread object

**Returns:** `string`

```php
add_filter( 'better_messages_thread_title', 'custom_thread_title', 10, 3 );
function custom_thread_title( $title, $thread_id, $thread ){
    $custom = Better_Messages()->functions->get_thread_meta( $thread_id, 'custom_title' );
    return $custom ?: $title;
}
```

---

### `better_messages_thread_image` {#better_messages_thread_image}

Customizes the preview image/thumbnail for a conversation thread. Default is an empty string (no image). Return a URL to display a custom image next to the thread in the conversation list.

**Parameters:**
- `$image` *(string)* — Default empty string
- `$thread_id` *(int)* — Thread ID
- `$thread` *(object)* — Thread object

**Returns:** `string` — Image URL

---

### `better_messages_thread_url` {#better_messages_thread_url}

Customizes the URL link associated with a thread. Default is an empty string. Return a URL to make the thread title clickable, linking to an external page or custom view.

**Parameters:**
- `$url` *(string)* — Default empty string
- `$thread_id` *(int)* — Thread ID
- `$thread` *(object)* — Thread object

**Returns:** `string`

---

## Friends, Groups & Social

### `better_messages_friends_active` {#better_messages_friends_active}

Whether the friends feature is active in the messaging system. Default `false`. BuddyPress and BuddyBoss automatically enable this. Enable it to show friends lists, restrict messaging to friends, and use friend-based suggestions.

**Parameters:**
- `$active` *(bool)* — Default `false`

**Returns:** `bool`

---

### `better_messages_followers_active` {#better_messages_followers_active}

Whether the followers feature is active in the messaging system. Default `false`. Enable it to restrict messaging to followed users or show follower-based contact lists.

**Parameters:**
- `$active` *(bool)* — Default `false`

**Returns:** `bool`

---

### `better_messages_groups_active` {#better_messages_groups_active}

Whether the groups feature is active in the messaging system. Default `false`. BuddyPress, PeepSo, and other community plugins automatically enable this for group-based messaging.

**Parameters:**
- `$active` *(bool)* — Default `false`

**Returns:** `bool`

---

### `better_messages_is_friends` {#better_messages_is_friends}

Determines if two users are friends when using a custom friendship system (not BuddyPress). Default `false`. Implement this filter to integrate your own friend/connection system with Better Messages friend-based restrictions.

**Parameters:**
- `$are_friends` *(bool)* — Default `false`
- `$user_id_1` *(int)* — First user
- `$user_id_2` *(int)* — Second user

**Returns:** `bool`

```php
add_filter( 'better_messages_is_friends', 'custom_friendship', 10, 3 );
function custom_friendship( $are_friends, $user1, $user2 ){
    return my_friendship_system_check( $user1, $user2 );
}
```

---

### `better_messages_is_followers` {#better_messages_is_followers}

Determines if user_id_1 follows user_id_2 when using a custom follower system. Default `false`. Implement this filter to integrate your own follower system with Better Messages follower-based restrictions.

**Parameters:**
- `$is_follower` *(bool)* — Default `false`
- `$user_id_1` *(int)* — First user
- `$user_id_2` *(int)* — Second user

**Returns:** `bool`

---

### `better_messages_only_friends_mode` {#better_messages_only_friends_mode}

Restricts messaging to friends only when enabled. Default `false`. When `true`, users can only start conversations with their friends. Administrators bypass this restriction.

**Parameters:**
- `$enabled` *(bool)* — Default `false`

**Returns:** `bool`

---

### `better_messages_only_followers_mode` {#better_messages_only_followers_mode}

Restricts messaging to followers only when enabled. Default `false`. When `true`, users can only start conversations with users who follow them.

**Parameters:**
- `$enabled` *(bool)* — Default `false`

**Returns:** `bool`

---

### `better_messages_get_friends` {#better_messages_get_friends}

Returns the list of friends for a user via the REST API and internal functions. Default is an empty array. BuddyPress and other social plugins hook into this to provide actual friend data. Return an array of user IDs or user objects.

**Parameters:**
- `$friends` *(array)* — Default empty array
- `$user_id` *(int)* — User ID

**Returns:** `array`

```php
add_filter( 'better_messages_get_friends', 'custom_friends_list', 10, 2 );
function custom_friends_list( $friends, $user_id ){
    return my_get_user_friends( $user_id );
}
```

---

### `better_messages_get_groups` {#better_messages_get_groups}

Returns the list of groups for a user via the REST API. Default is an empty array. BuddyPress, PeepSo, and other group plugins hook into this to provide group data. Return an array of group IDs or group objects.

**Parameters:**
- `$groups` *(array)* — Default empty array
- `$user_id` *(int)* — User ID

**Returns:** `array`

---

## Calls & Video

### `bp_better_messages_can_start_call` {#bp_better_messages_can_start_call}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Base capability check for whether a user can start any type of call (audio or video) in a thread. Default is based on the user's send message permission in the thread. This filter runs before the specific audio/video call filters.

**Parameters:**
- `$can_call` *(bool)* — Default based on send message permission
- `$user_id` *(int)* — User starting the call
- `$thread_id` *(int)* — Thread ID

**Returns:** `bool`

---

### `bp_better_messages_can_audio_call` {#bp_better_messages_can_audio_call}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Whether a user can make audio calls in a specific thread. Default is based on the `bp_better_messages_can_start_call` filter result. Return `false` to disable audio calling for specific users or threads while still allowing video calls.

**Parameters:**
- `$can_call` *(bool)* — Default based on `bp_better_messages_can_start_call`
- `$user_id` *(int)* — User ID
- `$thread_id` *(int)* — Thread ID

**Returns:** `bool`

---

### `bp_better_messages_can_video_call` {#bp_better_messages_can_video_call}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Whether a user can make video calls in a specific thread. Default is based on the `bp_better_messages_can_start_call` filter result. Return `false` to disable video calling for specific users or threads while still allowing audio calls.

**Parameters:**
- `$can_call` *(bool)* — Default based on `bp_better_messages_can_start_call`
- `$user_id` *(int)* — User ID
- `$thread_id` *(int)* — Thread ID

**Returns:** `bool`

```php
add_filter( 'bp_better_messages_can_video_call', 'restrict_video_calls', 10, 3 );
function restrict_video_calls( $can_call, $user_id, $thread_id ){
    // Video calls only for premium users
    return my_is_premium_user( $user_id );
}
```

---

### `better_messages_call_create_custom_error` {#better_messages_call_create_custom_error}

Custom error message for call creation. Return empty string to allow, non-empty to deny.

**Parameters:**
- `$error` *(string)* — Default empty string
- `$thread_id` *(int)* — Thread ID
- `$user_id` *(int)* — User initiating call
- `$type` *(string)* — `'audio'` or `'video'`

**Returns:** `string`

```php
add_filter( 'better_messages_call_create_custom_error', 'time_based_calls', 10, 4 );
function time_based_calls( $error, $thread_id, $user_id, $type ){
    $hour = (int) date('G');
    if( $hour < 8 || $hour > 22 ){
        return 'Calls are only available between 8 AM and 10 PM';
    }
    return $error;
}
```

---

### `better_messages_call_join_custom_error` {#better_messages_call_join_custom_error}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Custom error message for joining an existing **1-to-1 (private) call**. Return empty string to allow, non-empty string to deny with that message. Does not apply to group/conversation calls — for those, use [`better_messages_group_call_join_custom_error`](#better_messages_group_call_join_custom_error).

**Parameters:**
- `$error` *(string)* — Default empty string
- `$thread_id` *(int)* — Thread ID
- `$user_id` *(int)* — User joining
- `$type` *(string)* — `'audio'` or `'video'`

**Returns:** `string`

```php
add_filter( 'better_messages_call_join_custom_error', 'block_male_users_from_audio', 10, 4 );
function block_male_users_from_audio( $error, $thread_id, $user_id, $type ){
    if( $type === 'audio' && get_user_meta( $user_id, 'gender', true ) === 'male' ){
        return __( 'Audio calls are not available for your account', 'your-textdomain' );
    }
    return $error;
}
```

---

### `better_messages_group_call_join_custom_error` {#better_messages_group_call_join_custom_error}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Custom error message for joining a **group call / chatroom** (audio or video). Runs after the built-in `restrictGroupCallsJoin` role restriction passes, so use it for per-user or condition-based logic that the role setting can't express. Return empty string to allow, non-empty string to deny with that message.

Since 3.2.0 it is also asked before a person who may not join at all is refused, someone banned from a chat room or no longer in the conversation, so they read why instead of a bare refusal. Better Messages answers it itself at priority 10 for its bans: a ban from the conversation ("You were banned in this conversation until") and a ban from its calls with [Remove and Ban from Calls](/docs/websocket/group-video-chat/#remove-and-ban-from-calls) ("A moderator removed you from the calls of this conversation until"). Keep an `$error` that is not empty, as the example does.

**Parameters:**
- `$error` *(string)* — Empty, or the message of a ban already found
- `$thread_id` *(int)* — Thread (group/conversation) ID
- `$user_id` *(int)* — User joining the room
- `$type` *(string)* — `'audio'` or `'video'`

**Returns:** `string`

```php
add_filter( 'better_messages_group_call_join_custom_error', 'block_male_users_from_group_audio', 10, 4 );
function block_male_users_from_group_audio( $error, $thread_id, $user_id, $type ){
    if( $type === 'audio' && get_user_meta( $user_id, 'gender', true ) === 'male' ){
        return __( 'This audio chatroom is not available for your account', 'your-textdomain' );
    }
    return $error;
}
```

---

### `better_messages_group_call_participants_cache_time` {#better_messages_group_call_participants_cache_time}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

How many seconds a group call participant count is cached before the call server is asked again. Default is `5`. Raise it on a page that polls often, or return `0` to read a fresh number on every call — useful while testing, wasteful on a busy page.

Applies to [`get_group_call_participants`](/hooks/php-functions#get_group_call_participants) and to the REST endpoint built on it.

**Parameters:**
- `$seconds` *(int)* — Default `5`
- `$thread_id` *(int)* — Conversation ID
- `$type` *(string)* — `'audio'` or `'video'`

**Returns:** `int`

```php
add_filter( 'better_messages_group_call_participants_cache_time', 'faster_occupancy_counts', 10, 3 );
function faster_occupancy_counts( $seconds, $thread_id, $type ){
    return 2;
}
```

---

### `better_messages_private_call_allowed_error` {#better_messages_private_call_allowed_error}

Custom error for private 1-on-1 calls. Return empty string to allow.

**Parameters:**
- `$error` *(string)* — Default empty string
- `$thread_id` *(int)* — Thread ID
- `$current_user_id` *(int)* — Caller
- `$target_user_id` *(int)* — Called user

**Returns:** `string`

---

### `better_messages_points_call_charge_rate` {#better_messages_points_call_charge_rate}

Filters the points charge rate per minute for voice/video calls when the points integration is active. Receives both caller and target user IDs for per-user pricing logic. The legacy `better_messages_mycred_call_charge_rate` filter is also applied for backward compatibility.

**Parameters:**
- `$charge_rate` *(int|float)* — Points per minute
- `$thread_id` *(int)* — Thread ID
- `$caller_id` *(int)* — Caller user ID
- `$target_id` *(int)* — Target user ID

**Returns:** `int|float`

---

## Notifications & Push

### `better_messages_push_notification` {#better_messages_push_notification}

:::info
Available since Better Messages 2.15.26
:::

Filters the push notification payload before it is sent, with both recipient and thread context. Use it to change the URL a notification opens, or its title, body, icon or tag, without modifying plugin files.

This filter runs on **every** push delivery path — the built-in Web Push, the [mobile app](/docs/category/mobile-app/) push, the [OneSignal integration](/docs/integrations/onesignal/), the BuddyBoss app push, and the bulk path used when a message has several recipients — so a single callback covers them all.

**Parameters:**
- `$notification` *(array)* — Notification payload: `title`, `body`, `icon`, `tag`, and `data` (which holds `url`)
- `$user_id` *(int)* — Recipient user ID. `0` when one payload is shared by several recipients, which happens only on the third-party bulk path
- `$type` *(string|null)* — `new_message`, `call_request` or `call_missed`
- `$thread_id` *(int)* — Conversation ID
- `$message_id` *(int)* — Message ID
- `$sender_id` *(int)* — User ID of the sender

**Returns:** `array`

```php
add_filter( 'better_messages_push_notification', 'my_push_url', 10, 6 );
function my_push_url( $notification, $user_id, $type, $thread_id, $message_id, $sender_id ){
    if ( $type !== 'call_request' ) {
        return $notification;
    }

    $notification['data']['url'] = add_query_arg(
        array( 'thread' => $thread_id ),
        home_url( '/my-call-screen/' )
    );

    return $notification;
}
```

Because the recipient is passed in, the destination can differ per user — useful when the same conversation is reached through different pages depending on who is opening it.

:::caution
When `$user_id` is `0` the payload is shared by every recipient, so anything recipient-specific must be skipped in that case.
:::

---

### `better_messages_mobile_push_content` {#better_messages_mobile_push_content}

:::info
Available since Better Messages 2.15.26
:::

Filters the text of push notifications sent to the [native mobile app](/docs/category/mobile-app/).

This is a separate hook from [`better_messages_push_notification`](#better_messages_push_notification) because the native app does not receive a web notification: it receives platform payloads for APNs and FCM. The app opens the right conversation from the thread ID it is given rather than from a URL, so there is no address to rewrite here — only the wording to adjust.

The filter runs on the plain text, **before** the sender name and avatar are encrypted individually for each of the recipient's devices, so whatever is returned here is what gets encrypted and delivered.

**Parameters:**
- `$content` *(array)* — `title`, `body`, `sender`, and `avatar` (the last only for `new_message`)
- `$type` *(string)* — `new_message` or `call_request`
- `$thread_id` *(int)* — Conversation ID
- `$message_id` *(int)* — Message ID
- `$sender_id` *(int)* — User ID of the sender
- `$user_id` *(int)* — Recipient user ID for call pushes. `0` for `new_message`, which is built once for every recipient

**Returns:** `array`

```php
add_filter( 'better_messages_mobile_push_content', 'my_mobile_push', 10, 6 );
function my_mobile_push( $content, $type, $thread_id, $message_id, $sender_id, $user_id ){
    if ( $type === 'call_request' ) {
        $content['title'] = 'Consultation call';
    }

    return $content;
}
```

:::caution
Return the array with its keys intact. Removing one leaves the notification without that piece of text.
:::

---

### `better_messages_push_active` {#better_messages_push_active}

Whether the built-in push notification system is active.

**Parameters:**
- `$active` *(bool)* — Default from `enablePushNotifications` setting

**Returns:** `bool`

---

### `better_messages_3rd_party_push_active` {#better_messages_3rd_party_push_active}

Whether a third-party push notification system is active. Default `false`.

**Parameters:**
- `$active` *(bool)* — Default `false`

**Returns:** `bool`

---

### `better_messages_bulk_pushs` {#better_messages_bulk_pushs}

Custom push notifications for multiple recipients via third-party systems.

**Parameters:**
- `$pushes` *(array)* — Default empty array
- `$all_recipients` *(array)* — User IDs
- `$notification` *(object)* — Notification data
- `$message` *(object)* — Message object

**Returns:** `array`

---

### `better_messages_get_user_push_subscriptions` {#better_messages_get_user_push_subscriptions}

Returns push subscriptions for a user when built-in push is inactive.

**Parameters:**
- `$subscriptions` *(array)* — Default empty array
- `$user_id` *(int)* — User ID

**Returns:** `array`

---

### `better_messages_send_mobile_pushs` {#better_messages_send_mobile_pushs}

Sends push notifications to mobile devices via third-party services like Firebase Cloud Messaging. Default is an empty array. Return an array of push notification objects to be sent. Receives the full notification data along with thread and message context.

**Parameters:**
- `$pushes` *(array)* — Default empty array
- `$user_id` *(int)* — Recipient
- `$notification` *(object)* — Notification data
- `$type` *(string|null)* — Notification type
- `$thread_id` *(int)* — Thread ID
- `$message_id` *(int)* — Message ID
- `$sender_id` *(int)* — Sender ID

**Returns:** `array`

---

### `better_messages_send_onesignal_push` {#better_messages_send_onesignal_push}

Sends a push notification via OneSignal integration. Default is `false` (no OneSignal push). Return an array of OneSignal push data to send, or `false` to skip. Receives full notification context including thread ID, message ID, and sender ID.

**Parameters:**
- `$push` *(bool|array)* — Default `false`
- `$user_id` *(int)* — Recipient
- `$notification` *(object)* — Notification data
- `$type` *(string|null)* — Notification type
- `$thread_id` *(int)* — Thread ID
- `$message_id` *(int)* — Message ID
- `$sender_id` *(int)* — Sender ID

**Returns:** `bool|array`

---

### `better_messages_vapid_keys` {#better_messages_vapid_keys}

Web Push VAPID key pair. Return `false` to use stored keys.

**Parameters:**
- `$keys` *(array|false)* — Default `false`

**Returns:** `array|false` — Array with `publicKey` and `privateKey`

---

### `better_messages_is_user_emails_enabled` {#better_messages_is_user_emails_enabled}

Whether email notifications are enabled for a user. The stored preference is `true` unless the member switched emails off in their messenger settings (or used the unsubscribe link), so a member who never touched the switch counts as enabled. The switch in the member's settings reads its state through this filter too, so it always shows what the member will actually get.

**Parameters:**
- `$enabled` *(bool)* — User's stored preference
- `$user_id` *(int)* — User ID

**Returns:** `bool`

To make message emails opt-in (off until a member switches them on), remember each member's own choice with [`better_messages_user_emails_enabled_update`](/hooks/php-actions#better_messages_user_emails_enabled_update) and only allow emails for members who chose them:

```php
// Remember each member's explicit choice
add_action( 'better_messages_user_emails_enabled_update', function( $user_id, $enabled ){
    update_user_meta( $user_id, 'my_bm_email_optin', $enabled === 'yes' ? 'yes' : 'no' );
}, 10, 2 );

// Only email members who switched emails on themselves
add_filter( 'better_messages_is_user_emails_enabled', function( $enabled, $user_id ){
    return $enabled && get_user_meta( $user_id, 'my_bm_email_optin', true ) === 'yes';
}, 10, 2 );
```

Members who never chose then see the switch off in their settings, and turning it on starts their emails.

---

### `better_messages_can_have_group_conversations` {#better_messages_can_have_group_conversations}

Whether a member can be in a conversation of more than two people, a chat room, an integration group or a course. The messenger settings offer the email choice **Only one-to-one conversations, mentions and replies** only to such a member, since for anyone else it mails exactly like **All my notifications**, and a member who had picked it is shown **All my notifications**. By default it is `true` while members can start group conversations, and otherwise `true` only for a member who is already in one of them. See [What members are emailed about](/docs/features/email-notifications/#what-members-are-emailed-about). Since 3.2.0.

**Parameters:**
- `$can` *(bool)* — The default described above
- `$user_id` *(int)* — The member

**Returns:** `bool`

```php
// Members of a membership level join chat rooms later: offer them the choice from the start
add_filter( 'better_messages_can_have_group_conversations', function( $can, $user_id ){
    return $can || ( function_exists( 'pmpro_hasMembershipLevel' ) && pmpro_hasMembershipLevel( null, $user_id ) );
}, 10, 2 );
```

---

### `better_messages_is_user_web_push_enabled` {#better_messages_is_user_web_push_enabled}

Whether web push is enabled for a user. Default `true`.

**Parameters:**
- `$enabled` *(bool)* — Default `true`
- `$user_id` *(int)* — User ID

**Returns:** `bool`

---

### `bp_better_messages_overwrite_email` {#bp_better_messages_overwrite_email}

Completely replaces the default notification email with custom content or a third-party email service. Return `false` to use the default email template, or return custom HTML/true to override it. Receives the user ID, thread ID, and array of unread messages for the notification.

**Parameters:**
- `$overwrite` *(bool|string)* — Default `false`
- `$user_id` *(int)* — Recipient
- `$thread_id` *(int)* — Thread
- `$messages` *(array)* — Messages in notification

**Returns:** `bool|string` — `false` for default email, or custom HTML

```php
add_filter( 'bp_better_messages_overwrite_email', 'custom_email', 10, 4 );
function custom_email( $overwrite, $user_id, $thread_id, $messages ){
    // Send custom email instead
    my_send_custom_email( $user_id, $thread_id, $messages );
    return true; // Prevent default email
}
```

---

### `bp_better_messages_notification_tokens` {#bp_better_messages_notification_tokens}

Filters the token placeholders available in email notification templates. Default tokens include `messages.html`, `messages.raw`, `sender.name`, `thread.id`, `thread.url`, `subject`, and `unsubscribe`. Add custom tokens to support custom email template variables.

**Parameters:**
- `$tokens` *(array)* — Keys: `messages.html`, `messages.raw`, `sender.name`, `thread.id`, `thread.url`, `subject`, `unsubscribe`

**Returns:** `array`

---

### `better_messages_email_notification_time` {#better_messages_email_notification_time}

Customizes the formatted timestamp shown in email notifications.

**Parameters:**
- `$time` *(string)* — Formatted date/time
- `$message` *(object)* — Message object
- `$user_id` *(int)* — Recipient

**Returns:** `string`

---

### `better_messages_buddypress_notification_url` {#better_messages_buddypress_notification_url}

Customizes BuddyPress notification click URL.

**Parameters:**
- `$url` *(string)* — Notification URL
- `$notification` *(object)* — BuddyPress notification

**Returns:** `string`

---

### `better_messages_bb_app_push_only_online` {#better_messages_bb_app_push_only_online}

Controls whether to send push only to online BuddyBoss app users. Default `true`.

**Parameters:**
- `$only_online` *(bool)* — Default `true`

**Returns:** `bool`

---

## Search

### `better_messages_search_results` {#better_messages_search_results}

Filters complete search results.

**Parameters:**
- `$return` *(array)* — Array with `friends`, `users`, `messages`, `updateData` keys
- `$search` *(string)* — Search query
- `$user_id` *(int)* — Searcher

**Returns:** `array`

---

### `better_messages_search_user_results` {#better_messages_search_user_results}

Filters user IDs matching a search query.

**Parameters:**
- `$user_ids` *(array)* — Matching user IDs
- `$search` *(string)* — Search query
- `$user_id` *(int)* — Searcher

**Returns:** `array`

---

### `better_messages_search_messages_results` {#better_messages_search_messages_results}

Filters message search results.

**Parameters:**
- `$messages` *(array)* — Messages with thread_id, message_id, count
- `$search` *(string)* — Search query
- `$user_id` *(int)* — Searcher

**Returns:** `array`

---

### `better_messages_search_friends` {#better_messages_search_friends}

Returns friend user IDs for search results when only-friends messaging mode is enabled. Default is an empty array. Implement this to provide friend lists from custom social systems that aren't BuddyPress or BuddyBoss.

**Parameters:**
- `$friends` *(array)* — Default empty array
- `$search` *(string)* — Search query
- `$user_id` *(int)* — Current user

**Returns:** `array`

---

### `better_messages_search_user_sql_condition` {#better_messages_search_user_sql_condition}

Adds custom SQL WHERE conditions to user search.

**Parameters:**
- `$conditions` *(array)* — SQL condition strings
- `$found_user_ids` *(array)* — Already-found user IDs
- `$search` *(string)* — Search query
- `$user_id` *(int)* — Searcher

**Returns:** `array`

```php
// Example 1: Exclude specific user IDs
add_filter( 'better_messages_search_user_sql_condition', 'exclude_users', 10, 4 );
function exclude_users( $sql_array, $user_ids, $search, $user_id ){
    $sql_array[] = "AND ID NOT IN(1,2,3)";
    return $sql_array;
}

// Example 2: Exclude users with 'subscriber' role
add_filter( 'better_messages_search_user_sql_condition', 'exclude_subscribers', 10, 4 );
function exclude_subscribers( $sql_array, $user_ids, $search, $user_id ){
    global $wpdb;
    $sql_array[] = $wpdb->prepare(
        "AND ID NOT IN (SELECT user_id FROM {$wpdb->usermeta} WHERE meta_key = %s AND meta_value LIKE %s)",
        $wpdb->prefix . 'capabilities',
        '%subscriber%'
    );
    return $sql_array;
}

// Example 3: Show only users with 'subscriber' role
add_filter( 'better_messages_search_user_sql_condition', 'only_subscribers', 10, 4 );
function only_subscribers( $sql_array, $user_ids, $search, $user_id ){
    global $wpdb;
    $sql_array[] = $wpdb->prepare(
        "AND ID IN (SELECT user_id FROM {$wpdb->usermeta} WHERE meta_key = %s AND meta_value LIKE %s)",
        $wpdb->prefix . 'capabilities',
        '%subscriber%'
    );
    return $sql_array;
}
```

---

### `better_messages_search_users_limit` {#better_messages_search_users_limit}

Maximum number of users returned in search. Default `50`.

**Parameters:**
- `$limit` *(int)* — Default `50`

**Returns:** `int`

---

## Files & Attachments

### `better_messages_attachment_url` {#better_messages_attachment_url}

Filters attachment URLs before returning them to the frontend. Use this to proxy attachments through a CDN, add authentication tokens to URLs, or implement signed URLs for secure file access.

**Parameters:**
- `$url` *(string)* — Attachment URL
- `$attachment_id` *(int)* — Attachment ID
- `$message_id` *(int)* — Message ID
- `$thread_id` *(int)* — Thread ID

**Returns:** `string`

```php
add_filter( 'better_messages_attachment_url', 'cdn_attachment_url', 10, 4 );
function cdn_attachment_url( $url, $attachment_id, $message_id, $thread_id ){
    return str_replace( home_url(), 'https://cdn.example.com', $url );
}
```

---

### `bp_better_messages_attachment_allowed_extensions` {#bp_better_messages_attachment_allowed_extensions}

Filters the allowed file extensions for message attachments. Default comes from the `attachmentsFormats` plugin setting. Receives the thread ID and user ID, allowing per-thread or per-user file type restrictions.

**Parameters:**
- `$extensions` *(array|string)* — From `attachmentsFormats` setting
- `$thread_id` *(int)* — Thread ID
- `$user_id` *(int)* — User ID

**Returns:** `array|string`

```php
add_filter( 'bp_better_messages_attachment_allowed_extensions', 'allow_pdf', 10, 3 );
function allow_pdf( $extensions, $thread_id, $user_id ){
    if( is_string( $extensions ) ){
        $extensions .= ',pdf';
    }
    return $extensions;
}
```

---

### `bp_better_messages_attachment_max_size` {#bp_better_messages_attachment_max_size}

Filters the maximum file size in megabytes for message attachments. Default comes from the `attachmentsMaxSize` plugin setting. Receives the thread ID and user ID, allowing per-user upload limits (e.g., premium users get larger uploads).

**Parameters:**
- `$max_size_mb` *(int|float)* — From `attachmentsMaxSize` setting
- `$thread_id` *(int)* — Thread ID
- `$user_id` *(int)* — User ID

**Returns:** `int|float`

```php
add_filter( 'bp_better_messages_attachment_max_size', 'premium_upload_size', 10, 3 );
function premium_upload_size( $max_size, $thread_id, $user_id ){
    if( my_is_premium_user( $user_id ) ){
        return 50; // 50MB for premium
    }
    return $max_size;
}
```

---

### `bp_better_messages_upload_dir_name` {#bp_better_messages_upload_dir_name}

Filters the base upload directory name. Default `'bp-better-messages'`.

**Parameters:**
- `$dir_name` *(string)* — Default `'bp-better-messages'`

**Returns:** `string`

---

### `better_messages_ensure_file_is_not_from_other_gallery` {#better_messages_ensure_file_is_not_from_other_gallery}

Controls attachment ownership security check. Default `true`.

**Parameters:**
- `$enable_check` *(bool)* — Default `true`

**Returns:** `bool`

---

## AI

### `better_messages_ai_bot_instruction` {#better_messages_ai_bot_instruction}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Filters the system instruction/prompt sent to the AI provider. Applies to all providers (OpenAI, Anthropic, Gemini).

:::note Renamed in 2.15.0
Previously named `better_messages_open_ai_bot_instruction` (3 args). The old name still works as a deprecated alias.
:::

**Parameters:**
- `$instruction` *(string)* — Bot instruction from settings
- `$bot_id` *(int)* — AI bot ID
- `$user_id` *(int)* — User the bot is replying to
- `$thread_id` *(int)* — Conversation thread ID *(added in 2.15.0)*
- `$message_id` *(int)* — ID of the user message that triggered this response *(added in 2.15.0)*

**Returns:** `string`

**Example — append the user's name:**

```php
add_filter( 'better_messages_ai_bot_instruction', 'dynamic_instruction', 10, 5 );
function dynamic_instruction( $instruction, $bot_id, $user_id, $thread_id, $message_id ){
    $user = get_user_by( 'id', $user_id );
    return $instruction . "\nThe user's name is " . $user->display_name;
}
```

**Example — read the triggering user message:**

```php
add_filter( 'better_messages_ai_bot_instruction', 'instruction_with_user_message', 10, 5 );
function instruction_with_user_message( $instruction, $bot_id, $user_id, $thread_id, $message_id ){
    $message = Better_Messages()->functions->get_message( $message_id );
    if ( ! $message ) return $instruction;

    return $instruction . "\nThe user just wrote: " . wp_strip_all_tags( $message->message );
}
```

---

### `better_messages_ai_providers_info` {#better_messages_ai_providers_info}

Filters the list of AI providers shown in the bot editor. Use it to register custom providers alongside the built-in OpenAI, Anthropic and Gemini providers.

**Parameters:**
- `$providers` *(array)* — Sequential array of provider info arrays. Each item must contain `id`, `name`, `features` and `hasGlobalKey`.

**Returns:** `array`

See the full walkthrough in [Add a custom AI provider](/docs/development/guides/custom-ai-provider/).

```php
add_filter( 'better_messages_ai_providers_info', 'add_custom_provider' );
function add_custom_provider( $providers ){
    $providers[] = array(
        'id'           => 'my_provider',
        'name'         => 'My Custom AI',
        'features'     => array( 'temperature', 'maxOutputTokens' ),
        'hasGlobalKey' => true,
    );
    return $providers;
}
```

---

### `better_messages_ai_provider_create` {#better_messages_ai_provider_create}

Creates a custom AI provider instance. Return `null` for unknown providers.

**Parameters:**
- `$provider` *(null|Better_Messages_AI_Provider)* — Default `null`
- `$provider_id` *(string)* — Provider identifier

**Returns:** `Better_Messages_AI_Provider|null`

---

### `better_messages_ai_provider_global_key` {#better_messages_ai_provider_global_key}

Returns the global API key for a custom AI provider.

**Parameters:**
- `$api_key` *(string)* — Default empty string
- `$provider_id` *(string)* — Provider identifier

**Returns:** `string`

---

## E-commerce Integrations

### `better_messages_dokan_store_default` {#better_messages_dokan_store_default}

Whether Dokan vendor store messaging is enabled by default. Default `true`.

**Parameters:**
- `$enabled` *(bool)* — Default `true`
- `$store_id` *(int)* — Vendor store ID

**Returns:** `bool`

---

### `better_messages_wcfm_store_default` {#better_messages_wcfm_store_default}

Whether WCFM vendor messaging is enabled by default. Default `true`.

**Parameters:**
- `$enabled` *(bool)* — Default `true`
- `$vendor_id` *(int)* — Vendor ID

**Returns:** `bool`

---

### `better_messages_wc_vendors_store_default` {#better_messages_wc_vendors_store_default}

Whether WC Vendors messaging is enabled by default. Default `true`.

**Parameters:**
- `$enabled` *(bool)* — Default `true`
- `$store_id` *(int)* — Store ID

**Returns:** `bool`

---

### `better_messages_multivendorx_store_default` {#better_messages_multivendorx_store_default}

Whether MultiVendorX vendor messaging is enabled by default. Default `true`.

**Parameters:**
- `$enabled` *(bool)* — Default `true`
- `$store_id` *(int)* — Store ID

**Returns:** `bool`

---

## Plugin Configuration

### `bp_better_messages_overwrite_settings` {#bp_better_messages_overwrite_settings}

Overrides all plugin settings programmatically.

**Parameters:**
- `$settings` *(array)* — All loaded plugin options

**Returns:** `array`

```php
add_filter( 'bp_better_messages_overwrite_settings', 'override_settings' );
function override_settings( $settings ){
    $settings['messagesHeight'] = 500;
    $settings['disableSubject'] = '1';
    return $settings;
}
```

---

### `bp_better_messages_fast` {#bp_better_messages_fast}

Whether to use "fast" mode optimization. Default `'1'`.

**Parameters:**
- `$fast` *(string)* — `'0'` or `'1'`

**Returns:** `string`

---

### `better_messages_replace_buddypress` {#better_messages_replace_buddypress}

Whether to replace BuddyPress native messaging. Default `true`.

**Parameters:**
- `$replace` *(bool)* — Default `true`

**Returns:** `bool`

---

### `better_messages_replace_buddyboss` {#better_messages_replace_buddyboss}

Whether to replace BuddyBoss native messaging. Default `true`.

**Parameters:**
- `$replace` *(bool)* — Default `true`

**Returns:** `bool`

---

### `better_messages_onesignal_integration` {#better_messages_onesignal_integration}

Whether to load the [OneSignal integration](/docs/integrations/onesignal/) when the OneSignal WordPress plugin is detected. Default `true`. Return `false` to fully disable the integration — Better Messages will not load the frontend script which associates WordPress user IDs with OneSignal subscriptions (`OneSignal.login()` / External ID mapping), will not register its OneSignal REST endpoint, and will not route message push notifications through OneSignal (the built-in [Web Push add-on](/docs/websocket/web-push/) is used instead, when enabled).

Available since version 2.15.23.

**Parameters:**
- `$enabled` *(bool)* — Default `true`

**Returns:** `bool`

```php
add_filter( 'better_messages_onesignal_integration', '__return_false' );
```

---

### `better_messages_fluent_notify_integration` {#better_messages_fluent_notify_integration}

Whether to load the [FluentNotify integration](/docs/integrations/fluent-notify/) when a configured FluentNotify is detected. Default `true`. Return `false` to fully disable the integration — Better Messages will not route message or call push notifications through FluentNotify (the built-in [Web Push add-on](/docs/websocket/web-push/) is used instead, when enabled).

Available since version 2.15.32.

**Parameters:**
- `$enabled` *(bool)* — Default `true`

**Returns:** `bool`

```php
add_filter( 'better_messages_fluent_notify_integration', '__return_false' );
```

---

### `better_messages_user_config` {#better_messages_user_config}

Filters the user-facing settings available in the messaging preferences panel. Each setting is an object with `id`, `title`, `type`, and `options` array. Use this to add custom user preferences (e.g., message sound choice, notification frequency).

**Parameters:**
- `$settings` *(array)* — Array of setting objects (id, title, type, options)

**Returns:** `array`

---

### `better_messages_script_dependencies` {#better_messages_script_dependencies}

Filters the WordPress script dependencies for the main Better Messages JavaScript bundle. Default is `['wp-hooks', 'better-messages-react']`. Add your own script handles to ensure they load before Better Messages initializes.

**Parameters:**
- `$deps` *(array)* — Default `['wp-hooks', 'better-messages-react']`

**Returns:** `array`

---

### `better_messages_style_dependencies` {#better_messages_style_dependencies}

Filters style dependencies. Default empty array.

**Parameters:**
- `$deps` *(array)* — Default empty array

**Returns:** `array`

---

### `bp_better_messages_script_variables` {#bp_better_messages_script_variables}

Filters global JavaScript variables passed to the frontend.

**Parameters:**
- `$variables` *(array)* — Settings, user data, URLs, feature flags

**Returns:** `array`

```php
add_filter( 'bp_better_messages_script_variables', 'add_frontend_data' );
function add_frontend_data( $vars ){
    $vars['myCustomData'] = array( 'key' => 'value' );
    return $vars;
}
```

---

## Server & Infrastructure

### `better_messages_realtime_server` {#better_messages_realtime_server}

Overrides the WebSocket server URL, for a self-hosted server. From 3.1 it also moves the requests the site itself makes to the server, not only the connection of the browsers.

**Parameters:**
- `$url` *(string)* — Default from 3.1: `'https://ws.wordplus.cloud/'` (WordPlus Cloud) for the connection of the browsers, and `'https://rest.wordplus.cloud/'` for the requests of the site itself. Before 3.1: `'https://cloud.better-messages.com/'`

**Returns:** `string`

---

### `better_messages_turn_server` {#better_messages_turn_server}

Overrides the TURN server for video/audio calls.

**Parameters:**
- `$url` *(string)* — Default from 3.1: `'turn.rtc.wordplus.cloud'`. Before 3.1: `'turn.bpbettermessages.com'`

**Returns:** `string`

---

### `better_messages_video_server` {#better_messages_video_server}

Overrides the video conferencing server URL.

**Parameters:**
- `$url` *(string)* — Default from 3.1: `'video.rtc.wordplus.cloud'`. Before 3.1: `'video-cloud.better-messages.com'`

**Returns:** `string`

---

### `better_messages_mobile_app_builder_server` {#better_messages_mobile_app_builder_server}

Overrides the mobile app builder server URL.

**Parameters:**
- `$url` *(string)* — Default `'https://builder.better-messages.com'`

**Returns:** `string`

---

### `better_messages_realtime_server_send_data` {#better_messages_realtime_server_send_data}

Filters the complete data payload sent to the realtime WebSocket server when a new message is created. Includes message content, sender info, thread data, and encryption keys. Use this to add custom data that needs to be broadcast in real-time to recipients.

**Parameters:**
- `$data` *(array)* — Message data payload
- `$message` *(object)* — Message object

**Returns:** `array`

---

### `better_messages_realtime_server_message_deleted_data` {#better_messages_realtime_server_message_deleted_data}

Filters the data payload sent to the realtime WebSocket server when a message is deleted. The default payload includes `site_id`, `secret_key`, and `message_id`. Use this to add custom data to the deletion broadcast.

**Parameters:**
- `$data` *(array)* — Deletion event payload (site_id, secret_key, message_id)
- `$message_id` *(int)* — Deleted message ID

**Returns:** `array`

---

### `better_messages_thread_self_update_extra` {#better_messages_thread_self_update_extra}

Adds extra data to thread self-update WebSocket messages.

**Parameters:**
- `$extra` *(array)* — Default empty array
- `$thread_id` *(int)* — Thread ID
- `$user_id` *(int)* — User ID

**Returns:** `array`

---

## Mobile App

### `better_messages_mobile_settings` {#better_messages_mobile_settings}

Filters mobile app settings sent to the frontend. Use this to customize the mobile app login screen branding and legal text.

**Parameters:**
- `$settings` *(array)* — Keys: `loginLogo`, `loginLogoExtension`, `loginLogoDark`, `loginLogoDarkExtension`, `termsAndConditions`, `loginMethods`, `webSignInUrl`, `webSignInReturn`, `openUrlPrefix`, `appLock`, `appLockAfter`, `accountDeletion`, `siteName`, `siteIcon` and `loginBackground` (since 3.2.0 for all but the first three)

**Returns:** `array`

---

### `better_messages_mobile_app_login_methods` {#better_messages_mobile_app_login_methods}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Filters the sign-in methods of the mobile app, set in Mobile App, General, Sign-in methods. With `website`, the password form is off on the site too, so a password sign-in from any build of the app is refused. See [Sign-in and two-factor authentication](/docs/mobile-app/sign-in/). Since 3.2.0.

**Parameters:**
- `$methods` *(string)* — `both`, `website` or `password`

**Returns:** `string`

```php
add_filter( "better_messages_mobile_app_login_methods", function( $methods ) {
    return "website";
} );
```

---

### `better_messages_mobile_app_login_url` {#better_messages_mobile_app_login_url}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Filters the login page that website sign-in opens for a visitor who is not logged in to the site. Use it when members log in on a page of your own instead of `wp-login.php`. Keep the address to return to, or the visitor does not come back to the app. Since 3.2.0.

**Parameters:**
- `$login_url` *(string)* — `wp_login_url()` with the return address as `redirect_to`
- `$return` *(string)* — The address to return to after login

**Returns:** `string`

```php
add_filter( "better_messages_mobile_app_login_url", function( $login_url, $return ) {
    return add_query_arg( "redirect_to", rawurlencode( $return ), home_url( "/login/" ) );
}, 10, 2 );
```

---

### `better_messages_mobile_app_authenticate` {#better_messages_mobile_app_authenticate}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Runs before the password check of the password form of the mobile app. The form does not run the WordPress `authenticate` filters, because CAPTCHA and two-factor plugins hook there and would refuse every app sign-in. A `WP_Error` fires `wp_login_failed` like a wrong password. Since 3.2.0.

**Parameters:**
- `$result` *(null)* — `null`
- `$login` *(string)* — The username or email typed
- `$password` *(string)* — The password typed
- `$device` *(array)* — The device the app sends
- `$request` *(WP_REST_Request)* — The request

**Returns:** `null|WP_User|WP_Error` — `null` to go on with the password check, a `WP_User` to sign that user in, a `WP_Error` to refuse with its message

---

### `better_messages_mobile_app_login_limits` {#better_messages_mobile_app_login_limits}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Filters the failure limits of the password form of the mobile app. Since 3.2.0.

**Parameters:**
- `$limits` *(array)* — `account` (5): failures for one account from one address, `ip` (30): failures from one address, `window` (900): seconds the failures count for and the lock lasts

**Returns:** `array`

---

### `better_messages_mobile_app_login_ip` {#better_messages_mobile_app_login_ip}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Filters the address the failure limits of the mobile app count by. By default it is `REMOTE_ADDR`, or when that is a private or local address, the first public address in `X-Forwarded-For`, then `X-Real-IP`. Since 3.2.0.

**Parameters:**
- `$ip` *(string)* — The address

**Returns:** `string`

On a site that is reachable only through Cloudflare:

```php
add_filter( "better_messages_mobile_app_login_ip", function( $ip ) {
    return isset( $_SERVER["HTTP_CF_CONNECTING_IP"] ) ? sanitize_text_field( $_SERVER["HTTP_CF_CONNECTING_IP"] ) : $ip;
} );
```

---

### `better_messages_mobile_app_can_login` {#better_messages_mobile_app_can_login}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Filters whether a member may sign in to the mobile app, for both the password form and website sign-in. Any value but `true` refuses. Since 3.2.0.

**Parameters:**
- `$allowed` *(bool)* — `true`
- `$user` *(WP_User)* — The member
- `$device` *(array)* — The device the app sends
- `$method` *(string)* — `password` or `website`

**Returns:** `bool|WP_Error` — a `WP_Error` refuses with its message

---

### `better_messages_mobile_app_sign_out_on_password_change` {#better_messages_mobile_app_sign_out_on_password_change}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Filters whether a password change signs out every app device of the member, set in Mobile App, General, Sign out on password change (on by default). Since 3.2.0.

**Parameters:**
- `$enabled` *(bool)* — The setting

**Returns:** `bool`

---

### `better_messages_mobile_app_lock` {#better_messages_mobile_app_lock}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Filters the app lock of the site, set in Mobile App, General, Security. See [App lock](/docs/mobile-app/app-lock/). Since 3.2.0.

**Parameters:**
- `$lock` *(array)* — `mode`: `off`, `choice` or `required` (an unknown mode counts as `choice`), `after`: seconds in the background before the app asks again, from 0 to a day

**Returns:** `array`

```php
add_filter( "better_messages_mobile_app_lock", function( $lock ) {
    $lock["mode"]  = "required";
    $lock["after"] = 60;

    return $lock;
} );
```

---

### `better_messages_mobile_app_account_deletion` {#better_messages_mobile_app_account_deletion}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Filters what Delete Account does in the mobile app, set in Mobile App, General, Accounts. See [Delete Account](/docs/mobile-app/delete-account/). Since 3.2.0.

**Parameters:**
- `$mode` *(string)* — `delete`, `request` or `off`

**Returns:** `string`

---

### `better_messages_mobile_app_can_delete_account` {#better_messages_mobile_app_can_delete_account}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Filters whether a member may delete their account, or send a request for it, from the mobile app. Administrators are refused before this filter. Since 3.2.0.

**Parameters:**
- `$allowed` *(bool)* — `true`
- `$user` *(WP_User)* — The member
- `$mode` *(string)* — `delete` or `request`

**Returns:** `bool|WP_Error` — a `WP_Error` refuses with its message, which the app shows

```php
add_filter( "better_messages_mobile_app_can_delete_account", function( $allowed, $user, $mode ) {
    if ( $mode === "delete" && function_exists( "wc_get_orders" ) && wc_get_orders( array( "customer_id" => $user->ID, "status" => array( "processing", "on-hold" ), "limit" => 1 ) ) ) {
        return new WP_Error( "open_orders", "Your account can be deleted once your open orders are complete." );
    }

    return $allowed;
}, 10, 3 );
```

---

### `better_messages_mobile_app_login_background` {#better_messages_mobile_app_login_background}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Filters the background of the login and lock screens of the mobile app, set in Mobile App, General, Login screen. The values are checked again after the filter. See [Login screen](/docs/mobile-app/login-screen/). Since 3.2.0.

**Parameters:**
- `$background` *(array)* — `loginBackground` (`plain` or `glow`), `loginGlowColor` and `loginGlowColorDark` (`#rrggbb`, empty for the accent color), `loginGlowStrength` (5 to 60), `loginGlowSpread` (50 to 200) and `loginGlowPosition` (`logo`, `top` or `both`)

**Returns:** `array`

---

### `better_messages_mobile_app_open_url` {#better_messages_mobile_app_open_url}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Filters where a `/bm/open/` address of the site leads in the browser, on a phone without the app or on a computer. An empty address leads to the home page. See [Links that open the app](/docs/mobile-app/app-links/). Since 3.2.0.

**Parameters:**
- `$url` *(string)* — The messenger address, or the login page for a visitor
- `$type` *(string)* — `messages`, `conversation` or `user`
- `$id` *(int)* — The conversation or user id, `0` for `messages`

**Returns:** `string`

---

### `better_messages_mobile_app_apple_association` {#better_messages_mobile_app_apple_association}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Filters the content of `/.well-known/apple-app-site-association` that the site serves for the iOS app: `applinks` for the `/bm/open/` addresses and `webcredentials` for website sign-in. Since 3.2.0.

**Parameters:**
- `$data` *(array)* — The file as an array, empty when the Team ID or the App IDs are not set

**Returns:** `array`

---

### `better_messages_mobile_app_asset_links` {#better_messages_mobile_app_asset_links}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Filters the statements of `/.well-known/assetlinks.json` that the site serves for the Android app. Since 3.2.0.

**Parameters:**
- `$statements` *(array)* — One statement for each package, with the upload key and Play App Signing fingerprints

**Returns:** `array`

---

### `better_messages_mobile_app_script_variables` {#better_messages_mobile_app_script_variables}

Filters all script initialization variables for both mobile app and web frontend. This is the complete configuration object passed to the JavaScript application. Applied after the mobile-specific settings are merged.

**Parameters:**
- `$variables` *(array)* — Complete frontend initialization config

**Returns:** `array`

---

## Customization & Theming

### `better_messages_css_customizations` {#better_messages_css_customizations}

Allows adding custom CSS rules to the plugin output. This filter also works in Better Messages mobile applications — it is the way to apply custom CSS styles to mobile apps.

**Parameters:**
- `$rules` *(array)* — Array of CSS rule strings

**Returns:** `array`

```php
add_filter( 'better_messages_css_customizations', 'add_custom_css' );
function add_custom_css( $rules ){
    // Customize font size using CSS variables
    $rules[] = ':root{--bm-message-font-size: 16px;--bm-message-line-height: 20px;}';

    // Reverse camera video in calls
    $rules[] = '.bp-messages-wrap .bp-messages-video-container video[datatype="camera"]{ transform: scaleX(-1); }';

    return $rules;
}
```

---

### `better_messages_login_url` {#better_messages_login_url}

Customizes the login URL shown to unauthenticated users.

**Parameters:**
- `$url` *(string)* — Default from `wp_login_url()`

**Returns:** `string`

```php
add_filter( 'better_messages_login_url', 'custom_login_url' );
function custom_login_url( $url ){
    return home_url( '/my-login-page/' );
}
```

---

### `better_messages_registration_url` {#better_messages_registration_url}

Customizes the registration URL.

**Parameters:**
- `$url` *(string)* — Default from `wp_registration_url()`

**Returns:** `string`

```php
add_filter( 'better_messages_registration_url', 'custom_register_url' );
function custom_register_url( $url ){
    return home_url( '/register/' );
}
```

---

### `bp_better_messages_max_height` {#bp_better_messages_max_height}

Customizes the maximum height (px) of message containers.

**Parameters:**
- `$height` *(int)* — Default from `messagesHeight` setting

**Returns:** `int`

---

### `bp_better_messages_page` {#bp_better_messages_page}

Overrides the messages page URL. Return `null` for default.

**Parameters:**
- `$url` *(string|null)* — Default `null`
- `$user_id` *(int)* — User ID

**Returns:** `string|null`

---

### `bp_better_messages_sounds_assets` {#bp_better_messages_sounds_assets}

Customizes the base URL for notification sounds.

**Parameters:**
- `$url` *(string)* — Default plugin's `assets/sounds/` directory

**Returns:** `string`

---

### `bp_better_messages_time_locale` {#bp_better_messages_time_locale}

Customizes the locale for timestamp formatting.

**Parameters:**
- `$locale` *(string)* — Sanitized WordPress locale

**Returns:** `string`

---

### `bp_better_messages_current_template` {#bp_better_messages_current_template}

Overrides template file path for group page rendering.

**Parameters:**
- `$template_path` *(string)* — Full path to template
- `$template_name` *(string)* — Template filename

**Returns:** `string`

---

### `bp_better_messages_views_path` {#bp_better_messages_views_path}

Overrides the base path for template/view files.

**Parameters:**
- `$path` *(string)* — Default plugin's `/views/` directory

**Returns:** `string`

---

### `bp_better_messages_all_statuses` {#bp_better_messages_all_statuses}

Filters the available user status options displayed in the status selector. Each status has `name`, `icon`, and `color` properties. Use this to add custom statuses (e.g., "In a meeting", "Do not disturb") or remove default ones.

**Parameters:**
- `$statuses` *(array)* — Status definitions with name, icon, color

**Returns:** `array`

---

### `better_messages_custom_tabs` {#better_messages_custom_tabs}

Filters the [custom navigation tabs](/docs/features/custom-tabs/) of the member viewing the page: the admin's tabs, already without the ones hidden from that member's role, before they are sent to the browser. Add tabs here that need what only the server knows, a membership level or a capability, or change and drop the admin's tabs for some members.

It runs again when a content tab is opened, so a tab you add here is also one whose content the site serves, and a member it is not given to cannot ask for that content.

**Parameters:**
- `$tabs` *(array)* — The tabs, each an array:
  - `key` *(string)* — Unique. The admin's tabs have keys starting with `ct_`
  - `label` *(string)*
  - `icon` *(string)* — A preset name from the icon picker or SVG markup, empty for the stock glyph
  - `type` *(string)* — `link`, `page`, `content` or `custom`. A `custom` tab has no address: your script draws it, see below. Since 3.2.0 for `custom`
  - `url` *(string)* — For `link` and `page`
  - `newWindow` *(bool)* — For `link`
  - `bars` *(array)* — The bars the tab shows on: any of `mini`, `side`, `mobile`
  - `content` *(string)* — For `content`: text, HTML and shortcodes, rendered for the member who opens the tab. Never sent with the page
  - `content_callback` *(callable, optional)* — For `content`, instead of `content`: called as `callback( $tab, $user_id )` and returns the HTML
  - `guestWall` *(bool, optional)* — `false` leaves the tab open to a visitor who has not signed in, while the sign-in wall still covers the rest of the messenger. Any other value is dropped. Since 3.2.0
- `$user_id` *(int)* — The member, negative for a guest and `0` for a visitor who is not one yet

**Returns:** `array`

```php
add_filter( 'better_messages_custom_tabs', 'my_members_area_tab', 10, 2 );
function my_members_area_tab( $tabs, $user_id ){
    if ( $user_id <= 0 || ! function_exists( 'pmpro_hasMembershipLevel' ) || ! pmpro_hasMembershipLevel( null, $user_id ) ) {
        return $tabs;
    }

    $tabs[] = array(
        'key'              => 'members-area',
        'label'            => 'My membership',
        'icon'             => 'star',
        'type'             => 'content',
        'bars'             => array( 'side', 'mobile' ),
        'content_callback' => function( $tab, $user_id ) {
            return do_shortcode( '[pmpro_account sections="membership,invoices"]' );
        },
    );

    return $tabs;
}
```

A tab of the type `custom` is how a plugin decides on the server who gets its tab and on which bars, and draws the tab in the browser. Your script gives the tab its `render` or `onClick` by its key in [`better_messages_navigation_tabs`](/hooks/js-filters#better_messages_navigation_tabs), and until it does, the tab stays off the bars. The admin cannot make a `custom` tab in Appearance. See [A tab drawn by your own script](/docs/development/guides/custom-tabs/#a-tab-drawn-by-your-own-script) and [A tab a visitor can open before signing in](/docs/development/guides/custom-tabs/#a-tab-a-visitor-can-open-before-signing-in). Since 3.2.0.

```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' ),
        'guestWall' => false,
    );

    return $tabs;
}, 10, 2 );
```

:::info

Available since Better Messages 3.1.5. To change the built-in tabs, or any tab in the browser, use the JavaScript filter [`better_messages_navigation_tabs`](/hooks/js-filters#better_messages_navigation_tabs).

:::

---

### `better_messages_navigation_tab_content` {#better_messages_navigation_tab_content}

Filters the HTML a content tab shows, after its shortcodes ran, for the member who opened it.

**Parameters:**
- `$html` *(string)* — The rendered content
- `$tab` *(array)* — The tab, as [`better_messages_custom_tabs`](#better_messages_custom_tabs) describes it
- `$user_id` *(int)* — The member who opened the tab

**Returns:** `string`

```php
add_filter( 'better_messages_navigation_tab_content', 'my_tab_greeting', 10, 3 );
function my_tab_greeting( $html, $tab, $user_id ){
    if ( $tab['key'] !== 'ct_k3f9a2' || $user_id <= 0 ) {
        return $html;
    }

    $user = get_userdata( $user_id );

    return 'Hello, ' . esc_html( $user->display_name ) . '' . $html;
}
```

:::info

Available since Better Messages 3.1.5.

:::

---

### `better_messages_total_unread` {#better_messages_total_unread}

Filters the unread count that the button opening the messenger on a phone is printed with, as the member's total. A plugin with unread messages of its own, shown in a navigation tab of its own say, adds them here. Once the page runs, the JavaScript filter of the same name, [`better_messages_total_unread`](/hooks/js-filters#better_messages_total_unread), does the same for the page title, every `.bm-menu-unread` counter and the mini widgets bubble. See [Add your unread messages to the total](/docs/development/guides/custom-tabs/#add-your-unread-messages-to-the-total). Since 3.2.0.

**Parameters:**
- `$count` *(int)* — The conversations with unread messages of the member. `0` on the WebSocket version, where the browser counts them once the page runs
- `$user_id` *(int)* — The member, negative for a guest and `0` for a visitor who is not one yet

**Returns:** `int` — a negative value counts as `0`

```php
add_filter( 'better_messages_total_unread', function( $count, $user_id ){
    return $count + my_plugin_unread_count( $user_id );
}, 10, 2 );
```

---

### `better_messages_tab_offers` {#better_messages_tab_offers}

Lets a plugin that brings a navigation tab of its own offer it to the administrator in the Better Messages settings: a card in **Appearance → Mini widgets** while the tab is off, a pinned first row of each bar list it is on, and the same offer in **Integrations → Other Plugins** and **Get started → Plugins on this site**. Better Messages stores nothing of it. It posts to your routes when the administrator answers and asks the filter again afterwards. See [Offering your tab to the administrator](/docs/development/guides/custom-tabs/#offering-your-tab-to-the-administrator). Since 3.2.0.

**Parameters:**
- `$offers` *(array)* — Empty by default. Each offer is an array:
  - `key` *(string, required)* — The tab's key on the bars: letters, digits, `_` and `-`
  - `plugin` *(string, required)* — Your plugin's name
  - `label` *(string, required)* — The tab's name
  - `icon` *(string)* — The address of your plugin's icon
  - `text` *(string)* — What the tab brings, one line
  - `on` *(bool)* — Whether the tab is on now
  - `bars` *(array)* — Where it shows once on: any of `mini`, `side`, `mobile`, all three by default
  - `settings_url` *(string)* — Your settings page, linked from the pinned row once the tab is on
  - `enable` *(array)* — `url` and `data`: **Turn on** posts `data` as JSON to `url` with the administrator's REST nonce
  - `dismiss` *(array)* — `url` and `data`: **Not now** posts the same way

**Returns:** `array`

```php
add_filter( 'better_messages_tab_offers', function( $offers ){
    $offers[] = array(
        'key'          => 'my-chat',
        'plugin'       => 'My Plugin',
        'label'        => 'Support',
        'icon'         => plugins_url( 'icon.png', __FILE__ ),
        'text'         => 'Answer your visitors from the messenger.',
        'on'           => (bool) get_option( 'my_plugin_tab_on' ),
        'bars'         => array( 'mini', 'side', 'mobile' ),
        'settings_url' => admin_url( 'admin.php?page=my-plugin' ),
        'enable'       => array( 'url' => rest_url( 'my-plugin/v1/tab' ), 'data' => array( 'on' => true ) ),
        'dismiss'      => array( 'url' => rest_url( 'my-plugin/v1/tab/dismiss' ), 'data' => array() ),
    );

    return $offers;
} );
```

:::info

`enable.url` and `dismiss.url` must be routes of this site's REST API, as the nonce goes with them, so check `manage_options` in their permission callbacks. An offer without a valid `key`, `plugin` or `label`, an offer that is off with no `enable`, and a second offer with the same key are left out.

:::

---

### `better_messages_design_preview_scripts` {#better_messages_design_preview_scripts}

Names the scripts of your plugin to print in the **Appearance** preview, after Better Messages' own. The preview prints Better Messages' scripts and nothing else of the page, so a tab your script draws shows there only through this filter. Register the scripts as you do for the site's pages, on `init` or `wp_enqueue_scripts`. A handle that is not registered is skipped. In the preview `window.Better_Messages.designPreview` is `'1'`, for a tab that draws a sample in place of live data. See [Your tab in the Appearance preview](/docs/development/guides/custom-tabs/#your-tab-in-the-appearance-preview). Since 3.2.0.

**Parameters:**
- `$handles` *(array)* — Script handles, empty by default
- `$surface` *(string)* — What the preview shows: `desktop`, `mobile` or `widgets`

**Returns:** `array`

```php
add_filter( 'better_messages_design_preview_scripts', function( $handles, $surface ){
    $handles[] = 'my-plugin-tab';
    return $handles;
}, 10, 2 );
```

---

## Emojis & Reactions

### `better_messages_get_emoji_dataset` {#better_messages_get_emoji_dataset}

Filters the emoji dataset available in the emoji picker UI. The dataset is loaded from a JSON file based on the selected emoji set and includes categories and individual emoji data. Use this to add custom emoji categories or remove specific emojis.

**Parameters:**
- `$dataset` *(array)* — Emoji JSON with categories

**Returns:** `array`

---

### `bp_better_messages_reactions_list` {#bp_better_messages_reactions_list}

Filters the available emoji reactions that users can add to messages. Default comes from the `reactionsEmojies` plugin setting as comma-separated Unicode codes. Use this to customize which emoji reactions are available in the reaction picker.

**Parameters:**
- `$reactions` *(string)* — From `reactionsEmojies` setting (comma-separated Unicode codes)

**Returns:** `string|array`

---

## Reports & Moderation

### `better_messages_get_report_reasons` {#better_messages_get_report_reasons}

Filters available report reason categories.

**Parameters:**
- `$reasons` *(array)* — Default: inappropriate, spam, harassment, offensive, other
- `$message_id` *(int)* — Message being reported
- `$thread_id` *(int)* — Thread ID

**Returns:** `array`

```php
add_filter( 'better_messages_get_report_reasons', 'custom_reasons', 10, 3 );
function custom_reasons( $reasons, $message_id, $thread_id ){
    $reasons['scam'] = __( 'Scam or fraud', 'my-plugin' );
    return $reasons;
}
```

---

### `better_messages_report_description_max_length` {#better_messages_report_description_max_length}

Maximum character length for report description. Default `500`.

**Parameters:**
- `$max` *(int)* — Default `500`

**Returns:** `int`

---

### `better_messages_admin_moderation_item` {#better_messages_admin_moderation_item}

Filters moderation item in admin queue display.

**Parameters:**
- `$item` *(array)* — Item data (id, title, message, time, participants)
- `$message` *(array)* — Raw message data

**Returns:** `array`

---

### `better_messages_admin_system_message` {#better_messages_admin_system_message}

Filters system message content in admin moderation view.

**Parameters:**
- `$content` *(string)* — Default `'System message'` HTML
- `$system_type` *(string)* — System message type
- `$message` *(array)* — Message data

**Returns:** `string`

---

## Database & Cleanup

### `better_messages_delete_old_messages_batch_size` {#better_messages_delete_old_messages_batch_size}

Batch size for old message deletion cron. Default `100`.

**Parameters:**
- `$batch_size` *(int)* — Default `100`

**Returns:** `int`

---

### `better_messages_delete_old_voice_messages_batch_size` {#better_messages_delete_old_voice_messages_batch_size}

Batch size for old voice message deletion cron. Default `100`.

**Parameters:**
- `$batch_size` *(int)* — Default `100`

**Returns:** `int`

---

### `better_messages_tables_list` {#better_messages_tables_list}

Filters the list of Better Messages database tables.

**Parameters:**
- `$tables` *(array)* — Table names from migration system

**Returns:** `array`

---

## Notification SQL Query Filters

These filters allow modifying the SQL query that retrieves threads for email notifications. Advanced usage only.

### `better_messages_notifications_threads_select_sql` {#better_messages_notifications_threads_select_sql}

Filters SELECT columns.

**Parameters:** `$select` *(array)*
**Returns:** `array`

### `better_messages_notifications_threads_from_sql` {#better_messages_notifications_threads_from_sql}

Filters FROM clause.

**Parameters:** `$from` *(array)*
**Returns:** `array`

### `better_messages_notifications_threads_where_sql` {#better_messages_notifications_threads_where_sql}

Filters WHERE conditions.

**Parameters:** `$where` *(array)*
**Returns:** `array`

### `better_messages_notifications_threads_group_by_sql` {#better_messages_notifications_threads_group_by_sql}

Filters GROUP BY clause.

**Parameters:** `$group_by` *(array)*
**Returns:** `array`

### `better_messages_notifications_threads_having_sql` {#better_messages_notifications_threads_having_sql}

Filters HAVING clause.

**Parameters:** `$having` *(array)*
**Returns:** `array`

### `better_messages_notifications_threads_order_by_sql` {#better_messages_notifications_threads_order_by_sql}

Filters ORDER BY clause.

**Parameters:** `$order_by` *(array)*
**Returns:** `array`

### `better_messages_notifications_threads_limit_sql` {#better_messages_notifications_threads_limit_sql}

Filters LIMIT clause.

**Parameters:** `$limit` *(array)*
**Returns:** `array`

### `better_messages_notifications_threads_full_sql` {#better_messages_notifications_threads_full_sql}

Filters the complete assembled SQL query string.

**Parameters:** `$sql` *(string)*
**Returns:** `string`

---

## Fluent Community Integration

### `better_messages_fluent_community_group_chat_enabled` {#better_messages_fluent_community_group_chat_enabled}

Whether group chat is enabled for a Fluent Community space. Default `'yes'`.

**Parameters:**
- `$enabled` *(string)* — `'yes'` or `'no'`
- `$space_id` *(int)* — Space ID

**Returns:** `string`

---

### `better_messages_fluent_community_group_chat_user_has_access` {#better_messages_fluent_community_group_chat_user_has_access}

Whether a user has access to a Fluent Community group chat.

**Parameters:**
- `$has_access` *(bool)* — Based on space membership
- `$group_id` *(int)* — Group ID
- `$user_id` *(int)* — User ID

**Returns:** `bool`

---

### `better_messages_fluent_community_group_chat_user_can_moderate` {#better_messages_fluent_community_group_chat_user_can_moderate}

Whether a user can moderate a Fluent Community group chat.

**Parameters:**
- `$can_moderate` *(bool)* — Based on role
- `$group_id` *(int)* — Group ID
- `$user_id` *(int)* — User ID

**Returns:** `bool`

---

### `better_messages_fluent_community_group_chat_members` {#better_messages_fluent_community_group_chat_members}

Filters the member list the self-healing membership sync applies to a Fluent Community Space chat. User IDs removed from the array are taken out of the chat by the sync itself and are not re-added by later enrollment events. Pair with [`better_messages_fluent_community_group_chat_user_has_access`](#better_messages_fluent_community_group_chat_user_has_access) to also deny opening the chat directly.

Available since version 2.15.25.

**Parameters:**
- `$member_ids` *(array)* — WordPress user IDs about to be synced into the chat
- `$space_id` *(int)* — Space ID
- `$thread_id` *(int)* — Better Messages thread ID

**Returns:** `array`

```php
add_filter( 'better_messages_fluent_community_group_chat_members', function( $members, $space_id, $thread_id ) {
    if ( $space_id === 12 ) {
        $members = array_diff( $members, array( 34, 56 ) );
    }
    return $members;
}, 10, 3 );
```

---

### `better_messages_fluent_community_course_chat_enabled` {#better_messages_fluent_community_course_chat_enabled}

Whether group chat is enabled for a Fluent Community course. Default `'yes'`.

**Parameters:**
- `$enabled` *(string)* — `'yes'` or `'no'`
- `$course_id` *(int)* — Course ID

**Returns:** `string`

---

### `better_messages_fluent_community_course_chat_user_has_access` {#better_messages_fluent_community_course_chat_user_has_access}

Whether a user has access to a Fluent Community course chat.

**Parameters:**
- `$has_access` *(bool)* — Based on course enrollment
- `$course_id` *(int)* — Course ID
- `$user_id` *(int)* — User ID

**Returns:** `bool`

---

### `better_messages_fluent_community_course_chat_members` {#better_messages_fluent_community_course_chat_members}

The course chat counterpart of [`better_messages_fluent_community_group_chat_members`](#better_messages_fluent_community_group_chat_members) — filters the member list the membership sync applies to a Fluent Community course chat. Pair with [`better_messages_fluent_community_course_chat_user_has_access`](#better_messages_fluent_community_course_chat_user_has_access) for a complete lock-out.

Available since version 2.15.25.

**Parameters:**
- `$member_ids` *(array)* — WordPress user IDs about to be synced into the chat
- `$course_id` *(int)* — Course ID
- `$thread_id` *(int)* — Better Messages thread ID

**Returns:** `array`

---

## HivePress Integration

### `better_messages_hivepress_menu_item` {#better_messages_hivepress_menu_item}

Filters the HivePress menu item for messages.

**Parameters:**
- `$menu_item` *(array)* — Keys: `label`, `url`, `_order`

**Returns:** `array`

---

## LearnDash Integration

### `better_messages_learndash_group_chat_enabled` {#better_messages_learndash_group_chat_enabled}

Whether a LearnDash Group has a group chat while no choice is saved in the **Group Chat** switch of its **Settings** tab. Default `'yes'`. A group saved with the switch keeps that choice whatever the filter returns. Applies while **LearnDash Group Chat** is enabled. See [Choosing the groups that have a chat](/docs/integrations/learndash/#choosing-the-groups-that-have-a-chat). Since 3.2.0.

**Parameters:**
- `$enabled` *(string)* — `'yes'` or `'no'`
- `$group_id` *(int)* — LearnDash Group ID

**Returns:** `string`

**Example — every group starts with the switch off:**

```php
add_filter( 'better_messages_learndash_group_chat_enabled', function ( $enabled, $group_id ) {
    return 'no';
}, 10, 2 );
```

**Example — groups 123 and 456 start with the switch on, the others off:**

```php
add_filter( 'better_messages_learndash_group_chat_enabled', function ( $enabled, $group_id ) {
    return in_array( (int) $group_id, array( 123, 456 ), true ) ? 'yes' : 'no';
}, 10, 2 );
```

---

## Better Messages PHP Functions Reference — Better_Messages() API

# PHP Functions Reference

:::info REQUIREMENTS

To be able to implement this guide, you need to learn how to insert PHP snippets to your website.

You can find guide here: [WP Beginner](https://www.wpbeginner.com/beginners-guide/beginners-guide-to-pasting-snippets-from-the-web-into-wordpress/)

:::

This page lists all public PHP functions available in the Better Messages plugin. Use these to programmatically manage conversations, messages, participants, and more.

---

## Sending Messages

### `new_message` {#new_message}

Sends a new reply to an existing conversation or creates a new conversation with a first message.

**Starting a new conversation:**

```php
$sender_id  = get_current_user_id();
$recipients = [2, 3, 4];
$content    = 'new conversation message content';
$subject    = 'Subject';

$thread_id = Better_Messages()->functions->new_message([
    'sender_id'    => $sender_id,
    'content'      => $content,
    'subject'      => $subject,
    'recipients'   => $recipients,
    'return'       => 'thread_id',
    'error_type'   => 'wp_error'
]);

if ( is_wp_error( $thread_id ) ) {
    $error = $thread_id->get_error_message();
    // Process error
} else {
    // Thread created
}
```

**Replying to an existing conversation:**

```php
$sender_id  = get_current_user_id();
$thread_id  = 6620;
$content    = 'new message content';

$message_id = Better_Messages()->functions->new_message([
    'sender_id'    => $sender_id,
    'thread_id'    => $thread_id,
    'content'      => $content,
    'return'       => 'message_id',
    'error_type'   => 'wp_error'
]);

if ( is_wp_error( $message_id ) ) {
    $error = $message_id->get_error_message();
    // Process error
} else {
    // Message created
}
```

**Pre-moderation:** `new_message()` applies the site's **Pre-Moderation** settings to the sender, the same way the messenger does. A message from a sender who must be moderated is saved as pending and waits for approval in the Administration page. Two arguments change this:

- `'skip_moderation' => true` sends the message straight away. Use it for automatic messages that pre-moderation should never hold, such as a notice your plugin sends in the member's name. A message sent this way does not count as the sender's approved message under **First-Time Senders**.
- `'is_pending' => 0` or `1` sets the state yourself. Pre-moderation is not checked, and the value is kept as given.

```php
Better_Messages()->functions->new_message([
    'sender_id'       => $sender_id,
    'thread_id'       => $thread_id,
    'content'         => 'Your order has shipped',
    'skip_moderation' => true,
]);
```

---

## Creating Conversations

### `create_new_conversation` {#create_new_conversation}

Creates a new empty conversation programmatically and returns the conversation ID.

**Parameters:**
- `$user_ids` *(array)* — Array of user IDs to include
- `$subject` *(string)* — Conversation subject

**Returns:** `int|false` — Thread ID on success, `false` on failure

```php
$user_ids = [1, 2, 3];
$subject  = 'Conversation Subject';

$thread_id = Better_Messages()->functions->create_new_conversation( $user_ids, $subject );
```

---

### `get_private_conversation_id` {#get_private_conversation_id}

Gets an existing private conversation with a user, or creates one if it doesn't exist.

**Parameters:**
- `$to` *(int)* — Recipient user ID
- `$from` *(int|null)* — Sender/initiator user ID. Default `null` (current user)
- `$create` *(bool)* — Whether to create if not found. Default `true`
- `$subject` *(string)* — Subject for new conversations. Default `''`
- `$uniqueKey` *(string|null)* — Optional unique key for context-specific conversations. Default `null`

**Returns:** `array` — Result with `result` key (`'thread_found'`, `'thread_created'`, or `'not_allowed'`) and `thread_id` or `errors`

```php
$to      = 3;
$from    = get_current_user_id();
$create  = true;
$subject = 'New conversation subject';

$result = Better_Messages()->functions->get_private_conversation_id( $to, $from, $create, $subject );

switch( $result['result'] ){
    case 'thread_created':
    case 'thread_found':
        $thread_id = $result['thread_id'];
        // Do something with thread ID
        break;

    case 'not_allowed':
        $errors = $result['errors'];
        foreach( $errors as $error ){
            // echo $error;
        }
        break;
}
```

---

### `get_unique_conversation_id` {#get_unique_conversation_id}

Gets or creates a unique conversation based on a set of user IDs and a unique key. Useful for creating unique conversations between buyers and sellers for different products.

If a conversation with the unique key was already created for the given users, returns the existing thread ID — otherwise creates a new one.

**Parameters:**
- `$user_ids` *(array)* — Array of user IDs
- `$unique_key` *(string)* — Unique identifier (e.g., `'product_123'`)
- `$subject` *(string)* — Subject (only used when creating new conversation)

**Returns:** `int|false` — Thread ID on success, `false` on failure

```php
$user_ids   = [1, 2];
$unique_key = 'product_123';
$subject    = 'Questions about your Product 123';

$thread_id = Better_Messages()->functions->get_unique_conversation_id( $user_ids, $unique_key, $subject );
```

---

## Participants

### `add_participant_to_thread` {#add_participant_to_thread}

Adds a user to an existing conversation.

**Parameters:**
- `$thread_id` *(int)* — Conversation ID
- `$user_id` *(int)* — User ID to add

**Returns:** `bool` — `true` if added, `false` if not

```php
$user_id   = 3;
$thread_id = 6610;

$user_added = Better_Messages()->functions->add_participant_to_thread( $thread_id, $user_id );
```

---

### `remove_participant_from_thread` {#remove_participant_from_thread}

Removes a user from an existing conversation.

**Parameters:**
- `$thread_id` *(int)* — Conversation ID
- `$user_id` *(int)* — User ID to remove

**Returns:** `bool` — `true` if removed, `false` if not

```php
$user_id   = 3;
$thread_id = 6610;

$user_removed = Better_Messages()->functions->remove_participant_from_thread( $thread_id, $user_id );
```

---

### `is_user_participant` {#is_user_participant}

Checks if a user is a participant of a conversation.

**Parameters:**
- `$thread_id` *(int)* — Conversation ID
- `$user_id` *(int)* — User ID to check

**Returns:** `bool` — `true` if participant, `false` if not

```php
$user_id   = 3;
$thread_id = 6610;

$is_participant = Better_Messages()->functions->is_user_participant( $thread_id, $user_id );
```

---

### `get_recipients_ids` {#get_recipients_ids}

Retrieves all user IDs participating in a conversation.

**Parameters:**
- `$thread_id` *(int)* — Conversation ID

**Returns:** `array` — Array of user IDs, empty array if no participants or thread doesn't exist

```php
$user_ids = Better_Messages()->functions->get_recipients_ids( $thread_id );
```

---

## Thread Management

### `archive_thread` {#archive_thread}

Archives (hides) a conversation for a specific user. Equivalent to the user deleting the conversation — it only hides it from their list, not actually deleted from the database.

**Parameters:**
- `$user_id` *(int)* — User ID
- `$thread_id` *(int)* — Conversation ID

```php
$user_id   = 3;
$thread_id = 6610;

Better_Messages()->functions->archive_thread( $user_id, $thread_id );
```

---

### `set_user_unread_count_for_thread` {#set_user_unread_count_for_thread}

Sets the unread message count for a specific user in a specific conversation.

**Parameters:**
- `$user_id` *(int)* — User ID
- `$thread_id` *(int)* — Conversation ID
- `$unread_count` *(int)* — Number of unread messages

```php
$user_id      = 3;
$thread_id    = 3;
$unread_count = 1;

Better_Messages()->functions->set_user_unread_count_for_thread( $user_id, $thread_id, $unread_count );
```

---

## Thread Meta

### `get_thread_meta` {#get_thread_meta}

Gets thread metadata for a specific key. Works like WordPress `get_post_meta()` — returns the stored value for the given key, or empty string if not found.

**Parameters:**
- `$thread_id` *(int)* — Conversation ID
- `$key` *(string)* — Meta key

**Returns:** `mixed` — Meta value

```php
$thread_id = 1;
$key = 'custom_data';

$custom_data = Better_Messages()->functions->get_thread_meta( $thread_id, $key );
```

---

### `update_thread_meta` {#update_thread_meta}

Updates thread metadata for a specific key. Creates the entry if it doesn't exist, similar to WordPress `update_post_meta()`. Overwrites any existing value for the key.

**Parameters:**
- `$thread_id` *(int)* — Conversation ID
- `$key` *(string)* — Meta key
- `$value` *(mixed)* — Meta value

```php
$thread_id = 1;
$key = 'custom_key';

Better_Messages()->functions->update_thread_meta( $thread_id, $key, 'custom_data' );
```

---

### `delete_thread_meta` {#delete_thread_meta}

Deletes thread metadata for a specific key. Removes the meta entry entirely from the database, similar to WordPress `delete_post_meta()`.

**Parameters:**
- `$thread_id` *(int)* — Conversation ID
- `$key` *(string)* — Meta key

```php
$thread_id = 1;
$key = 'custom_key';

Better_Messages()->functions->delete_thread_meta( $thread_id, $key );
```

---

## URLs & Links

### `create_conversation_link` {#create_conversation_link}

Generates a URL that points to a new conversation screen or directly to a conversation.

**Parameters:**
- `$user_id` *(int)* — Recipient user ID
- `$subject` *(string)* — Predefined subject (leave empty to not prefill)
- `$message` *(string)* — Predefined message content (leave empty to not prefill)
- `$fastStart` *(bool)* — If `true`, opens the conversation directly instead of showing the new conversation screen
- `$scrollToContainer` *(bool)* — Automatically scroll to messages container on page load

**Returns:** `string` — URL

**New conversation screen:**

```php
$user_id = 3;
$subject = 'Conversation Subject';
$message = 'Conversation Predefined Content';
$fastStart = false;
$scrollToContainer = true;

$url = Better_Messages()->functions->create_conversation_link( $user_id, $subject, $message, $fastStart, $scrollToContainer );

echo 'Private Message';
```

**Opening conversation directly:**

```php
$user_id = 3;
$fastStart = true;
$scrollToContainer = true;

$url = Better_Messages()->functions->create_conversation_link( $user_id, '', '', $fastStart, $scrollToContainer );

echo 'Fast Private Message';
```

---

### `get_user_messages_url` {#get_user_messages_url}

Generates a URL pointing to a user's personal inbox, optionally with a specific conversation opened.

**Parameters:**
- `$user_id` *(int)* — User ID for whom the link is generated
- `$thread_id` *(int, optional)* — Specific conversation to open

**Returns:** `string` — URL

**Specific conversation:**

```php
$user_id   = 3;
$thread_id = 111;

$url = Better_Messages()->functions->get_user_messages_url( $user_id, $thread_id );
```

**General inbox:**

```php
$user_id = 3;

$url = Better_Messages()->functions->get_user_messages_url( $user_id );
```

---

## Layout Rendering

### `get_conversation_layout` {#get_conversation_layout}

Outputs a single conversation layout for embedding.

**Parameters:**
- `$thread_id` *(int)* — Conversation ID to display

**Returns:** `string` — HTML

```php
$thread_id = 123;

echo Better_Messages()->functions->get_conversation_layout( $thread_id );
```

---

### `get_conversations_layout` {#get_conversations_layout}

Displays an interactive conversations list anywhere on your website.

**Parameters:**
- `$height` *(int)* — Height of the list in pixels

**Returns:** `string` — HTML

```php
$height = 400;
echo Better_Messages()->functions->get_conversations_layout( $height );
```

![Conversations layout example](./img/get_conversations_layout.png)

---

## Messages

### `get_message` {#get_message}

Fetches a single message by ID from the database. Returns the complete message row object including sender_id, thread_id, message content, timestamps, and subject. Returns null if the message doesn't exist.

**Parameters:**
- `$message_id` *(int)* — Message ID

**Returns:** `object|null`

```php
$message = Better_Messages()->functions->get_message( $message_id );
if ( $message ) {
    $sender  = $message->sender_id;
    $content = $message->message;
    $thread  = $message->thread_id;
}
```

---

### `get_messages` {#get_messages}

Fetches messages from a thread with various filtering options.

**Parameters:**
- `$thread_id` *(int)* — Thread ID
- `$message` *(int|false)* — Optional message ID for context. Default `false`
- `$action` *(string)* — Retrieval mode: `'last_messages'`, `'from_message'`, `'to_message'`. Default `'last_messages'`
- `$count` *(int)* — Number of messages to retrieve. Default `50`

**Returns:** `array` — Array of message objects

```php
// Get last 20 messages from a thread
$messages = Better_Messages()->functions->get_messages( $thread_id, false, 'last_messages', 20 );
```

---

### `send_system_message` {#send_system_message}

Sends a system message (non-user, sender_id = 0) with metadata. Useful for events, notifications, or automated messages within a thread.

**Parameters:**
- `$thread_id` *(int)* — Thread ID
- `$type` *(string)* — System message type identifier
- `$data` *(array)* — Additional metadata. Default `[]`

**Returns:** `int` — Message ID

```php
Better_Messages()->functions->send_system_message( $thread_id, 'user_joined', [
    'user_id' => $user_id,
    'user_name' => $user_name,
] );
```

---

### `delete_message` {#delete_message}

Deletes a message and its associated attachments. Triggers `better_messages_before_message_delete` action.

**Parameters:**
- `$message_id` *(int)* — Message ID to delete
- `$thread_id` *(int|false)* — Thread ID. Default `false` (auto-detected)
- `$update_thread` *(bool)* — Whether to update thread timestamps. Default `true`
- `$deleteMethod` *(string|null)* — `'delete'` (hard) or `'softdelete'`. Default `null` (uses plugin setting)

```php
Better_Messages()->functions->delete_message( $message_id );
```

---

### `update_message` {#update_message}

Updates an existing message with new content.

**Parameters (as array):**
- `sender_id` *(int)* — User performing the update
- `message_id` *(int)* — Message ID to update
- `content` *(string)* — New message content
- `thread_id` *(int)* — Thread ID

```php
Better_Messages()->functions->update_message([
    'sender_id'  => get_current_user_id(),
    'message_id' => $message_id,
    'thread_id'  => $thread_id,
    'content'    => 'Updated message content',
]);
```

---

## Message Meta

### `add_message_meta` {#add_message_meta}

Adds metadata to a message.

**Parameters:**
- `$message_id` *(int)* — Message ID
- `$meta_key` *(string)* — Meta key
- `$meta_value` *(mixed)* — Meta value
- `$unique` *(bool)* — Prevent duplicate keys. Default `true`

```php
Better_Messages()->functions->add_message_meta( $message_id, 'priority', 'high' );
```

---

### `get_message_meta` {#get_message_meta}

Gets message metadata for a specific key. Wrapper around WordPress `get_metadata()`. Returns the stored value by default, or an array of all values if `$single` is false.

**Parameters:**
- `$message_id` *(int)* — Message ID
- `$key` *(string)* — Meta key. Default `''` (all meta)
- `$single` *(bool)* — Return single value. Default `true`

**Returns:** `mixed`

```php
$priority = Better_Messages()->functions->get_message_meta( $message_id, 'priority' );
```

---

### `update_message_meta` {#update_message_meta}

Updates message metadata for a specific key. Wrapper around WordPress `update_metadata()`. Creates the entry if it doesn't exist, overwrites if it does.

**Parameters:**
- `$message_id` *(int)* — Message ID
- `$meta_key` *(string)* — Meta key
- `$meta_value` *(mixed)* — New value

```php
Better_Messages()->functions->update_message_meta( $message_id, 'priority', 'low' );
```

---

### `delete_message_meta` {#delete_message_meta}

Deletes message metadata for a specific key. Wrapper around WordPress `delete_metadata()`. If `$meta_value` is provided, only deletes entries matching that specific value.

**Parameters:**
- `$message_id` *(int)* — Message ID
- `$meta_key` *(string)* — Meta key
- `$meta_value` *(mixed, optional)* — Specific value to delete

```php
Better_Messages()->functions->delete_message_meta( $message_id, 'priority' );
```

---

## Thread Information

### `get_thread` {#get_thread}

Fetches a thread object by ID with WordPress object cache support. The result includes the thread's subject, type, and associated metadata. Returns false if the thread doesn't exist.

**Parameters:**
- `$thread_id` *(int)* — Thread ID

**Returns:** `object|false`

```php
$thread = Better_Messages()->functions->get_thread( $thread_id );
if ( $thread ) {
    $subject = $thread->subject;
}
```

---

### `get_thread_type` {#get_thread_type}

Gets the type of a thread. Returns `'thread'` for private conversations, `'group'` for group-linked conversations, or other types for chat rooms. The result is cached and validated against active group plugins.

**Parameters:**
- `$thread_id` *(int)* — Thread ID

**Returns:** `string` — `'thread'` (private), `'group'`, or chat room type

```php
$type = Better_Messages()->functions->get_thread_type( $thread_id );
if ( $type === 'group' ) {
    // Handle group conversation
}
```

---

### `change_thread_subject` {#change_thread_subject}

Changes a thread's subject in the database and triggers `better_messages_thread_updated` and `better_messages_info_changed` actions. All thread participants receive a real-time update notification so the UI reflects the new subject immediately.

**Parameters:**
- `$thread_id` *(int)* — Thread ID
- `$new_subject` *(string)* — New subject text

**Returns:** `string` — The escaped subject that was set

```php
Better_Messages()->functions->change_thread_subject( $thread_id, 'New Subject' );
```

---

### `find_existing_threads` {#find_existing_threads}

Finds all existing private threads between two users. Excludes deleted threads and threads with disabled replies. Useful for checking if a PM conversation already exists before creating a new one.

**Parameters:**
- `$from` *(int)* — First user ID
- `$to` *(int)* — Second user ID
- `$exclude_deleted` *(bool|null)* — Whether to exclude deleted threads

**Returns:** `array` — Array of thread IDs

```php
$threads = Better_Messages()->functions->find_existing_threads( $user_id_1, $user_id_2 );
```

---

### `clear_thread` {#clear_thread}

Deletes all messages in a thread, its mentions included, and resets unread counters, read timestamps, and delivered timestamps for all participants. The conversation itself and its participants stay. This is a destructive operation — all message content and attachments are permanently removed. Fires `better_messages_thread_cleared`.

**Parameters:**
- `$thread_id` *(int)* — Thread ID

```php
Better_Messages()->functions->clear_thread( $thread_id );
```

---

### `erase_thread` {#erase_thread}

Deletes a whole conversation for good: all its messages with their attachments, its metadata, and its participant records, so it disappears for everyone. Use it to remove conversations from code, for example when a member's access ends. Fires `better_messages_thread_erased`. `clear_thread` empties a conversation and keeps it.

**Parameters:**
- `$thread_id` *(int)* — Thread ID

```php
Better_Messages()->functions->erase_thread( $thread_id );
```

Delete the private conversations between two users, as `find_existing_threads` finds them:

```php
foreach ( Better_Messages()->functions->find_existing_threads( $user_id_1, $user_id_2 ) as $thread_id ) {
    Better_Messages()->functions->erase_thread( $thread_id );
}
```

---

## Unread Counts

### `get_user_unread_count` {#get_user_unread_count}

Gets the total unread message count across all non-deleted threads for a user. Sums the `unread_count` values above 0 from the recipients table, so a conversation the user [marked as unread](/docs/features/mark-as-unread/) (`-1`) is not counted. Useful for displaying a global unread badge.

**Parameters:**
- `$user_id` *(int)* — User ID

**Returns:** `int`

```php
$total_unread = Better_Messages()->functions->get_user_unread_count( $user_id );
```

---

### `get_user_unread_for_thread` {#get_user_unread_for_thread}

Gets the unread count for a specific user in a specific thread from the recipients table. Returns 0 if the user has read all messages or if the record doesn't exist, and -1 for a conversation the user [marked as unread](/docs/features/mark-as-unread/).

**Parameters:**
- `$user_id` *(int)* — User ID
- `$thread_id` *(int)* — Thread ID

**Returns:** `int`

```php
$unread = Better_Messages()->functions->get_user_unread_for_thread( $user_id, $thread_id );
```

---

### `messages_mark_thread_read` {#messages_mark_thread_read}

Marks all messages in a thread as read for a user by resetting `unread_count` to 0 and updating `last_read` and `last_delivered` timestamps. Clears related caches. Defaults to the current user if `$user_id` is not provided.

**Parameters:**
- `$thread_id` *(int)* — Thread ID
- `$user_id` *(int|false)* — User ID. Default `false` (current user)

```php
Better_Messages()->functions->messages_mark_thread_read( $thread_id, $user_id );
```

---

### `mark_thread_unread` {#mark_thread_unread}

Marks a conversation as unread again for a user (Better Messages 3.2, [Mark as unread](/docs/features/mark-as-unread/)). Sets `unread_count` to `-1`, which shows a dot in the conversations list and counts in no unread total, passes the mark to the realtime server on the WebSocket version so it reaches the other devices of the user, and fires [`better_messages_thread_marked_unread`](/hooks/php-actions/#better_messages_thread_marked_unread). Opening the conversation or a new message in it ends the mark.

Refuses (returns `false`) when **Settings → Messaging → Conversation Features → Mark as Unread** is off, in a presence-based chat room, and for a user who is not a participant. With `$only_read`, it also leaves a conversation the site counts unread as it is and returns `false` for it.

**Parameters:**
- `$thread_id` *(int)* — Thread ID
- `$user_id` *(int)* — User ID, negative for a guest
- `$only_read` *(bool)* — Mark only a conversation the site counts read. Default `false`

**Returns:** `bool` — `true` once the conversation is marked

```php
Better_Messages()->functions->mark_thread_unread( $thread_id, $user_id );
```

---

### `get_user_muted_threads` {#get_user_muted_threads}

Gets all threads muted by a user from the recipients table. Returns an empty array if the muting feature is disabled in settings or if the user has no muted threads.

**Parameters:**
- `$user_id` *(int)* — User ID

**Returns:** `array` — Array of muted thread IDs, empty array if none

```php
$muted = Better_Messages()->functions->get_user_muted_threads( $user_id );
```

---

## Permissions

### `can_reply_in_conversation` {#can_reply_in_conversation}

Checks if a user can reply in a conversation, with detailed error messages.

**Parameters:**
- `$user_id` *(int)* — User ID
- `$thread_id` *(int)* — Thread ID

**Returns:** `array` — `['result' => 'allowed']` or `['result' => 'not_allowed', 'errors' => [...]]`

```php
$check = Better_Messages()->functions->can_reply_in_conversation( $user_id, $thread_id );
if ( $check['result'] === 'allowed' ) {
    // User can reply
} else {
    // $check['errors'] contains error messages
}
```

---

### `can_start_conversation` {#can_start_conversation}

Validates if a user can create a new conversation with specific recipients.

**Parameters:**
- `$starter_id` *(int)* — User starting the conversation
- `$recipients` *(array)* — Recipient user IDs. Default `[]`
- `$uniqueKey` *(string|null)* — Optional unique key. Default `null`

**Returns:** `array` — Result with `'result'` key

```php
$check = Better_Messages()->functions->can_start_conversation( $user_id, [3, 4, 5] );
if ( $check['result'] === 'allowed' ) {
    // User can start conversation
}
```

---

## Moderators

### `get_moderators` {#get_moderators}

Gets all moderator user IDs for a thread from the thread's `moderators` metadata. Returns an empty array if no moderators are assigned. Moderators have additional permissions like muting, banning, and deleting messages from other users.

**Parameters:**
- `$thread_id` *(int)* — Thread ID

**Returns:** `array` — Array of moderator user IDs

```php
$moderators = Better_Messages()->functions->get_moderators( $thread_id );
```

---

### `add_moderator` {#add_moderator}

Adds a user as moderator to a thread by updating the thread's `moderators` metadata. Skips if the user is already a moderator. Triggers `better_messages_info_changed` action so all participants see the updated moderator list.

**Parameters:**
- `$thread_id` *(int)* — Thread ID
- `$user_id` *(int)* — User ID to promote

```php
Better_Messages()->functions->add_moderator( $thread_id, $user_id );
```

---

### `remove_moderator` {#remove_moderator}

Removes a user from the moderator list of a thread by updating the thread's `moderators` metadata. Triggers `better_messages_info_changed` action if the user was actually a moderator. The user remains a regular participant.

**Parameters:**
- `$thread_id` *(int)* — Thread ID
- `$user_id` *(int)* — User ID to demote

```php
Better_Messages()->functions->remove_moderator( $thread_id, $user_id );
```

---

## User Information

### `get_name` {#get_name}

Gets a user's display name by checking fullname first, then falling back to display_name. Returns "Deleted User" if the user doesn't exist. The result passes through the `bp_better_messages_display_name` filter, allowing customization by other plugins.

**Parameters:**
- `$user_id` *(int)* — User ID (can be negative for guests)

**Returns:** `string`

```php
$name = Better_Messages()->functions->get_name( $user_id );
```

---

## Chat Rooms

### `get_chat_thread_id` {#get_chat_thread_id}

Gets the messaging thread ID associated with a chat room post. Looks up the thread ID from post metadata. Returns false if the chat room has no associated thread or if the metadata is invalid.

**Parameters:**
- `$chat_id` *(int)* — Chat room post ID

**Returns:** `int|false` — Thread ID or `false` if not found

```php
$thread_id = Better_Messages()->chats->get_chat_thread_id( $chat_id );
```

---

### `get_chat_settings` {#get_chat_settings}

Gets all settings for a chat room (permissions, notifications, display options), merged with defaults.

**Parameters:**
- `$chat_id` *(int)* — Chat room post ID

**Returns:** `array` — Complete settings array

```php
$settings = Better_Messages()->chats->get_chat_settings( $chat_id );
$can_join_roles = $settings['can_join']; // Array of roles that can join
```

---

## Group Calls

### `get_group_call_participants` {#get_group_call_participants}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Returns how many people are currently in a conversation's group call. Group video and group audio are separate rooms, so ask for each type you care about — one conversation can have people in both at the same time.

Use this for **server-side decisions**, above all the capacity gate below. Each uncached call reaches out to the call server, so it is the wrong tool for a page that displays a live number — that belongs in the browser, where [`BetterMessages.getGroupCallParticipants()`](/hooks/js-functions/#getGroupCallParticipants) answers over the WebSocket without touching WordPress at all.

Returns `0` when no call is running, when the conversation does not exist, or when the site has no WebSocket license.

**Parameters:**
- `$thread_id` *(int)* — Conversation ID
- `$type` *(string)* — `'video'` (default) or `'audio'`

**Returns:** `int` — People currently in that call

```php
$thread_id = 1;

$in_video = Better_Messages()->functions->get_group_call_participants( $thread_id, 'video' );
$in_audio = Better_Messages()->functions->get_group_call_participants( $thread_id, 'audio' );
```

There is no event for a participant leaving a call on the server, because a member closes the call in their browser without WordPress being involved. In the browser you do get one — [`better_messages_group_call_status`](/hooks/js-actions/#better_messages_group_call_status) fires whenever a count changes, in either direction.

To cap a room and send people elsewhere once it fills up, pair this with [`better_messages_group_call_join_custom_error`](/hooks/php-filters#better_messages_group_call_join_custom_error). The filter runs before the person is connected, so nobody slips in between two reads:

```php
add_filter( 'better_messages_group_call_join_custom_error', 'send_to_overflow_room', 10, 4 );
function send_to_overflow_room( $error, $thread_id, $user_id, $type ){
    if( ! empty( $error ) ){
        return $error;
    }

    if( Better_Messages()->functions->get_group_call_participants( $thread_id, $type ) >= 20 ){
        return __( 'This room is full. Please join the overflow room.', 'your-textdomain' );
    }

    return $error;
}
```

Group calls have no fixed size: a site includes 32 people at once across all its group calls, and more join with WordPlus Cloud credits. A threshold like this one keeps a room at the size you choose.

Results are cached briefly so a burst of joins does not mean a burst of outbound requests, and the window is filterable with [`better_messages_group_call_participants_cache_time`](/hooks/php-filters#better_messages_group_call_participants_cache_time).

---

## Realtime Events

### `send_realtime_event` {#send_realtime_event}

:::info WebSocket Version
This functionality is available only with the WebSocket version.
:::

Sends a custom realtime event directly to user browsers using WebSocket servers. To receive events on the frontend, use the [`better_messages_realtime_event`](/hooks/js-actions#better_messages_realtime_event) JavaScript hook.

**Parameters:**
- `$user_ids` *(array)* — User IDs to send events to
- `$data` *(mixed)* — Event data (string, array, or object)

```php
// Check if WebSocket class exists to avoid fatal errors
if( class_exists('Better_Messages_WebSocket') ){
    // Send simple string
    Better_Messages_WebSocket()->send_realtime_event( [1,2,3], 'custom string' );

    // Send more complex data sets
    Better_Messages_WebSocket()->send_realtime_event( [1,2,3], [
        'custom data' => 'test'
    ] );
}
```