Salesforce

Sync data between Saleforce & Regal

This guide describes how to sync your Salesforce Leads, Contacts, Person Accounts, or Accounts with Profiles in the Regal app. The integration also supports bringing events related to other Salesforce objects, such as Opportunities and Events, into Regal.

🚧

Sandbox Testing Recommended

Due to the highly varied nature of each organization's Salesforce setup, we recommend first testing out the integration within a sandbox Salesforce org. This will ensure a smooth flow of data between systems and compatibility with other third party software.

Install the Regal Voice Salesforce app & assign Permissions

Step 1: Click here to download and install the latest Regal managed package for Salesforce. See a list of previous versions in the Release Notes section below.

Step 2: Login to your Salesforce org, then select Install for Admins Only, and check the box acknowledging you are installing a 3rd Party App, and click Install.

18661866

Agree to Install 3rd Party App

Step 3: Check "Yes, grant access to these third-party web sites, then Continue.

Step 4: Installation may take up to 10 minutes. Once installed, click Done.

Step 5: Assign users to the Regal Voice permission sets who will use the app. There are two permission sets available:

  • For Admins: Users assigned to this permission set can create and edit configuration objects such as the Regal Voice Configuration, Attribute mapping and Object field mapping config. They also have access to creating, viewing and editing for all other objects (Contact, Lead, Account, etc.)
  • For Managers: Users with this permission set can see config objects, but not create or edit them. Other objects are available for creation, viewing and editing

📘

How to set Permissions in Salesforce

To add the desired permission set to the user, go to Setup > Permission Sets > Select Regal Voice Integration Admin > Manage Assignments. Click Add Assignments button and select users which will need Admin permissions. Start by giving Admin permissions to yourself (select your user, click Assign, then Done). You can later assign the requisite permissions to others.

15081508

Assign Permissions

Configure Data Flow from Salesforce to Regal

Step 1: Map Lead Id to Account and Contact

This step is necessary for Lead conversion to work properly.

  • Go to Setup > Object Manager > Lead > Fields & Relationships. On the top right, click Map Lead Fields. Click Account in the top menu, and map Copy Id in Lead Fields to Converted Lead Id in the corresponding Account Fields dropdown. Click Contact in the top menu, and repeat the mapping. Click Save.

Step 2: Create a new "Regal Voice Configuration" object

This object stores data for user authorization and for more precise synchronization of events from Salesforce to Regal Voice.

  • Click into the apps menu, and search for Regal Voice.
14661466

Search for Regal Voice

  • Click the Regal Voice Configurations tab, then click New.
  • Fill out the form according to your needs and click Save.

Object field descriptions:

  • Regal Voice Configuration Name - name it something descriptive like "{Full Sync Configuration}"
  • API Key - allows sending data to Regal Voice - email [email protected] to get your API key
  • Is Active - check to set this configuration active
  • All profiles are subscribed to {{channel}} - depending on this field, profiles that are created in Regal will be created with TRUE or FALSE parameters for subscribing to voice, sms, email channels
  • Create a new contact if no matches found - check this box if you want new profiles created in Regal that are not already in Salesforce to create a new corresponding record in Salesforce
  • Update contact fields from Regal Voice - check this box if you want updates to profile attributes in Regal Voice to update the equivalent fields in your Salesforce objects
17201720

Regal Voice Configuration modal

As part of the integration, the Regal app publishes the following events back to Salesforce so that they appear on a Lead, Contact, Account, or Person Account's profile in Salesforce. The “Regal Voice Configuration” object allows you to choose which of these events you'd like to save and display.

Events include:

  • Call completed
  • Call recording link available
  • Contact subscribed
  • Contact unsubscribed
  • Contact's attributes were edited
  • Contact assigned to experiment
  • SMS conversation completed
  • SMS message sent
  • SMS message received
  • Call or SMS task was created
  • Call or SMS task was canceled

Step 3: Create new "Object Field Mapping Config" objects

Using this object, you can specify which objects from Salesforce will be synced with Regal profiles. The integration supports Leads, Contacts, Accounts and Person Accounts.

  • Within your Regal Voice Configuration object, go to Object field mapping configs and click New
  • Add entries according to the table below
Your business process is:Object field mapping configs you should create:
starts as a Lead, does not convertLead
starts as a ContactContact
starts as an AccountAccount
starts as a Person AccountPerson Account
starts as a Lead, then converts and managed via Contact (Account also created behind the scenes, but not used)Lead and Contact, not Account
starts as a Lead, then converts and managed via Account (Contact also created behind the scenes, but not used)Lead and Account, not Contact
starts as a Lead, then converts to a Person AccountLead and Person Account

