PHP Filters Reference
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
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#
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.
Parameters:
$allowed(bool) — Whether the user is allowed$user_id(int) — User attempting to send$thread_id(int) — The thread ID
Returns: bool
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;
}
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) — Defaultnull$original_message(object) — The message being forwarded$current_user_id(int) — User forwarding the message
Returns: null|WP_Error
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#
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
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#
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) — Defaultfalse$user_id(int) — Current user$thread_id(int) — The thread
Returns: bool
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#
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
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#
Completely overrides the default access check for a thread. Return null to use default logic, or bool to override.
Parameters:
$override(null|bool) — Defaultnull(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
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#
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) — Defaultfalse$thread_id(int) — Group chat thread$user_id(int) — User checking access
Returns: bool
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#
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
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#
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 onguest_access_enabledsetting$registerData(array|null) — Registration form data
Returns: bool
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#
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) — Defaultfalse$request(WP_REST_Request) — The REST request
Returns: bool
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#
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
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#
Filters whether a user can unblock a previously blocked user. Default is true.
Parameters:
$can_unblock(bool) — Defaulttrue$user_id(int) — User unblocking$blocked_id(int) — User to unblock
Returns: bool
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 onbm_can_administratecapability$user_id(int) — The user$thread_id(int) — The thread
Returns: bool
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#
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#
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 (or0for new messages)
Returns: bool
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#
Filters whether the Messages tab is visible in BuddyPress group navigation. Default true.
Parameters:
$enabled(bool) — Defaulttrue
Returns: bool
Message Content#
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
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#
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
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#
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
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#
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#
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#
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 orfalse
Returns: string
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 orfalse
Returns: string
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#
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#
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#
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#
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#
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#
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#
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#
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_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#
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 exampleyoutubeorvimeo
Returns: string
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#
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) —trueby default$src(string) — The player URL about to be rewritten
Returns: bool
add_filter( 'better_messages_youtube_playsinline_fullscreen', '__return_false' );
REST API#
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 guide), and more.
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#
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.
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#
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
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#
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
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#
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#
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
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#
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) — Default0(not found)$key(string) — Unique key parameter$current_user_id(int) — Current user
Returns: int
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 withthread_idandmessage_id$request(WP_REST_Request) — The request$current_user_id(int) — Creator user ID
Returns: array
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#
Allows E2E encryption addons to intercept content before default sanitization. Return array with subject and content keys to override.
Parameters:
$e2e_init(null|array) — Defaultnull$request(WP_REST_Request) — The request$recipients(array) — Recipient user IDs
Returns: null|array
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 withthread_idandresultstatus$user_id(int) — Other user$current_user_id(int) — Current user
Returns: array
User Identity & Display#
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) — Defaultnull
Returns: int|null
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#
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
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;
}
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) — Defaultfalse$user_id(int) — User ID
Returns: bool
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#
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) — Defaultnull(use WordPress current user)
Returns: int|null
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) — Defaultget_current_user_id()
Returns: int
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) — Default0
Returns: int
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
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#
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
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
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;
}
bp_better_messages_avatar_extra_attr#
Adds custom HTML attributes to the <img> 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#
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
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#
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
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#
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) — Defaultfalse
Returns: bool
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) — Defaultfalse
Returns: bool
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) — Defaultfalse
Returns: bool
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) — Defaultfalse$user_id_1(int) — First user$user_id_2(int) — Second user
Returns: bool
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#
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) — Defaultfalse$user_id_1(int) — First user$user_id_2(int) — Second user
Returns: bool
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) — Defaultfalse
Returns: bool
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) — Defaultfalse
Returns: bool
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
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#
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#
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#
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 onbp_better_messages_can_start_call$user_id(int) — User ID$thread_id(int) — Thread ID
Returns: bool
bp_better_messages_can_video_call#
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 onbp_better_messages_can_start_call$user_id(int) — User ID$thread_id(int) — Thread ID
Returns: bool
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#
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
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#
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.
Parameters:
$error(string) — Default empty string$thread_id(int) — Thread ID$user_id(int) — User joining$type(string) —'audio'or'video'
Returns: string
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#
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.
Parameters:
$error(string) — Default empty string$thread_id(int) — Thread (group/conversation) ID$user_id(int) — User joining the room$type(string) —'audio'or'video'
Returns: string
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#
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 and to the REST endpoint built on it.
Parameters:
$seconds(int) — Default5$thread_id(int) — Conversation ID$type(string) —'audio'or'video'
Returns: int
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#
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#
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#
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 push, the OneSignal integration, 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, anddata(which holdsurl)$user_id(int) — Recipient user ID.0when one payload is shared by several recipients, which happens only on the third-party bulk path$type(string|null) —new_message,call_requestorcall_missed$thread_id(int) — Conversation ID$message_id(int) — Message ID$sender_id(int) — User ID of the sender
Returns: array
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.
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#
Available since Better Messages 2.15.26
Filters the text of push notifications sent to the native mobile app.
This is a separate hook from 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, andavatar(the last only fornew_message)$type(string) —new_messageorcall_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.0fornew_message, which is built once for every recipient
Returns: array
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;
}
Return the array with its keys intact. Removing one leaves the notification without that piece of text.
better_messages_push_active#
Whether the built-in push notification system is active.
Parameters:
$active(bool) — Default fromenablePushNotificationssetting
Returns: bool
better_messages_3rd_party_push_active#
Whether a third-party push notification system is active. Default false.
Parameters:
$active(bool) — Defaultfalse
Returns: bool
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#
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#
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#
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) — Defaultfalse$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#
Web Push VAPID key pair. Return false to use stored keys.
Parameters:
$keys(array|false) — Defaultfalse
Returns: array|false — Array with publicKey and privateKey
better_messages_is_user_emails_enabled#
Whether email notifications are enabled for a user.
Parameters:
$enabled(bool) — User's stored preference$user_id(int) — User ID
Returns: bool
better_messages_is_user_web_push_enabled#
Whether web push is enabled for a user. Default true.
Parameters:
$enabled(bool) — Defaulttrue$user_id(int) — User ID
Returns: bool
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) — Defaultfalse$user_id(int) — Recipient$thread_id(int) — Thread$messages(array) — Messages in notification
Returns: bool|string — false for default email, or custom HTML
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#
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#
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#
Customizes BuddyPress notification click URL.
Parameters:
$url(string) — Notification URL$notification(object) — BuddyPress notification
Returns: string
better_messages_bb_app_push_only_online#
Controls whether to send push only to online BuddyBoss app users. Default true.
Parameters:
$only_online(bool) — Defaulttrue
Returns: bool
Search#
better_messages_search_results#
Filters complete search results.
Parameters:
$return(array) — Array withfriends,users,messages,updateDatakeys$search(string) — Search query$user_id(int) — Searcher
Returns: array
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#
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#
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#
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
// 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#
Maximum number of users returned in search. Default 50.
Parameters:
$limit(int) — Default50
Returns: int
Files & Attachments#
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
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#
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) — FromattachmentsFormatssetting$thread_id(int) — Thread ID$user_id(int) — User ID
Returns: array|string
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#
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) — FromattachmentsMaxSizesetting$thread_id(int) — Thread ID$user_id(int) — User ID
Returns: int|float
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#
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#
Controls attachment ownership security check. Default true.
Parameters:
$enable_check(bool) — Defaulttrue
Returns: bool
AI#
better_messages_ai_bot_instruction#
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).
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:
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:
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#
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 containid,name,featuresandhasGlobalKey.
Returns: array
See the full walkthrough in Add a custom AI provider.
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#
Creates a custom AI provider instance. Return null for unknown providers.
Parameters:
$provider(null|Better_Messages_AI_Provider) — Defaultnull$provider_id(string) — Provider identifier
Returns: Better_Messages_AI_Provider|null
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#
Whether Dokan vendor store messaging is enabled by default. Default true.
Parameters:
$enabled(bool) — Defaulttrue$store_id(int) — Vendor store ID
Returns: bool
better_messages_wcfm_store_default#
Whether WCFM vendor messaging is enabled by default. Default true.
Parameters:
$enabled(bool) — Defaulttrue$vendor_id(int) — Vendor ID
Returns: bool
better_messages_wc_vendors_store_default#
Whether WC Vendors messaging is enabled by default. Default true.
Parameters:
$enabled(bool) — Defaulttrue$store_id(int) — Store ID
Returns: bool
better_messages_multivendorx_store_default#
Whether MultiVendorX vendor messaging is enabled by default. Default true.
Parameters:
$enabled(bool) — Defaulttrue$store_id(int) — Store ID
Returns: bool
Plugin Configuration#
bp_better_messages_overwrite_settings#
Overrides all plugin settings programmatically.
Parameters:
$settings(array) — All loaded plugin options
Returns: array
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#
Whether to use "fast" mode optimization. Default '1'.
Parameters:
$fast(string) —'0'or'1'
Returns: string
better_messages_replace_buddypress#
Whether to replace BuddyPress native messaging. Default true.
Parameters:
$replace(bool) — Defaulttrue
Returns: bool
better_messages_replace_buddyboss#
Whether to replace BuddyBoss native messaging. Default true.
Parameters:
$replace(bool) — Defaulttrue
Returns: bool
better_messages_onesignal_integration#
Whether to load the OneSignal integration 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 is used instead, when enabled).
Available since version 2.15.23.
Parameters:
$enabled(bool) — Defaulttrue
Returns: bool
add_filter( 'better_messages_onesignal_integration', '__return_false' );
better_messages_fluent_notify_integration#
Whether to load the FluentNotify integration 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 is used instead, when enabled).
Available since version 2.15.32.
Parameters:
$enabled(bool) — Defaulttrue
Returns: bool
add_filter( 'better_messages_fluent_notify_integration', '__return_false' );
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#
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#
Filters style dependencies. Default empty array.
Parameters:
$deps(array) — Default empty array
Returns: array
bp_better_messages_script_variables#
Filters global JavaScript variables passed to the frontend.
Parameters:
$variables(array) — Settings, user data, URLs, feature flags
Returns: array
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#
Overrides the WebSocket server URL.
Parameters:
$url(string) — Default'https://cloud.better-messages.com/'
Returns: string
better_messages_turn_server#
Overrides the TURN server for video/audio calls.
Parameters:
$url(string) — Default'turn.bpbettermessages.com'
Returns: string
better_messages_video_server#
Overrides the video conferencing server URL.
Parameters:
$url(string) — Default'video-cloud.better-messages.com'
Returns: string
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#
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#
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#
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#
Filters mobile app settings sent to the frontend. Includes loginLogo, loginLogoExtension, and termsAndConditions keys. Use this to customize the mobile app login screen branding and legal text.
Parameters:
$settings(array) — Keys:loginLogo,loginLogoExtension,termsAndConditions
Returns: array
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#
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
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#
Customizes the login URL shown to unauthenticated users.
Parameters:
$url(string) — Default fromwp_login_url()
Returns: string
add_filter( 'better_messages_login_url', 'custom_login_url' );
function custom_login_url( $url ){
return home_url( '/my-login-page/' );
}
better_messages_registration_url#
Customizes the registration URL.
Parameters:
$url(string) — Default fromwp_registration_url()
Returns: string
add_filter( 'better_messages_registration_url', 'custom_register_url' );
function custom_register_url( $url ){
return home_url( '/register/' );
}
bp_better_messages_max_height#
Customizes the maximum height (px) of message containers.
Parameters:
$height(int) — Default frommessagesHeightsetting
Returns: int
bp_better_messages_page#
Overrides the messages page URL. Return null for default.
Parameters:
$url(string|null) — Defaultnull$user_id(int) — User ID
Returns: string|null
bp_better_messages_sounds_assets#
Customizes the base URL for notification sounds.
Parameters:
$url(string) — Default plugin'sassets/sounds/directory
Returns: string
bp_better_messages_time_locale#
Customizes the locale for timestamp formatting.
Parameters:
$locale(string) — Sanitized WordPress locale
Returns: string
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#
Overrides the base path for template/view files.
Parameters:
$path(string) — Default plugin's/views/directory
Returns: string
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
Emojis & Reactions#
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#
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) — FromreactionsEmojiessetting (comma-separated Unicode codes)
Returns: string|array
Reports & Moderation#
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
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#
Maximum character length for report description. Default 500.
Parameters:
$max(int) — Default500
Returns: int
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#
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#
Batch size for old message deletion cron. Default 100.
Parameters:
$batch_size(int) — Default100
Returns: int
better_messages_delete_old_voice_messages_batch_size#
Batch size for old voice message deletion cron. Default 100.
Parameters:
$batch_size(int) — Default100
Returns: int
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#
Filters SELECT columns.
Parameters: $select (array)
Returns: array
better_messages_notifications_threads_from_sql#
Filters FROM clause.
Parameters: $from (array)
Returns: array
better_messages_notifications_threads_where_sql#
Filters WHERE conditions.
Parameters: $where (array)
Returns: array
better_messages_notifications_threads_group_by_sql#
Filters GROUP BY clause.
Parameters: $group_by (array)
Returns: array
better_messages_notifications_threads_having_sql#
Filters HAVING clause.
Parameters: $having (array)
Returns: array
better_messages_notifications_threads_order_by_sql#
Filters ORDER BY clause.
Parameters: $order_by (array)
Returns: array
better_messages_notifications_threads_limit_sql#
Filters LIMIT clause.
Parameters: $limit (array)
Returns: array
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#
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#
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#
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#
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 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
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#
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#
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#
The course chat counterpart of 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 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#
Filters the HivePress menu item for messages.
Parameters:
$menu_item(array) — Keys:label,url,_order
Returns: array
