Private Message
A comprehensive private messaging system that allows users to send and receive private messages with support for threading, user banning, and real-time notifications.
private_message
Install
composer require 'drupal/private_message:^3.0'
Overview
The Private Message module provides a full-featured private messaging system for Drupal sites. Users can communicate with each other through private message threads, which can include multiple participants. The module supports real-time message updates via AJAX, user banning to prevent unwanted communication, and email notifications for new messages.
Key capabilities include message threading (where conversations between users are grouped together), the ability to clear personal message history without affecting other thread members, customizable notification settings per user, and a flexible display system with multiple view modes. The module is built with extensibility in mind, leveraging Drupal's entity and plugin systems.
Three main blocks are provided: an Inbox block showing message threads, a Notification block displaying unread message/thread counts, and an Actions block with quick links to create messages or manage banned users. The module integrates with Views for custom message listings, Rules for automated messaging, and supports email notifications through the optional Private Message Notify submodule.
Features
- Private messaging system with threaded conversations between two or more users
- Three configurable blocks: Inbox (showing message threads), Notification (unread counts), and Actions (quick links)
- User banning system with passive (silent block) and active (show message) modes
- Real-time AJAX message loading and inbox refresh with configurable refresh rates
- Email notification support via the Private Message Notify submodule (requires message_notify module)
- Clear personal message history in a thread without affecting other participants
- Customizable message form labels and keyboard shortcuts for quick message sending
- Rules module integration for automated private message sending
- Views integration with custom field and filter plugins for thread queries
- User profile integration with notification preferences (email notifications, notify timing)
- Extra fields for displaying private message links on user profiles, nodes, comments, and profile entities
- Drush command for safe module uninstallation (deletes all message data)
- Support for prefilling recipients via URL parameter with optional field hiding
- Configurable autofocus on message textarea and CSS removal option for custom theming
Use Cases
Basic User-to-User Communication
Enable private messaging between site members by granting the 'use private messaging system' permission to authenticated users. Users can then visit /private-messages to view their inbox and compose new messages. Place the Notification block in a visible region (like the header) so users see their unread message count across the site.
Community Site Moderation Communication
Site moderators can use private messages to communicate with users about content issues. Create a 'moderator' role with messaging permissions and use the Rules integration to automatically notify users when their content is flagged or moderated. The threading system keeps all communication organized.
Support Ticket System
Use private message threads as lightweight support tickets. Users can message support staff who have the appropriate permissions. The thread subject field can be used to categorize inquiries. Views can be used to create a support inbox showing all threads involving support staff members.
E-commerce Buyer-Seller Communication
On marketplace sites, enable communication between buyers and sellers. Add the 'Private message link' extra field to user profiles and configure it to display on product author information. Buyers can click to start a conversation with sellers about products.
Group Conversations
The module supports multi-member threads. Set the widget's max_members setting appropriately to allow group discussions. All members see the same thread and can participate in the conversation.
Blocking Unwanted Messages
Users can block other users from messaging them. Use 'passive' mode for silent blocking (blocked users don't know they're blocked) or 'active' mode to show an error message. Users manage their blocked list at /private-message/ban.
Tips
- Use URL parameters to pre-fill recipients: /private-message/create?recipient=123 to create a message to user ID 123
- Enable 'Hide recipient field when prefilled' to create cleaner contact forms when linking to specific users
- Set ajax_refresh_rate to 0 on low-traffic sites to reduce server load from polling
- Use the 'remove_css' option when building custom themes that need full control over styling
- Create Views with the provided plugins to build custom inbox interfaces or admin message monitoring
- Thread members are validated to exclude blocked users from the autocomplete suggestions
- Use keyboard shortcuts (default: Enter) to quickly send messages without clicking the button
- Extra fields can add 'Send private message' links to user profiles, nodes, comments, and profile entities through Manage Display settings
Technical Details
Admin Pages 6
/admin/config/private-message/config
Main configuration page for the Private Message module. Configure notification settings, message form labels, user banning behavior, and display options.
/admin/structure/private-message
Administrative dashboard for managing Private Message entity types, their fields, form displays, and view displays.
/admin/structure/private-message/private-message-thread
Manage fields, form display, and view display for Private Message Thread entities.
/admin/structure/private-message/private-message
Manage fields, form display, and view display for Private Message entities.
/admin/config/private-message/uninstall
Prepare the module for uninstallation by deleting all private message data. This page displays information and provides confirmation before deleting all messages and threads.
/admin/structure/private_message_ban
Administrative list of all private message bans in the system. Administrators can view, edit, and delete ban records.
Permissions 11
Hooks 1
hook_private_message_new_message
Fired when a new message is added to a thread. Allows modules to react to new messages, such as sending notifications.
Drush Commands 1
drush private_message:prepare_uninstall
Prepares the Private Message module for uninstallation by deleting all private messages and threads. This is necessary before the module can be safely uninstalled.
Troubleshooting 6
Check browser console for JavaScript errors. Ensure that JavaScript aggregation isn't causing conflicts. Verify that CSRF tokens are being generated correctly. Check that the ajax_refresh_rate settings are not set to 0 (disabled).
The module cannot be uninstalled while private message data exists. Visit /admin/config/private-message/uninstall or run 'drush private_message:prepare_uninstall' to delete all messages and threads before uninstalling.
Clear cache tags by saving any thread. The module uses cache tags like 'private_message_notification_block:uid:X' and 'private_message:status:uid:X'. Cache clearing may be needed after configuration changes.
Verify the ban_mode setting. In 'passive' mode, blocked users can send messages but they won't be visible to the blocking user. Switch to 'active' mode if you want blocked users to see an error.
Ensure the Private Message Notify submodule is installed along with the Message Notify module. Check user's notification preferences in their profile. Verify that enable_notifications is true in module configuration.
This issue (Issue #3512770) has been fixed in recent versions. Update the module to the latest version.
Security Notes 6
- The module requires both 'use private messaging system' AND 'access user profiles' permissions to function, preventing anonymous or unauthorized access
- All AJAX endpoints are protected with CSRF tokens
- The 'administer private messages' and related admin permissions are marked as 'restrict access' for security
- User bans are enforced at query level, filtering blocked users from autocomplete and optionally preventing message sending
- Message content is stored as text fields and should have appropriate text format restrictions applied
- Admin permissions for ban entities are separated from general messaging permissions for granular access control