🚧

Do not map more than one of Contact, Account, or Person Account

While mapping Leads + another object is appropriate, mapping more than one of the primary record objects may result in duplicate profiles in Regal and improper syncing in Salesforce.

Object field descriptions:

  • Object field mapping config name - name it something descriptive like "Lead mapping" or "Contact mapping", etc.
  • Object type - select Lead, Contact, Account or Person Account
  • Is Active - whether synchronization is active or inactive for this object type
  • Configuration - select the configuration object defined in Step 2 (should be chosen by default)
17621762

Object field mapping config modal

11391139

Completed Object field mapping configs

Step 4: Create new "Attribute Mapping" objects

These objects store the mapping between the Salesforce object field names and the corresponding field names in Regal Voice, necessary for correctly updating and creating objects.

  • Create a mapping for each field you want to map to Regal Voice.

Object field descriptions:

  • Attribute mapping name - Name it something descriptive, like "Lead Phone"
  • Regal Voice attribute name - See the table below for basic fields to map. For any additional fields you want to map from Salesforce to Regal Voice, the “Regal Voice attribute name” must start with “traits.” For example, if you want the Salesforce field "Lead Source" to push through to the Regal Voice profile, the Regal Voice attribute name can be "traits.leadSource." They will show up on the contact profile in Regal Voice.
  • Salesforce field API name - to find the API name of a field, go to Setup > Object Manager > Select Object of interest > Fields & Relationships.
  • Object field mapping config - select the appropriate Object field mapping config created in the previous step.
  • Regal Voice Configuration - select the Configuration this mapping is activated by.
849849

New Attribute Mapping Prompt

Basic fields to map include:

Salesforce FieldRegal Voice AttributeNotes
Phonetraits.phonerequired to create a contact in Regal Voice
Emailtraits.email
FirstNametraits.firstName
LastNametraits.lastName

For some fields you will want to create duplicate mappings - one for each object type that is relevant. For example, if your prospective customers start off as Leads and then at some point convert to Contacts, you should create similar field mappings for both Leads and Contacts. Usually Leads have a more limited set of fields so you just have to map those that are relevant for each object.

10801080

Basic mappings for Lead and Contact objects

📘

Salesforce Field/API names

To find API names of the fields of an object in Salesforce, go to Setup by clicking on the gear icon in the upper right corner of the page. Then select the Object Manager tab, open the object of interest, and select Fields & Relationships. Here you can see all fields with their Salesforce Field name. You can also explore the Salesforce Reference Guide.

16181618

Where to Find Salesforce Field Names

📘

Mapping Address Information to Regal

Regal supports syncing of address data, but requires a specific mapping pattern due to the way it is represented in Regal. For example, in order to map City you need to create an Attribute mapping where the "Regal Voice attribute name" is "traits.address.city". See additional examples below:

Salesforce FieldRegal Voice Attribute
Streettraits.address.street
Citytraits.address.city
Statetraits.address.state
PostalCodetraits.address.zipcode
Countrytraits.address.country

📘

Mapping Opt In information from a field

If all of your Salesforce Leads or Contacts are opted in to sms and voice, and you want Regal to automatically opt them in as well, then you don't need to map any fields for optin. Instead just select "All profiles are subscribed to {{channel}}" in the Regal Voice Configuration in Step 2.

If, however, not all Leads or Contacts should be automatically subscribed, then you need to map dedicated optin fields from Saleforce to Regal Voice. To do so, the field in Salesforce must be a checkbox (see Salesforce Field/API names tooltip above). Then you need to create an Attribute mapping, where the “Regal Voice attribute name” is “optIn.voice.subscribed” or “optIn.sms.subscribed." See example below.

849849

SMS Optin mapping example

Step 5: Test Salesforce >> Regal data flow

Now that you've mapped fields from your Lead, Contact, Account, and/or Person Accounts, when you create or update these objects in Salesforce, the corresponding contact will be created or updated in your Regal Voice account. Only those fields of the object that have an “Attribute mapping”, and for which the “Object field mapping config” object was created, will be synched.

  • Test data flow by creating a new Lead object in Salesforce, then checking the Audience page in your Regal Voice account.

