Record Sync

Keep Five9 lists aligned with Salesforce Campaign Members, Leads, and Contacts.
Campaign Members go to the list assigned to their campaign. Leads and Contacts
sent without a campaign go to their object's default list. Real-time changes
and bulk imports are handled automatically.

Currently supported: Salesforce → Five9.

Quick start

Setup is shared by a QuickFlo admin and a Salesforce admin. You only need to
answer two questions:

1. Which Five9 list should receive the record?
2. Which Salesforce fields should be sent to Five9?

How Record Sync chooses the list and fields

Salesforce record	Five9 list comes from	Five9 fields come from
Campaign Member whose person is a Lead	record_sync_settings → five9 → listNameByCampaign	record_sync_field_mappings → Lead
Campaign Member whose person is a Contact	record_sync_settings → five9 → listNameByCampaign	record_sync_field_mappings → Contact
Lead sent without a campaign	record_sync_field_mappings → Lead → listName	The same Lead record
Contact sent without a campaign	record_sync_field_mappings → Contact → listName	The same Contact record

The campaign mapping always wins for a Campaign Member. The Lead.listName and
Contact.listName defaults are used only for records sent without a campaign.
An unknown campaign does not fall back to a default list; it waits safely on
the dashboard for an admin to map or ignore it.

1. Connect Five9 and copy its names

1. Install Record Sync and create a Five9 connection named five9.
2. Run record-sync-list-five9-lists to see the exact Five9 list names.
3. Run record-sync-ingest-contact-fields to load the available Five9 fields.

Use the names exactly as Five9 returns them.

2. Configure destinations and fields

You will edit only two data stores.

If you use Salesforce Campaign Members

Open the existing five9 record in record_sync_settings. Keep the other
installed settings and edit listNameByCampaign so each Salesforce campaign
name points to one Five9 list name. Leave dryRun: true during setup.

For example, these properties map two campaigns:

{
  "listNameByCampaign": {
    "Renewal Outreach": "Renewal Dialing",
    "Welcome Campaign": "New Customers"
  },
  "dryRun": true
}

Do not replace the whole installed five9 record with this short example;
change only these properties in the existing record.

Configure each Lead or Contact object

In record_sync_field_mappings, create or update a record with key Lead and
a record with key Contact when you use both person types. Each record does two
jobs: fieldMappings chooses the fields sent for that object, and listName
chooses its default Five9 list when the record is sent without a campaign.

{
  "fieldMappings": {
    "fields": {
      "id": "salesforce_id",
      "FirstName": "first_name",
      "LastName": "last_name",
      "Phone": "number1",
      "Email": "email"
    },
    "addKeys": ["salesforce_id", "number1"],
    "deleteKeys": ["salesforce_id"],
    "callNowField": "",
    "callTimeField": "",
    "callNowMode": "NONE"
  },
  "listName": ""
}

Change the Salesforce and Five9 field names as needed, but keep these identity
settings unchanged:

• id maps to salesforce_id.
• addKeys includes salesforce_id.
• deleteKeys is exactly ["salesforce_id"].

Set listName according to how the object is used:

What you sync	Lead.listName or Contact.listName
Campaign Members only	Leave it blank. The campaign mapping chooses the list.
Leads or Contacts without campaigns	Set it to that object's default Five9 list name.
Both	Set the default list. Campaign Members still use their campaign's list.

For example, set Lead.listName to "General Leads" to send Leads received
without a campaign to that Five9 list. This does not change where Campaign
Members whose person is a Lead go.

3. Connect Salesforce

1. Install the QuickFlo Connector for Salesforce.
2. Add the QuickFlo endpoint under Remote Site Settings and assign the
   QuickFlo Admin permission set.
3. Open QuickFlo Setup and enter the Record Sync webhook URL and API key.
4. For Campaign Member sync, activate CampaignMember plus Lead and/or
   Contact for the member types the customer uses. For records outside
   campaigns, activate Lead and/or Contact directly.
5. Enable Automatic Hourly Re-send under Advanced.

Full Salesforce installation details are in the
Salesforce setup guide.

4. Test and go live

Use an empty Five9 list for the test.

1. With dryRun: true, add one person to a mapped test campaign, or create or
   update one test Lead or Contact that uses a default list.
2. Open Salesforce → Five9 Record Sync and confirm there are no failures or
   campaigns waiting for a decision.
3. Set dryRun: false.
4. Repeat the test and confirm the person appears in the expected Five9 list
   with the expected fields.
5. If testing Campaign Members, remove the member and confirm the person leaves
   the campaign's Five9 list.

If the Five9 list already contains records, ask QuickFlo support to reconcile it
before go-live.

Campaign Member rules

• One Salesforce campaign owns one Five9 list. Do not map two campaigns to the
  same list.
• A campaign can contain both Leads and Contacts. Each uses its own field
  mapping; both land in the campaign's mapped list.
• Removing a Campaign Member removes that person from the mapped list.
• Campaign names are used during setup. Record Sync pins the Salesforce
  campaign ID when it first sees the campaign, so renaming the campaign later
  does not silently change its destination.
• Leave Lead.listName and Contact.listName blank unless records outside a
  campaign also need a default Five9 list.

If several teams need one combined Five9 audience, use one combined Salesforce
campaign rather than sharing a Five9 list across campaigns.

Daily operation

Open Salesforce → Five9 Record Sync and check the two cards at the top:

What you see	What to do
Both numbers are zero	Nothing. Record Sync is operating normally.
Campaigns waiting for a decision	In the campaign table, copy the campaign name and ID. Run salesforce-five9-record-sync-campaign-action and choose Map with an unused Five9 list, or Ignore.
Failed syncs	Read the recent error, fix the connection, list, or field mapping, then run salesforce-five9-record-sync-retry-failed.

During maintenance:

• Set paused: true to queue new Salesforce changes without sending them to
  Five9. Set it back to false to resume and drain the queue.
• Set dryRun: true to test the flow without changing Five9.

Moving a live campaign to another Five9 list or repairing a list that already
contains records requires a guided reconcile. Contact QuickFlo support rather
than editing the campaign registry.

Troubleshooting

Problem	First check
No Salesforce events appear	Verify the Salesforce connector is active and its webhook test succeeds.
Events arrive but nothing reaches Five9	Check paused, dryRun, the Five9 connection, and the dashboard's campaign-decision card.
Five9 rejects a record	Confirm the list name and mapped Five9 fields still exist, then retry failed records.
A bulk import is still processing	Check the dashboard. Bulk work is intentionally paced to Five9's limits and does not block real-time changes.

The package's queues, campaign registry, list-owner index, leases, and recovery
records are internal. Admins should not edit them directly.

Advanced use

Most installations do not need anything beyond the quick start.

• To sync Leads or Contacts that are not Campaign Members, set the object's
  listName to a dedicated Five9 list.
• To change the Five9 record shape or split several phone numbers into
  separate records, edit salesforce-five9-record-sync-record-builder.
• To enable Five9 call-now or scheduled-call fields, update the corresponding
  Lead or Contact field-mapping record.
• Use campaign reconcile only with QuickFlo support. It is a repair and
  cutover tool, not routine administration.

Help

For setup help, contact support@quickflo.app. Include the Salesforce campaign
name, Five9 list name, and the error shown on the Record Sync dashboard.

Membership contract (schema v3)

The authoritative engineering contract is maintained in
docs/salesforce-five9-record-sync-v3-contract.md. It is not required to
install or operate the package.