Using Salesforce with Customer.io Journeys
When you set up a Salesforce source for use with Customer.io Journeys, you’ll need to map your Salesforce data to people, custom objects, or events.
You’ll set up a sync for each kind of data you want to send through your pipeline. In most cases, you’ll want to follow our typical mappings. But the way you map your data to Customer.io depends on what you want to do with it—send messages, use it to trigger messages, or manage relationships!
Typical mappings
Remember, you’ll convert your Salesforce data to people, events, custom objectsNot to be confused with a JSON object, an object in Customer.io is a non-person entity that you can associate with one or more people—like a company, account, or online course. You can use objects to message people based on changes to their company, account, or course itinerary., or relationships. You’ll see our typical mapping suggestions below.
Notice the * next to Leads! Leads fill multiple roles in Salesforce, so you might map them to people, objects, or both. We’ve provided more information about leads below to help you figure out how you want to map them to Customer.io.
| Data Pipelines entity | Source call | Typical Salesforce objects |
|---|---|---|
| People | identify | Contacts, Leads* |
| Events | track | Tasks |
| Custom Objects | group | Accounts, Opportunities, Campaigns, Leads* |
| Relationships | group | Account-Contact Relationships, Opportunity-Contact Relationships |
The image below doesn’t show relationships. That’s because relationships aren’t a type of data themselves; rather, they’re a relationship between two data types. You won’t sync relationships unless you have two other data types you need to relate to each other. For example, if you only sync contacts, you won’t need to sync relationships. But if you sync contacts and accounts, you’ll need to sync relationships to relate contacts to accounts! See Relationships: matching people to objects below for more information.
What Related Record ID do I set for a Custom Object?
In most cases: you don’t need to set a Related Record ID when you sync custom objects to Customer.io Journeys. We use the userId to map a person to a custom object, but it’s not very useful unless you only care about the relationship between an object and its owner or creator in Customer.io. You’ll get far more value out of syncing relationships than you will by associating a single userID with an object/group.
When you sync relationships then you’ll need to set both userId and groupId fields—and your choices will be much more obvious. For example, when you sync Account Contact Relationships, your choices for userId and groupId will be the Contact ID and Account ID respectively. “Account” and “Contact” are right there in the names!
But when you simply look at an account, you might see fields like Owner ID, Master Record ID, or Created By ID. These fields are unlikely to change, and they’re not very useful unless you only care about the relationship between an object and its owner or creator in Customer.io.
Relationships: matching people to objects
Salesforce treats people, custom objects, and the relationships between the two as discrete pieces of information. For example, when you sync accounts and contacts to Customer.io, you’ll also sync Account Contact Relationship information to capture relationships between your contacts and accounts. This applies whenever you need to capture a relationship between people and a group—like opportunities, companies, etc—you’ll need to set up a relationship sync to maintain those relationships.
Where people need a userId, and custom objects need a groupId, relationships need both. When you sync relationships, we associate the userId with the groupId. And, like people and custom objects, relationships also contain traitsA key-value pair that you associate with a person or an object—like a person’s name, the date they were created in your workspace, or a company’s billing date etc. Use attributes to target people and personalize messages. Attributes are analogous to traits in Data Pipelines. describing the relationship—like whether someone is directly related to an account, a primary contact, and so on. These attributes help you find the right person by association with an object, like when you need to find an account’s primary contact, or all active participants in an opportunity.
How do I know if data is a person, event, or an object?
We’ve created a little decision tree to help you map data accordingly, but in short:
If you want to send messages to it, or you want to log events it performs, it’s a person.
In Customer.io, people are the basic unit you’ll operate against. People can receive messages and perform events. Objects themselves can’t receive messages or perform events. Think of it this way: an opportunity doesn’t have an email address; you’ll never send a message directly to an opportunity; an account can’t visit a page on your website. Those are things people do!
If something is related to people and the data has a lasting impact, it’s probably an object.
Custom objects are things that people are related to—like an account they belong to, a company they work for, or an opportunity they represent. They’re like people, in that they have attributesA key-value pair that you associate with a person or an object—like a person’s name, the date they were created in your workspace, or a company’s billing date etc. Use attributes to target people and personalize messages. Attributes are analogous to traits in Data Pipelines. and, unlike events, they’re important long after they initially appear in your workspace.
If something represents people’s activities, it’s probably an event.
Events are things that people do, like when a user visits a page on your website, adds an item to their shopping cart, or watches a video. Events are really useful for responding to people’s activities in an automated way, like sending a calend.ly link to people who want to hear from you about your product.
than one person?} d-->|yes|e(It's an object) c-.->|no|d d-.->|no|f(It's either an event
or you don't need it)
Are leads people or objects?
In Salesforce, a Lead represents multiple things: it’s an unqualified contact, an unqualified company, and an opportunity. Because a lead in Salesforce could be both a person or an object in Customer.io, you’ll want to map it based on what you want to do with your leads downstream.
- (Recommended) map leads to people: If you want to send messages to your lead, attempting to qualify and nurture them, then they must be people. This is the most common use case when sending leads to Customer.io Journeys.
- If you just want to track the opportunity or company represented by a lead until you have a qualified contact, you can map them to objects. But remember: you must have a person that you want to relate the object to!
- If you want to capture a lead as both a person and an object related to that person, you can set up two separate syncs that map leads to both people and objects!
When you qualify a lead in Salesforce, the record splits into those three things: a Contact related to a Company and an Opportunity. If you sync all three data types to Customer.io, then you’ll create or update records when you qualify the lead in Salesforce. So, whether you bring in a lead as a person or an object, it can eventually become a person and two related objects when you process or qualify it.
ready for you to act on?} d-->|yes|e(Salesforce lead
graduates into:) e-->f(Contact) e-->g(Company) e-->h(Opportunity) d-.->|no|i{Is the the lead old, or did they
respond negatively to outreach?} i-->|yes|j(Lead fails
to graduate) i-.->|no, continue
nurturing lead|d
Tasks are often events
In general, we suggest that you map tasks to events because:
- Tasks, like events, are assigned to a single person
- They represent things that people do
- You can use events to trigger campaigns, automating your task Salesforce list
Tasks in Salesforce are basically a single person’s to-do list for leads, accounts, opportunities and so on. While Salesforce doesn’t have a concept of “events,” tasks fit this bill, more or less, by changing states when you mark something off the to-do list.
Think of it this way: You aren’t likely to manage your task list in Customer.io. Instead, you probably want to automate your tasks or respond to changes in your to-do list. You may want to send a message to a contact when their bill is due, or send a message that invites a lead to schedule a meeting with you.
Convert your timestamps
Customer.io and Salesforce use different formats for dates and times! Customer.io Journeys uses Unix timestamps in seconds, while Salesforce uses ISO 8601 formatted dates and times. So, you need to convert a Salesforce date like 2021-03-22T10:00:00Z to a Unix timestamp like 1616425200 when you send data to Customer.io.
We do this with a single setting for each actionsThe source event and data that triggers an API call to your destination. For example, an incoming identify event from your sources adds or updates a person in our Customer.io Journeys destination.. Before you send data from Salesforce to Customer.io, you should go to the Actions tab, and set the Convert dates to Unix timestamps setting to true for each action.
You need to convert timestamps again if you send data back to Salesforce
When you send data to Customer.io, you’ll convert dates and times to Unix timestamps. But if you send data from Customer.io to a Salesforce destination—like you might do with message metrics or webhooks—you’ll need to convert those timestamps back to ISO 8601 formatted dates and times.
