DPMMA-2688 Smart Campaign Event Scheduling Based on Contact Behavior

docs/campaigns/campaign_builder.rst

@@ -237,6 +237,28 @@
 
 If a Contact appears again at a later date in that Segment because the value of the date has changed, then the Contact passes through the Campaign only once, and hence isn't included in the Campaign again.
 
+
+Smart event schedule
+~~~~~~~~~~~~~~~~~~~~~
+
+For the Send Email, Marketing Message, Push Contact to Integration and Send a Webhook actions, Mautic provides a smart event schedule option. This feature dynamically optimizes the timing of event execution based on individual Contact behaviors, increasing the likelihood of engagement.
+
+**How it Works**
+
+1. **Interaction data retrieval**: the system retrieves interaction data for the Contact, including Email reads, Landing Page hits and Form submissions, to analyze the Contact's engagement patterns.
+
+2. **Minimum interactions requirement**: a Contact must have a minimum number of interactions for the system to calculate optimal timing. Each interaction type (Email open, website visit, Form submit) counts only once per hour. When a Contact doesn't have enough interaction data, default hour ranges and days adjust to the Contact's preferred timezone.
+
+3. **Optimal time calculation (execute event within 24 hours)**: based on the Contact's interaction data, the system calculates the optimal time for executing a Campaign event, considering the Contact's historical engagement patterns.
+    - If the Contact is within the optimal window at that moment, the event executes immediately.
+    - If the current time is before today's optimal window, the event schedules for the first hour of that window.
+    - If the current time is after today's optimal window, the event schedules for the first hour of the next day's optimal window.
+
+4. **Optimal date calculation (execute event within 7 days)**: the system calculates the optimal time as in the previous option and additionally determines the best day of the week. By default, a Contact can have multiple optimal days.
+    - If the Contact is within the optimal window at that moment, the event executes immediately.
+    - If the current time and day are before the optimal window, it schedules for the first optimal hour of the next optimal day.
+
+
 .. vale off
 
 Triggering Campaign events

docs/configuration/settings.rst

@@ -158,6 +158,22 @@
 
 * **Use summary statistics** - Improves performance when viewing a Campaign with thousands of events per day by using summarized data. When you first turn on this setting you need to run a :ref:`cron job<campaign cron jobs>` to summarize existing data.
 
+Optimal for Contact event scheduler
+===================================
+
+.. image:: images/optimal-event-scheduler-settings.png
+  :width: 600
+  :alt: Screenshot showing Optimal for Contact event scheduler settings configuration in Mautic
+
+The optimal for Contact event scheduler settings allow you to configure the default timing and caching options used in the optimized event scheduler for Campaigns.
+
+* **Default Optimal Start Hour** - Set the default start hour for the optimal interaction window when specific Contact data is unavailable.
+* **Default Optimal End Hour** - Set the default end hour for the optimal interaction window when specific Contact data is unavailable.
+* **Default Optimal Days** - Select the default days of the week that are considered optimal for interaction when specific Contact data is unavailable.
+* **Interaction Data Cache Timeout** - Choose how long the interaction data should be cached.
+* **Fetch Interactions From** - Select the time frame for fetching interaction data. This determines how far back the system will look for interactions.
+* **Interaction Fetch Limit** - Set the maximum number of interactions of each type (for example: Page hits, Email reads, Form submits) to retrieve for timing optimization.
+
 Email settings
 **************