Fundraising/Data and Integrated Processes/SMS

In December 2024 we started harvesting SMS numbers via the Remind-me-later tab on the donation form. 
==== Relevant links ====
# Acoustic documentation - the rest of our fr-tech Acoustic docs
# Project summary - early planning document, contains information about the consent legal requirements
# Banner flow - screenshots of what the potential donor sees
# Donor relations SMS document - includes discussion / images of what the future flows will look like
# Consent record phab - discussion of consent record handling
# Swagger - Acoustic rest api test harness - can test api calls using credentials from live via this webpage
# Search Kit - shows donations that have come in via SMS so far
==== Donor flow (1) - currently implemented ====
# The potential donor clicks on 'Remind me later' on the donation form.
# The potential donor then is encouraged to text "Wikilove" to our short-code (ie 21526, the SMS number allocated to us).
# A record is created in Acoustic. The record will only have the phone number in the (Acoustic mobile_phone field) and the Acoustic identifier (the recipient_id). If a match is found on the phone number the record is updated but as of December 2024 there is no pre-existing data to match on
# The donor receives a text from Acoustic in response to that telling them that they are opted in and how to log out. This exchange constitutes consent and is a subject to regulation.
# Within a day the potential donor will receive a text with a donation link. This donation link will include the recipient_id in the url - ie. recipient_id=xyz
# The donor fills in the Donation form giving name and email details, but we do not collect phone details. This submission is queued, including the recipient_id from the url
# When the donation is processed into CiviCRM we have the recipient_id but not yet the phone number. The donation is processed, with the custom field channel in the Gift Data custom group set to 'SMS' (ie civicrm_value_1_gift_data_7.channel or at the php level Gift_Data.channel). Normal efforts are made to match existing contacts based on name and email information and a contact is created or updated, with a dummy phone record being created. This dummy record
## has the number 99999
## has custom data attached to it (not easily viewable through the UI at this stage but stored in civicrm_value_phone_data) holding the recipient_id, source and update date . (entity_id in this table refers to civicrm_phone.id)
## has the location type of 'SMS Consent' and phone type of Mobile (ie civicrm_location_type.name = 'sms_mobile')
## will be created if the contact does not have an SMS_Consent phone number already. If they DO have an SMS Consent phone number that will be overwritten on the assumption that Acoustic is the canonical source of this data
# A scheduled job (omniphone_update) will run (hourly at minute 17) to find instances of the dummy phone. A query is sent to Acoustic to find out the real phone number and the details of the consent given. The following data entries take place
## The phone number is updated, along with the update date of the phone
## The consent data is saved to the table civicrm_phone_consent- saved values are country_code, phone_number, master_recipient_id, consent_date, consent_source. This table is not linked to the contact or contact's phone record but rather holds information relevant to the phone number.
## An activity is created against the contact specifying the consent was given
# At this stage no data is flowing back to Acoustic regarding these donations. 
==== Future flows ====
Trilogy and the email team are currently investigating 2 further flows
1) the potential donor enters their phone number on the form and gives consent that way. This is the same as the implemented flow and from a data point of view the only difference is the source on the consent record.
2) the potential donor texts 'DONATE' to our short code. This results in a donate link being sent out immediately. This interaction does not constitute the giving on ongoing consent
==== Consent records ====
Currently this phab is tracking our handling of consent records. At a high level Acoustic holds consent details against a combination of a recipient_id and a phone number. In Acoustic-land a recipient_id is attached to a specific email (unless we change that in the future) so a phone number that is consented against a contact with one email is not consented if it is matched to a contact on donation or merged into a contact with a different email - we need to track the consent data and push up the consent against the new contact. In addition we need to figure out where the remove contact Information has changed. I am investigating leveraging the omimgroupmembers.load job we use for getting RML email contacts to also retrieve RML consent data. I have created group 44499666 holding contacts who have opted into our 2 way programme in the last 14 days and 44499670 for recent opt outs and have had (some) success retrieving them with this api call 
drush @wmff cvapi Omnigroupmember.get group_identifier=44499666 mail_provider=Silverpop start_date="14 days ago" 
The load function will need more tweaking as that does the saving 
==== Process gaps ====
# Update job written but not yet scheduled
# What happens when a contact is deduped?
# Ensuring re-consenting is done per this phab
# Can we see the messaging history - ie how many appeals they have received in Civi somehow
# Allowing donors to opt out via Preference centre
# UI visibility of the SMS consent data (custom fields extending the phone record)
# How do we deal with the possibility of the consent situation having changed in Acoustic - ie I don't think we can be notified when someone opts out after opting in - so our Civi data would be out of date - we could maybe search for contacts with a mobile_phone in Acoustic each day & then query them one by one - is that feasible?
# Send data back to Acoustic - Potential places it would be represented are
## Field 'both_funds_latest_donation_source'
## field mobile_phone
## consent information attached to the phone number
# We are not currently pushing any existing phone data from Civi to Acoustic. If we did so it might create a few more matches when they first fill in the form but on the other hand we have limited phone data of suspect quality and if we do NOT push it up (where I am leaning) then if mobile_phone is non-empty at Acoustic it is an SMS contact & that can be used for other queries