Skip to main content

JavaScript Actions Reference

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​

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

Parameters:

  • message_id (number) — The received message ID
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​

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.)
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​

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 PHP function.

Parameters:

  • eventData (object) — Decrypted custom event data (structure defined by sender)
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​

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

Parameters:

  • unread (number) — Total unread count
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​

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

Online Status​

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
wp.hooks.addAction('better_messages_user_online', 'my_plugin', function(userId) {
    console.log('User #' + userId + ' is now online');
});

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
wp.hooks.addAction('better_messages_user_offline', 'my_plugin', function(userId) {
    console.log('User #' + userId + ' is now offline');
});

better_messages_online_users_loaded​

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
wp.hooks.addAction('better_messages_online_users_loaded', 'my_plugin', function(onlineUsers) {
    console.log('Online users:', onlineUsers.length);
    // Initialize presence indicators
});

Chat Rooms​

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
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​

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
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​

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

Calls​

better_messages_call_accepted​

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
wp.hooks.addAction('better_messages_call_accepted', 'my_plugin', function(messageId, threadId) {
    console.log('Call accepted in thread #' + threadId);
});

better_messages_call_end​

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)
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​

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
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​

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​

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
wp.hooks.addAction('better_messages_call_user_rejected', 'my_plugin', function(messageId, threadId, userId, reason) {
    console.log('Call rejected by user #' + userId + ': ' + reason);
});