A link back to the relevant Salesforce profile will automatically be available in Regal Voice in the profile attribute called salesforceLink. Additionally, the externalId attribute on the profile in Regal Voice point to the Salesforce Lead object ID. If a Lead is converted into a Contact, Account or Person Account, then the externalId attribute is updated to the corresponding object ID.

11741174

Contact in Regal Voice

Enable Data Flow from Regal Voice to Salesforce

Step 1: Connect your Salesforce org via OAuth

These steps are necessary in order for Regal events and data to make their way to your Salesforce organization.

🚧

System Admin recommended

It's highly recommended that a user with the System Admin profile in your Salesforce org is the one who goes through the OAuth flow to connect the Regal app.

  • In the Regal app, go to Settings > Integrations and find the Salesforce tile. Click Connect.

  • In the connect modal, enter the domain name of your Salesforce org. login.salesforce.com works for most organizations unless you have a custom domain name. Use test.salesforce.com if connecting a sandbox org.

  • Click Authenticate and follow the remaining OAuth flow by logging in with your Salesforce credentials. When you're done, you will be redirected back to the Regal app Settings page, where the Salesforce tile will show Connected.

Step 2: Add the Regal Voice Events component to your Salesforce object layouts

Now that you can receive Regal Voice events into Salesforce, the final step is to add a visual component to your Lead, Contact, Account or Person Account pages to display the events.

  • Start by opening any Contact, then click the gear icon in the upper right corner, and select Edit Page.
734734

Edit Page

  • Scroll down the list of components on the left, find and drag the regalVoiceEventsComponent to the place on the profile you want Regal Voice events to appear, and click Save. (If this is your first time customizing this page in Salesforce you'll be prompted to go through an Activation flow. Keep clicking through until it's complete, then click Save.)

  • Repeat for any other objects that you will sync to Regal Voice.

Step 3: Test Regal >> Salesforce data flow

Now you should be able to create and edit contacts directly in Regal Voice, then see the corresponding changes in your Salesforce objects. Only those fields of the object that have an “Attribute mapping”, and for which the “Object field mapping config” object was created, will be synched.

  • Test data flow by going to the agent desktop in Regal Voice and initiating an outbound sms to a new phone number. Try editing the name of the contact or any other attributes that you have mapped. Feel free to send an sms as well.
  • Now go to your Salesforce org, find the relevant object (Lead, Contact, etc. depending on your mappings) and check that there is a new record created by changing Recently Viewed to All Contacts. Click into the record to see also that the Regal Voice Events component now has several events in the feed.
17031703

Regal Voice Events component with several events

This concludes the integration. Explore the Advanced Topics below that may be relevant to your org. If you have any questions about how to install the Regal Voice Salesforce app or which contact properties are important to send to Regal Voice, reach out to [email protected]

Advanced Topics

Tracking Salesforce Opportunities in Regal Voice

Currently there is no concept of an Opportunity object in Regal Voice, but our integration can still receive events related to Salesforce Opportunity creations, updates, and deletes, which can be used to trigger Journey automations.

Created
When an opportunity is created in Salesforce, an event called Salesforce Opportunity Created (along with all of its properties) is sent to Regal Voice and attached to the relevant contact profile in Regal Voice.

Updated
When a property of an opportunity is updated in Salesforce, an event called Salesforce Opportunity Updated is sent to Regal Voice and attached to the relevant contact profile in Regal Voice. This event will only contain the properties that were updated.

Stage Change
Changes to the Stage property in the Opportunity object are treated like any other property change, and will thus trigger a Salesforce Opportunity Updated event with the new stage property included.

Tracking Salesforce Calendar Events in Regal Voice

Similar to the Salesforce Opportunities, our integration can receive events related to the Event object, which can be used to trigger Journey automations such as scheduled callbacks.
The payloads will contain:

  • externalId that references the related object so that the Event can be tied to a contact in Regal Voice
  • all properties, including custom properties, of the Event object
  • email and name of the Salesforce User assigned to the Event, which can identify the agent in Regal Voice to make sure tasks are assigned to the right person

Mapping Fields w/ Formulas

This topic pertains to fields in Salesforce that are calculated by other fields. For example, FieldC = FieldA + FieldB. Due to the way Salesforce triggers work, mapping only FieldC is insufficient to keep Salesforce and Regal in sync, but there are two workarounds we recommend:

  1. Create mappings for all fields in the formula, in addition to the calculated field. Using the example above, you would create the following attribute mappings:

