Fundraising/Data and Integrated Processes/Acoustic Integration/Snooze

Acoustic has a mechanism called 'Snooze' which allows people to opt our of receiving communications for a period (most frequently 90 days). The interaction between this feature the remind-me-later feature in Acoustic is complicated and there are many phabs / discussions about managing this all via WMF Forms / CiviCRM in the hope of reducing complexity / increasing control. 
===== How is snooze represented in the database? =====
Acoustic is represented in 2 ways within Acoustic and 1 within CiviCRM. We have processes to try to keep the 3 in sync.
* Acoustic has a hidden system field where it stores the snooze end date. This is not available in the Acoustic UI when viewing a contact or when querying the contact, although we are able to access it via the api and we display this field in the CiviCRM UI as internal_system_snooze_end_date. This field is what Acoustic looks at to exclude or include contacts in emails
* Acoustic has a (new as of Feb 2025) 'normal' query-able field called snooze_end_date . This field does not have Acoustic functionality attached, but it can be used in queries within Acoustic (which are evaluated at different points in time than the internal_system_snooze_end_date
* CiviCRM has a custom field attached to the email which can be manually edited from within the CiviCRM UI
===== How do they get snoozed? =====
One of
1) Acoustic-initiated-snooze - ie Clicking on a link from a bulk email that takes them to an Acoustic page where they can unsubscribe or snooze
2) CiviCRM-initiated snooze - ie Interacting with a WMF staff member who edits the snooze_date field attached to their email address in CiviCRM. Adding a date to that field initiates a process whereby that value is pushed up to Acoustic as the snooze date.
===== How do they get un-snoozed? =====
Generally they are unsnoozed once the snooze end date passes. 
However, Acoustic will also unsnooze them in they fill in a Remind-Me-Later form provided by Acoustic. We view this as an unintentional un-snooze. Many users choose Remind me later in order to make the banners go away but internal Acoustic logic (by design) interprets this being the end of any snooze period. At this point the internal_system_snooze_end_date is removed within Acoustic (neither the CiviCRM field or the other Acoustic field are changed when this happens).
===== What emails do they get/ not get when snoozed =====
They still get any emails initiated from CiviCRM including thank you emails, civimails, and user initiated emails. They do not get Acoustic 'campaign emails' (ie the normal planned emails). 
However, there is a 3rd category 'non campaign emails' - ie Remind me later emails. The Remind me later campaign emails do a calculation of who should be emailed when the campaign is initiated and before each email but contacts who are "eligible, but snoozed" are still included in these calculations as "eligible but delayed". A snoozed contact who is eligible for an email will be sent it once their snooze ends or is removed if the remind me later campaign is still running even if they no longer meet the criteria at the point of send. ie someone who clicks remind me later and then chooses to snooze on receiving the first email will receive the second and subsequent emails when their snooze expires even if they have donated in the meantime - an action that would normally make them ineligible. As of February 2025 we are syncing the system snooze date into a query-able field snooze_end_datethat can be included in the criteria in order to prevent this. This relies on the criteria being consistently included.
===== What do we do to sync snooze data =====
* When a snooze date is added to an email within CiviCRM (by a user or by code) we kick of process to update both the internal_system_snooze_end_date and the snooze_end_date in Acoustic
* We have a process to pull in all web events that take place directly in Acoustic - we import these into CiviCRM as activities and if the event appears to be a snooze we update the snooze field in CiviCRM with the end date (triggering an update back to Acoustic) 
* We have a scheduled job that gets all emails with a snooze date added in the last 200 days (based on the modified date on the snooze record) in CiviCRM and checks the end dates in Acoustic are set appropriately. If not it initiated a re-snooze to restore any data that has been lost via the Remind me later. This job is fairly intensive as it has to look up each contact individually in Acoustic. As of writing it runs twice a day at 11.05 and 23.05
===== What does snooze data look like in the UI =====
Where 	Image
In CiviCRM it shows up on the Contact summary page 	
There is a link to see the Acoustic data from the Mailing Events page 	
On this page the data is fetched from Acoustic in real-time and displayed - note the snooze_fields_match is just a basic comparison of the 2 fields	
Only the visible field can be seen directly in Acoustic 	
===== Api Details =====
The relevant api actions are
* Omnicontact.snooze - queues the snooze to be actioned into the CiviCRM Queue mechanism to be processed by co-worker
* Omnicontact.create - actions the snooze
* Omnicontact.get - retrieve the details about a contact from Acoustic - note we can only retrieve internal_system_snooze_end_dateon a single contact basis :-( so we have to iterate through
* Omniactivity.load - retrieves web actions from Acoustic and creates activities - this is how we find out about snoozes directly in Acoustic. It is a bit fragile because it relies on the Acoustic forms matching expected patterns
* Omnicontact.verifySnooze - finds records in log_civicrm_value_email that were inserted/altered/removed in the last x days (scheduled job set to 200) and if they still have a future snooze date in CiviCRM retrieves the data from Acoustic to check they are still snoozed in Acoustic and if not queues them up to be snoozed