Voxel Bulk Messages
The {CODICTS} Voxel Bulk Messages plugin enables users to send bulk direct messages to listing owners on sites powered by the Voxel Theme. By placing a single shortcode alongside a Voxel Search Form, users can compose and send a message to all listings matching the current search criteria — delivered through Voxel’s native Direct Messages system.
Requirements
Important: The plugin checks for the Voxel Child Theme on every page load. If the Voxel Theme is not the active theme, the plugin will display an admin notice and will not load any of its features.
Installation & Activation
Start by downloading the plugin from the Downloads page on your dashboard on the CoDicts website.
After downloading, install and activate the plugin in WordPress by navigating to “Plugins” > “Add New” > “Upload Plugin” and selecting the downloaded zip file. Click “Install Now” and then “Activate”.
Once activated, navigate to “Bulk Messages” > “Settings” in the WordPress admin sidebar to configure the plugin before use.
Quick Start Setup
Step 1: Configure Settings
Go to “Bulk Messages” > “Settings” and configure the basic options. At minimum, you need to enable the user roles that should have access to the bulk messaging feature.
Step 2: Add the Shortcode
Place the following shortcode on any page that contains a Voxel Search Form (VX) Elementor widget:
[codicts-voxel-bulk-messages]This will render a “Send Bulk Messages” button that automatically reads the active search filters to determine recipients.
Step 3: Test It
Visit the page on the frontend while logged in as a user with an enabled role. Apply some search filters, then click the bulk message button. A modal will appear where you can compose and send your message to all matching listings.
Tip: The user must be logged in, and their role must be enabled in the plugin settings for the button to appear.
Shortcode Options
The shortcode supports the following attributes for customization:
| Attribute | Default | Description |
|---|---|---|
button_text | “Send Bulk Messages” | Custom text for the trigger button. |
search_form_selector | (auto-detect) | CSS selector targeting a specific Search Form widget. Useful when multiple search forms exist on a page. |
Example Usage
[codicts-voxel-bulk-messages button_text="Message All" search_form_selector=".my-search-form"]Important: The page must contain a Voxel Search Form (VX) Elementor widget for the shortcode to work. The plugin reads the search form’s current filters to determine who receives the message.
The Bulk Message Modal
When a user clicks the bulk message button, a Voxel-styled modal popup appears with the following sections:
| Section | Description |
|---|---|
| Header | Shows the current user’s avatar and display name. If the receiver editor is enabled, a tokenfield composer replaces this. Optionally displays the daily limit counter. |
| Body | Contains the message textarea (max 5,000 characters) and optional pre-defined message buttons. |
| Footer | Cancel and Send buttons. The Send button shows a loading spinner during submission. |
Settings Overview
All settings are found at “Bulk Messages” > “Settings” in the WordPress admin.
General Settings
| Setting | Description |
|---|---|
| Require Admin approval | Places messages in Pending status until an admin approves them. Messages are not delivered until approved. |
| Send notification email to admin | Sends an HTML email to the site admin when a message is pending approval. Only available when approval is enabled. |
| Disable sending to current user’s posts | Prevents users from sending bulk messages to their own listings. |
| Max target bulk message limit | Maximum number of recipients per bulk message (default: 500). |
| Send to visible results only | Limits recipients to only the listings currently visible on the search results page, rather than all matching listings. |
Daily Limits
| Setting | Description |
|---|---|
| Limit daily messages per user | Enables per-user daily sending caps. |
| Daily limit max | Maximum messages a user can send per day (default: 500). The count resets automatically at midnight. |
User Access
| Setting | Description |
|---|---|
| Enable for User Roles | Select which WordPress roles can use the bulk message feature. Users with roles not checked here will not see the button. |
| Disable for User | Individually block specific users from sending bulk messages, regardless of their role. |
Receiver Editor
| Setting | Description |
|---|---|
| Enable receiver editor | Shows a composer-like tokenfield in the modal header, allowing senders to search for, add, and remove individual recipients before sending. |
Pre-Defined Messages
| Setting | Description |
|---|---|
| Use pre-defined messages | Enables message templates that appear as clickable buttons in the modal. |
| Disable custom messages | Hides the free-text textarea so users can only choose from pre-defined options. |
| Pre-defined messages | Add, edit, or remove message templates using the repeater interface. |
Opt-Out Toggle Label
| Setting | Description |
|---|---|
| Receive bulk messages toggle label | Customizes the label text shown on the opt-out toggle in users’ inboxes (default: “Receive bulk messages?”). |
Per-Listing-Type Settings
At the bottom of the Settings page, you will find a section for each registered Voxel listing type. For each listing type, you can configure where bulk messages are sent:
| Option | Behavior |
|---|---|
| Listing Post | Messages are sent directly to the listing post itself. |
| Listing Author | Messages are sent to the listing author’s profile post instead. |
| Custom Field | Messages are sent to the post(s) referenced by a specified custom field key. When selected, a text input appears for entering the field key. |
Tip: The “Listing Author” option is useful when your listings represent businesses or places, and you want the message to go to the person who created the listing rather than the listing page itself.
Admin Approval Workflow
When “Require Admin approval” is enabled, messages go through a review process before being delivered.
How It Works
Step 1: A user submits a bulk message from the frontend. The message is saved with a Pending status and is not delivered yet. The user sees a notice confirming the message is awaiting approval.
Step 2: If admin email notifications are enabled, the site admin receives an HTML email with the message details and Approve, Decline, and Delete action buttons.
Step 3: The admin navigates to “Bulk Messages” in the WordPress admin (a pending count badge is shown on the menu item). From there, the admin can:
| Action | Result |
|---|---|
| Approve | Status changes to Sent and messages are delivered to all recipients. |
| Decline | Status changes to Declined. Messages are never sent. |
| Delete | The record is permanently removed. |
All three actions can also be applied in bulk to multiple messages at once.
Tip: When admin approval is disabled, messages are sent immediately after the user clicks Send — no admin review required.
Admin Message List
The main “Bulk Messages” admin page shows a list of all submitted messages with the following columns:
| Column | Description |
|---|---|
| User | Sender’s display name and email. |
| Referrer | The page URL the message was sent from (clickable link). |
| Parameters | The search query parameters used to find recipients, shown as pill badges. |
| Message | The message text content. |
| Date | When the message was submitted. |
| Status | Pending, Sent, or Declined. |
You can sort by User, Referrer, Date, or Status. Use the status dropdown to filter by Pending, Sent, or Declined messages, and the search box to find messages by sender name.
Receiver Editor
When the “Enable receiver editor” setting is active, the modal header is replaced with a tokenfield composer that gives senders more control over who receives the message.
How It Works
Step 1: When the modal opens, recipients matching the current search filters are automatically loaded as tokens.
Step 2: The sender can remove individual recipients by clicking the token’s remove button, or search for additional recipients by typing in the field.
Step 3: On send, only the recipients shown in the tokenfield receive the message.
Tip: The receiver editor is particularly useful when you want to give users fine-grained control over exactly who receives their message, rather than sending to every matching listing.
Pre-Defined Messages
Administrators can create a library of message templates that users can select from when composing bulk messages.
Setting Up Templates
Step 1: In Settings, enable “Use pre-defined messages”.
Step 2: Use the repeater to add your message templates. Each template is a text string that will appear as a clickable button in the modal.
Step 3: Optionally enable “Disable custom messages” to hide the free-text textarea entirely, forcing users to choose only from your templates.
How Users See It
Pre-defined messages appear as clickable pill buttons above the textarea. Clicking one selects it and populates the textarea with its content. Clicking it again deselects it and clears the textarea. Only one template can be selected at a time.
User Opt-Out System
Users can opt out of receiving bulk messages directly from their Voxel inbox.
The plugin adds a toggle switch to the Voxel inbox sidebar. When toggled off, the user is excluded from all future bulk message recipient lists. Toggling it back on re-subscribes the user.
You can customize the toggle label text in the plugin settings under “Receive bulk messages toggle label”.
Daily Limit System
When “Limit daily messages per user” is enabled, each user is limited to a configurable number of bulk message sends per day.
The current count and limit are displayed in the modal header (e.g., “3/10 daily limit”). When the limit is reached, the user sees a message: “Daily message limit has been reached.”
The count resets automatically at midnight via a WordPress cron event. If you notice counts not resetting, see the Troubleshooting section below.
Admin Email Notifications
When both “Require Admin approval” and “Send notification email to admin” are enabled, the site admin receives an HTML email each time a user submits a bulk message.
The email includes the sender’s name and email, up to 10 target listing links (with a “+ X more records” note if there are more), the message text, and Approve, Decline, and Delete action buttons that link directly to the admin panel.
Hooks & Filters for Developers
PHP Filter — Email Sender
Customize the “From” header on admin notification emails:
add_filter('codicts-voxel-bulk-messages::sender', function($sender_string) {
return 'My Site <noreply@mysite.com>';
});PHP Filter — Max Search Limit
Override the maximum number of search results returned when resolving recipients:
add_filter('voxel/get_search_results/max_limit', function($max_limit) {
return 1000;
});Troubleshooting
“Voxel Theme Not Detected” Error
Ensure the Voxel Theme is installed and set as the active theme. If you are using a child theme, the parent theme template must still be voxel.
“Search form not found” Error
This error appears when the shortcode cannot find a Voxel Search Form widget on the page. Make sure a Search Form (VX) Elementor widget exists on the same page as the shortcode. If multiple search forms exist, use the search_form_selector attribute to target the correct one:
[codicts-voxel-bulk-messages search_form_selector=".my-search-form"]Messages Not Sending
If messages are not being delivered, check the following:
Admin approval enabled? Messages may be sitting in Pending status. Check the “Bulk Messages” admin list and approve them.
User role enabled? Make sure the user’s WordPress role is checked in the plugin settings.
User individually disabled? Check the “Disable for User” setting to make sure the sender is not blocked.
Daily limit reached? The user may have hit their daily sending cap. The count resets at midnight.
All recipients opted out? If every matching listing owner has opted out via the inbox toggle, there will be no recipients.
Empty search results? The current search query may return no listings. Try broadening the filters.
Daily Limits Not Resetting
If daily message counts persist past midnight, WordPress cron may not be running properly. Verify that wp-cron.php is accessible on your server. You can also check if the reset event is scheduled using a cron inspection plugin like WP Crontrol. As a quick fix, deactivate and reactivate the plugin to reschedule the cron event.
Receiver Editor Not Showing Results
Make sure at least one listing matches the current search filters. Check that the listing type’s “Send to” configuration is correct in the per-listing-type settings. Verify that targeted listings have authors and can receive messages through Voxel’s Direct Messages system.
For further support, visit codicts.com or contact us at support@codicts.com.