Skip to main content

JavaScript Functions Reference

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

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

Returns: true

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

Conversations​

BetterMessages.openChatWithUser( userId )​

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
var user_id = 3;
BetterMessages.openChatWithUser( user_id );

BetterMessages.openUniqueConversation( key )​

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
BetterMessages.openUniqueConversation( 'order-123-support' );

Full Screen​

BetterMessages.openFullScreen()​

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

BetterMessages.openFullScreen();

Mini Chats​

BetterMessages.miniChatOpen( threadId, open )​

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
var thread_id = 10;
var open = true;
BetterMessages.miniChatOpen( thread_id, open );

BetterMessages.miniChatClose( threadId )​

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
var thread_id = 10;
BetterMessages.miniChatClose( thread_id );

BetterMessages.openNewConversationWidget()​

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.

BetterMessages.openNewConversationWidget();

Online Users​

BetterMessages.getOnlineUsers()​

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

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

Call Status​

BetterMessages.isInCall()​

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

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

WebSocket​

BetterMessages.getSocket()​

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

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

API Access​

BetterMessages.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

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

Thread Management​

BetterMessages.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.

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

BetterMessages.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.

BetterMessages.resetMainVisibleThread();

Settings Storage​

BetterMessages.getSetting( key, standard )​

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>

var value = await BetterMessages.getSetting( 'my_custom_setting', 'default' );

BetterMessages.updateSetting( key, value )​

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

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

BetterMessages.deleteSetting( key )​

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

Parameters:

  • key (string) — Setting key to remove

Returns: Promise

await BetterMessages.deleteSetting( 'my_custom_setting' );

Utility​

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

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