Conversations

Create, retrieve, delete, and restore conversation threads

📄️ Get threads list

Returns the current user's conversation list with recent messages and participant data. Threads are ordered by last activity. Deleted threads and threads without messages (except chat rooms and groups) are automatically excluded. Administrators can see pending messages from all users, while regular users only see their own pending messages.

📄️ Get threads list (POST)

Same as GET /threads but accepts POST body for parameters. Useful when the exclude list is large and would exceed URL length limits.

📄️ Get thread details

Returns a specific thread with all its messages and participant data. Automatically marks the thread as read for the current user. For chat room threads, auto-add users are synced on access. The endpoint also detects messages that have been deleted since the client's last load by comparing the provided loaded message IDs against the database.

📄️ Start new conversation

Creates a new conversation thread and sends the first message. Recipients are validated against plugin restrictions (friends-only mode, blocking, etc.). If message moderation is enabled, the message will be placed in a pending queue for admin approval. Supports file attachments and E2E encryption addon integration. Returns an error with detailed messages if the conversation cannot be created.

📄️ Get or create private thread

Gets an existing private 1-on-1 conversation with a specific user, or creates one if it doesn't exist. Supports unique conversation keys for context-specific conversations (e.g., per-product discussions). When a unique key is provided, the endpoint uses `get_unique_pm_thread_id()` instead of the standard PM lookup. Returns full thread data including messages and participants when a thread is found or created.

📄️ Suggest thread for recipients

Checks if a conversation can be started with the given recipients. When a single recipient is specified without the forceNew flag, it looks for an existing PM thread and returns its ID. Otherwise, it validates whether the current user has permission to start a new conversation with the specified recipients.

📄️ Get unique conversation

Gets or creates a conversation identified by a unique key string. The actual thread resolution is handled by addon filters — the core plugin fires `better_messages_get_unique_conversation` filter and returns the resolved thread. This is commonly used for E2E encryption rooms and context-specific conversations. **Public endpoint** — does not require authentication.

📄️ Delete thread

Archives a thread for the current user by soft-deleting it. The thread is hidden from the user's conversation list but not permanently removed from the database. Other participants can still see the conversation. Deletion can be restricted via the `restrictThreadsDeleting` plugin setting — when enabled, only administrators can delete threads. The `bp_better_messages_can_delete_thread` filter allows custom permission logic.

📄️ Restore thread

Restores a previously archived/deleted thread back to the user's conversation list. Sets the is_deleted flag to 0 and updates the last_update timestamp. Subject to the same permission restrictions as thread deletion.

📄️ Clear all messages

Deletes all messages from a thread in batches of 50. Resets unread counts and read timestamps for all participants. Requires the `bm_can_administrate` capability or moderator permission. This is a destructive operation — all message content and attachments are permanently removed.

📄️ Erase thread permanently

Permanently and irreversibly deletes a thread along with all messages, metadata, and participant records. Requires the `bm_can_administrate` capability. Unlike clearing messages, this removes the thread entry itself from the database. Use with extreme caution.

📄️ Leave thread

Removes the current user from a group conversation. The user will no longer receive messages or notifications for this thread. A single moderator cannot leave a thread — another moderator must be assigned first. The `can_leave()` function validates whether the user is allowed to leave.

📄️ Mark all as read

Marks all conversations as read for the current user. Updates unread_count to 0 and sets last_read and last_delivered timestamps for every thread the user participates in. Fires the `better_messages_mark_all_read` action hook.

📄️ Mark threads as read

Marks specific threads as read for the current user. Calls `messages_mark_thread_read()` for each provided thread ID, which resets unread counts and updates read timestamps.