Note: Updates in Regal to fieldA or fieldB will update the corresponding fields in Salesforce. This will re-calculate FieldC, but no event will be sent from Salesforce to Regal with the updated value (this is by design to prevent never-ending update cycles). For this reason, we recommend configuring all attributes involved (in this example, fieldA, fieldB, and fieldC) as non-editable in Regal.

  1. Within Salesforce, create another field (e.g. FieldD) that is automatically set every time the calculated field updates, and map only that field.

Note: Because FieldD in Salesforce cannot update FieldC, any updates made to fieldD in Regal will likewise not update FieldC in Salesforce. For this reason, we recommend configuring these attributes as non-editable in Regal.

Backfilling already existing contacts

If you'd like to backfill existing Salesforce contacts into Regal Voice, download your contacts and properties from Salesforce and share the file in a secure way (for example, you can password protect the excel file then email it [email protected] and share the password over slack).

Troubleshooting

I can't install the app, or am unable to configure the object mappings

I created a new Lead/Contact in Salesforce, but don't see anything happening in Regal Voice

  • Check that your Lead/Contact is created with a phone number, which is required to create a Profile in Regal.
  • Check that the mappings in your Regal Voice Configuration exist (and are active) for all the relevant objects and fields. You must map a phone number field to traits.phone in order to create a contact in Regal Voice, as that is the primary identifier in our app.
  • Check that your API key is correct.

I'm unable to convert a Lead to a Contact/Account/Person Account, or the status attribute in Regal Voice does not change after I do convert.

  • Check that you have a mapping for the Lead status field (and that it is active) in your Regal Voice Configuration.
  • Check that you mapped Lead Id to Account and Contact (see Step 1)

I created a contact in Regal Voice, but don't see the corresponding record in Salesforce

  • Check that the "Create a new contact if no matches found " checkbox in your Regal Voice Configurations is selected
  • Check that your reporting webhook matches the Site URL you created in Step 1
  • Check that the regal_voice.RegalVoiceWebhookService Apex Class was enabled in Step 2

Editing a contact in Regal Voice does not update the corresponding record in Salesforce

  • Check that the mappings in your Regal Voice Configuration exist (and are active) for all the relevant objects and fields.
  • Check that the "Update contact fields from Regal Voice" checkbox in your Regal Voice Configurations is selected
  • Check that the "Contact’s attributes were edited" checkbox in your Regal Voice Configurations is selected
  • Check that your reporting webhook matches the Site URL you created in Step 1
  • Check that the regal_voice.RegalVoiceWebhookService Apex Class was enabled in Step 2

I don't see the Regal Voice Events component when I click into a record

  • Check that you followed Step 4 for each Salesforce object that is relevant.

I see the Regal Voice Events component, but no events in the feed

  • Check that the appropriate checkboxes for Regal Voice Events in your Regal Voice Configurations are selected
  • Check that you are able to update a contact in Regal Voice and see the corresponding change in Salesforce

Release Notes

  • v 1.24 - 9/30/2022
    • fixed bug: if Lead/Contact/etc. is created in Salesforce without a phone number, no event was sent to Regal. Now we do want to create contacts in Regal even if there is no phone number.
    • fixed bug: decimal/currency fields not updating in RV >> SF direction. Now we can infer from the type of the mapped field whether to attempt to convert the string from Regal.
  • v 1.22 - 9/20/2022
    • fixed bug: if more than 10 attribute mappings exist for an object, updates in RV >> SF direction would fail
    • fixed bug: sms sent, received, conversation completed events did not show in Regal Events component if "All profiles are subscribed to sms" was unchecked. Also fixed similar issue for voice related events.
    • fixed bug: in RV >> SF direction, text fields that were too long caused an error. Now data will be truncated without returning an error response to Regal.
    • fixed bug: incorrect domain on salesforceLink in custom properties.
  • v 1.21.6 - 9/8/2022
    • improvement: support SF >> RV updates for address mappings
    • improvement: implemented daily logging for all caught exceptions
    • fixed bug: if any invalid mapping existed, all updates from RV >> SF would fail
    • fixed bug: updates to Opportunities were not flowing to Regal in all cases
    • fixed bug: "contact was created" checkbox in config was in the wrong place. Moved to Events section of config.
  • v 1.20.16 - 8/18/2022
    • new feature: SF Event object triggers events to Regal
    • new feature: SF Account object can sync w/ Regal contacts
    • improvement: catch all exceptions in the app without causing brand's operations to fail
    • fixed bug: RV >> SF attribute updates did not work for custom properties

Did this page help you?