CRMs & Field Management Systems
      Back to home
      1. Help Center
      2. Integrations
      3. CRMs & Field Management Systems

      Salesforce Enterprise

      What is the Salesforce Enterprise integration, how it works, and where to begin.

      Table of Contents


      What is the Salesforce Enterprise integration?

      The Salesforce Enterprise integration offers all the same benefits as our legacy Salesforce integration...and more! With increased functionality and customizability, the new integration was designed to support the needs of both small businesses and enterprise users.

      What does the integration do?

      The integration is bi-directional: While active, the integration will sync new and updated Salesforce data into Hatch every 15 minutes. It also allows you to automatically push records of Hatch campaign or communication events back to the associated Salesforce record.

      To get started, open the App Marketplace in your Hatch workspace and follow the setup instructions below.

      How do I set up the integration?

      Requirements

      • API access is required. The minimum Salesforce plan including API access is the Enterprise edition. If you are on the lower tier Professional edition, you may purchase API access as an add-on. 
      • Sufficient API bandwidth. Salesforce does place a daily limit on the number of requests to the API that can be made by your Salesforce instance. In most cases, this limit should not be an issue. However, if you have many integrations using the API or are syncing massive amounts of data between Hatch and Salesforce then your API request limit is something to be aware of. 
      • We generally recommend using Admin credentials when authorizing the integration, to ensure that permissions are granted to all the necessary read/write capabilities. Ideally, you will want to authorize the integration with credentials that will ensure stability.

      Setup Instructions

      The integration uses OAuth protocol to provide access to the Salesforce APIs. All you need to do is click Connect to establish the connection. 

      Configuration Options

      The new and improved Salesforce integration offers a multitude of customization options that users can configure.  The next sections will go into further detail on how to configure what data will be synced between Hatch and Salesforce. 

      What Salesforce data is available in Hatch? 

      Hatch has defined three types of opportunities that can be generated by the integration: our standardized default objects, custom objects, and advanced custom objects. Each object that you choose to sync with Hatch generate an individual Hatch opportunity.

      Standard Objects

      Hatch has pre-defined a set of standard Salesforce objects that are readily available to sync with Hatch: 

        • Lead
        • Opportunity
        • Contact

      All three can be toggled on and off at will. Hatch will pull all fields present on these objects (including custom fields) and automatically map the necessary information into the Hatch Contact schema. 

      In some cases, the Contact may be unnecessary as a stand-alone Hatch opportunity. The Lead and Opportunity objects will automatically include the details from the related Contact, as these are necessary to turn the objects into Hatch contacts. Unless there is a specific workflow being used that is reliant on the Contact object, it is recommended to leave  this turned off. 

      Custom Objects

      In addition to the objects Hatch has pre-defined, the integration allows you to define your own custom objects to sync. This includes both standard Salesforce objects and/or objects that may be fully custom to your organization.

      When adding a Custom Object to your integration, you will be able to choose from a dropdown list of the available objects pulled from your Salesforce instance:

      Tip: start typing to scroll through the list of objects!


      Since Hatch has not defined the data schema for these objects, users will need to map the fields from Salesforce into the Hatch contact schema.  In order for your custom object to function correctly, your Salesforce object must include one of the following:

        • the fields required to create a Hatch contact (Name, Phone, Email)
        • a field with a lookup relationship to the Salesforce contact. The integration will automatically access that lookup and pull in the related contact information. 

      If the object you desire does not include this information, please consult with your Salesforce admin on a solution.

      Please note that this option does still have some limitations, primarily related to limitations in SOQL. For example:

      • The SOQL we are using to pull the object as well as its related Contact cannot support polymorphic fields. Polymorphic fields are fields that contain a lookup relationship to more than one object type (for example the relationship can be a Lead or a Contact). If you attempt to configure an object and receive the below error, you will need to use the Advanced Custom Object to configure this instead. 
        Screenshot 2024-08-05 213348

      Advanced Custom Objects

      If you need to enable syncing of a more complex Salesforce model into Hatch contacts, this option may be for you: if a technical user within your org can identify the SOQL query to join the needed data together, then you may create an "object" for Hatch to sync with by directly inputting that SOQL. 

      SOQL can and should be tested first in your Salesforce dev console. We strongly recommend the assistance of a Salesforce admin or developer for use of this option as it may require advanced knowledge of your Salesforce data model and SOQL syntax. 

      If invalid SOQL is used to create a Hatch object, it may cause failures within the integration.

      To add an Advanced Custom Object to your integration, the key will be the name of the object and should match the API name of the base object in Salesforce (this will allow pushcomms to be sent back to Salesforce). The value will be a string containing your SOQL query.

      Please note that this option does still have some limitations, primarily related to limitations in SOQL. For example:

      • SOQL will only allow for a single WHERE clause per query. Since Hatch is using the WHERE clause to control the sync time range, it is not available for use in the custom object model (syncs will fail to complete). 

      Defining Custom Objects

      In order to sync custom objects into Hatch, those objects need to have certain information mapped from the Salesforce fields into the equivalent Hatch fields. If the fields are not mapped correctly, the integration may fail to create contacts or create contacts with incomplete information.


      The integration will pull in all of the available fields from the Salesforce object and an example contact to help visualize the data. 

      Tip: The example contact will be the most recently modified record. If you want to use a different example contact, navigating back will refresh the selection


      As best practice, the following information should be defined within your custom object:

      • Hatch Contact's First Name 

      • Hatch Contact's Last Name

      • Hatch Contact's Phone Number

      • Hatch Contact's Email

      • Hatch Contact's External ID (The ID of the Salesforce object record. This is typically a system field name ID or Record ID)

      • Hatch Contact's External Contact ID (The ID of the related Salesforce Contact. This is typically a system field name Contact ID or Who ID )

      • Hatch Contact's External Created At (The datetime that the record was created in Salesforce. This is typically a system field name Created Date)

      • Hatch Contact's External Updated At (The datetime that the record was created in Salesforce. This is typically a system field name Last Modified Date)

      • Hatch Contact's Status (This is not a required field, but can be useful context. We recommend mapping any available field that might give insight into where this contact is in your customer journey)

      Creating a Hatch Contact & Opportunity

      Each of the objects defined in the configuration step will create an individual Hatch Opportunity. 

      Screenshot 2024-08-09 174150

      Hatch determines whether an opportunity should be created or updated based on the External ID field.

      If there is an existent Hatch Opportunity with the same External Id, then that Hatch Opportunity will be updated. If not, a new Hatch Opportunity will be created.

      A Hatch Contact will be created or updated depending on whether or not the Opportunity's contact information (phone or email) are already found in the system. If one of the contact values matches, a Contact will be updated. If not, a new Contact will be created. 

      What information does Hatch sync back to Salesforce?

      Hatch events and/or communications can be sync’d to Salesforce in the following scenarios. These options are configurable during the integration setup. If enabled for a particular object, Hatch will log the records as a completed Salesforce Task on that object. 

      Keep in mind that push communications occur instantaneously. There must be a Salesforce record in Hatch at the time of the communication event in order for the push communication to succeed. 

      • When a Hatch campaign sends a text/email/voicemail to a contact,
      • When a contact calls or sends a text/email/voicemail to a Hatch workspace
      • When a Hatch user calls or sends a text/email to a contact
      • When events occur within a Hatch campaign
        • A contact is launched (added) to a Hatch campaign
        • A contact is sent the first message of a Hatch campaign
        • A contact is removed from a Hatch campaign before it has ended
        • A contact completed a Hatch campaign

      Frequently Asked Questions

      I re-authorized the integration connection, and now my custom object configurations are blank--what happened?

      It's likely that the user who reauthorized does not have access to the custom objects previously configured. Leave the configuration as-is, and have another user with appropriate access re-authorize the connection. Your custom object configurations should reappear once that happens. 

      How are the example contacts pulled for the field mapping? 

      If the object has a "lastModified" field, then the field mapper will use the most recently updated record. This should make it easy to sync in a test contact with all the fields you need. If there is no "lastModified" field, then the first record returned by Salesforce is used. 

      One of the fields I need to map is not available--what do I do?

      It's possible that the field is not present on the contact being used as an example. You can try creating or modifying a test record or ideal record to force the integration to use that as the mapping example. 

      What will the push communications look like in my Salesforce?

      Keeping in mind that there are some configurable options here, the Salesforce Tasks might look something like this: