Customer.io Destination
UpdatedAbout this integration
Sending data into your Customer.io workspace lets you take advantage of various sources to gather customer data, personalize messages, and trigger complex workflows. You can send data to different workspaces, to gather data for different messaging use cases.
Getting started
Go to the Data Pipelines tab and click Connections.
Click Add New under Destinations.
Select the Customer.io Journeys destination.
(Optional) Select the sources that you want to connect to this destination. You can always connect sources to your destination later. We’ll only show you eligible sources.
Configure your destination.
Site Id: Customer.io site ID. This can be found on your API Credentials page.
Api Key: Customer.io API key. This can be found on your API Credentials page.
Account Region: Learn about Account Regions.
Endpoint: The URL of the Customer.io API
Click Enable Destination.
Actions
Be careful when editing Customer.io Journeys destination’s actions
The Customer.io Journeys destination is how data gets into Customer.io—the people, events, and other data that you’ll use to send messages to your audience. It’s already configured with 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. to support incoming data from your sources. You can edit these actions if you want to change how we handle incoming data, but take care not to inadvertently break integrations with Customer.io.
When you’re done setting up your destination, you can go to the Actions tab to see how we map source events to your destination.
Action | Default Trigger | Description |
---|---|---|
Create or Update Device |
| Create or update a person's device. |
Delete Device |
| Delete a person's device. |
Delete Relationship |
| Delete a relationship between a person and an object in Customer.io |
Delete Person |
| Delete a person in Customer.io. |
Delete Object |
| Delete an object in Customer.io. |
Create or Update Person |
| Create a person in Customer.io or update them if they exist. |
Track Event | type = "track" andevent != "Application Installed" andevent != "Application Opened" andevent != "Application Uninstalled" andevent != "Relationship Deleted" andevent != "User Deleted" andevent != "User Suppressed" andevent != "User Unsuppressed" andevent != "Object Deleted" andevent != "Report Delivery Event" andevent != "Device Created orUpdated"
event != "Device Deleted" | Track an event for a known or anonymous person. |
Track Page View |
| Track a page view for a known or anonymous person. |
Track Screen View |
| Track a screen view for a known or anonymous person. |
Create or Update Object |
| Create an object in Customer.io or update them if they exist. |
Merge People |
| Merge two customer profiles together. |
Suppress Person |
| Track a "User Suppressed" event to suppress a person. |
Unsuppress Person |
| Track a "User Unsuppressed" event to suppress a person. |
Report Delivery Event |
| Report delivery metrics for a message sent from the Customer.io Journeys product. |
Report Content Event |
| Report a Viewed or Clicked Content event. |
Create or update a person (identify)
Incoming identify
calls add and update people in your workspace. We map traitsInformation that you know about a person, captured from identify
events in Data Pipelines. Traits are analogous to attributes in Customer.io Journeys. in source calls to 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. for people in your workspace. These are things you know about a person, like their first name, their interests, etc.
By default, we send this event when you identify
a person—like when they submit their email address on your website requesting more information, or when they create an account with you.
You’ll typically set relationships between a person and an object and information about the relationship with the group
call. But you can also send this information in an identify
call if you want. When you relate a person to an object through an identify
call, you’ll place the group information in the context
object.
{
"type": "identify",
"traits": {
"first_name": "cool",
"last_name": "person",
"email": "cool.person@example.com",
"plan": "premium",
// include if you want to set relationships/attributes
"objectId": "math101-2024",
"objectTypeId": "2",
"relationshipAttributes": {
"dues_paid": true,
"class_complete": true,
"grade": "A-"
}
},
"userId": "97980cfea0067",
"created_at": "1679407797",
}
Add and update people by ID or email
In Customer.io, you can identify people by an id
or an email
address, which provides a way to work with people if they provide an email address but haven’t generated a backend ID (like when someone signs up as a lead but hasn’t yet become a paying customer). When you send identify
events to this destination, they’ll add or update people in Customer.io depending whether or not the corresponding email or ID exists.
If an identify
request contains either a userId
or an email
trait, and that person doesn’t already exist, we’ll create a person in Customer.io
If an identify
request contains either a userId
or an email
trait, and that person already exists, we’ll update the person in Customer.io
If an identify
request contains both a userId
and an email
trait, but one of those values wasn’t associated with the person, we’ll add the new identifierThe attributes you use to add, modify, and target people. Each unique identifier value represents an individual person in your workspace. to the person and update their profile.
identify
event)-->b{Does it haveemail or ID} b-->|yes|c{Does email
or ID exist?} b-.->|no|d(Not sent to destination) c-->|yes|e(Update person) c-->|no|f(Add new person)
Customer.io Journeys doesn’t support anonymous identify calls yet
We’re working on support for anonymous profiles, but, for now, Journeys ignores anonymous identify
calls.
This doesn’t mean you shouldn’t send anonymous identify
calls—even if Journeys is your only destination. Anonymous still has value if:
- You send data to other, non-Customer.io destinations, many of which support anonymous profiles.
- You use our JavaScript source.
If you use our JavaScript source, anonymous identify
calls store traits in local storage and attach them to subsequent identify
calls. This means that when you formally identify a person later, you won’t need to capture all of a customer’s traits at the same time; the JavaScript source will automatically associate their anonymously-gathered traits with their userId
.
Delete person
You’ll delete people in Customer.io Journeys by sending a track
call called User Deleted
. You can always change the name of the event in the Actions tab of your destination settings.
Deleting a person doesn’t necessarily require a userId
. You can delete a person by their email address, for example. If you don’t include a userId
, we can delete a profile by properties.email
. If you include both, we’ll use the userId
.
{
"type": "track",
"event": "User Deleted",
"userId": "97980cfea0067",
"timestamp": "1679407797",
"properties": {
"reason": "user requested deletion"
}
}
Create or update an object (group)
In Customer.io Journeys, we refer to groups as 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.—non-people entities like accounts, online classes, or recreational leagues.
The group
call does two things:
- It creates or updates an object, like an
identify
call does for people. - If you include a
userId
, it also relates a person to the object—including any relationship 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. you pass in the call.
Note the objectTypeId
field: objects in Customer.io Journeys have a type—an incrementing number beginning at 1. This lets you have different kinds of objects; if you run an edtech company, for example, you might have objects for online classes, departments of faculty members, clubs or study groups, and so on. If you don’t pass traits.object_type_id
(or objectTypeId
), we assume that the value is 1
.
Like people, objects and their relationships with people can also have traits
—things you know about the object, like its name, industry, and so on. A relationship might have things you know about the relationship between the group and a person, like a person’s position in a company, whether they’re a primary contact for a company, and so on.
Items in the traits
object apply to the object itself—except for the relationshipAttributes
key. Anything you put in the traits.relationshipAttributes
object applies to the relationship between a person and the object.
{
"messageId": "4vl6zh",
"timestamp": "2022-11-24T22:56:14.144Z",
"type": "group",
"traits": {
"class_code": "cio101",
"class_name": "Customer.io Basics",
"start_date": 1679410730,
"object_type_id": 1,
"relationshipAttributes": {
"type": "student",
"dues_paid": true,
"class_completed": false
}
},
"groupId": "cio101-spring2024",
"userId": "97980cfea0067"
}
Object and relationship attributes
Both objects and people have their own 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.. But relationships can have attributes too! In the way that attributes on a person describe the person and attributes on an object describe the object, attributes on a relationship describe the relationship between the person and the object.
In the example above, our object is an online class and we set relationship traits (attributes) for a student. We could just as easily define relationship traits for a teacher, a teaching assistant, and so on—anyone who might be related to the class. These attributes help you send campaigns that are relevant to the relationship between a person and an object.
Delete relationship
In Journeys, people are related to groups (called 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.) You can relate people to one or more groups. In some cases, you may want to remove a relationship—like when someone finishes an online class or leaves an organization. You can do this with a track
call called Relationship Deleted
.
Your call must include:
properties.objectId
: the ID of the object a person is related to.properties.objectTypeId
: the type of object the person is related to (defaults to1
).- either
userId
orproperties.email
: the ID or email of the person you’re removing the relationship from. If you include both values, we’ll use theuserId
.
{
"messageId": "4vl6zh",
"timestamp": "2022-11-24T22:56:14.144Z",
"type": "track",
"event": "Relationship Deleted",
"properties": {
"objectId": "example-company",
"objectTypeId": 2
},
"userId": "97980cfea0067"
}
Delete object
In Journeys, you can delete a group (called an objectNot 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.) with a track
call called Object Deleted
. Deleting an object also removes all relationships between people and the object.
{
"messageId": "4vl6zh",
"timestamp": "2022-11-24T22:56:14.144Z",
"type": "track",
"event": "Object Deleted",
"properties": {
"objectId": "example-company",
"objectTypeId": 2
},
"userId": "97980cfea0067"
}
Create or update a device
When a person uses your mobile app or mobile website, you can capture and send device information to Customer.io. We capture this information with two specific events: Application Installed
and Application Opened
. These represent the times when you’ll typically register for a token and associate a device with a person.
{
"messageId": "i6yatl",
"timestamp": "2022-11-24T22:48:17.593Z",
"type": "track",
"email": "cool.person@example.com",
"properties": {
"device_id": "cEFolG5uRDGPizsaUh4X4m:APA91bFsKwjW9zUaiuJMCGqa3fLRiJ8fv1riQ6U-1iI72aSFZx5wxiqGnqbL-S2g3kZ5RrRUUo3AAVh_LhpFbjDlSqEoC4rqHmH8Z1BGgqaD9jStahy63cGXueW-vOr6mTOekmXgWSww"
},
"userId": "97980cfea0067",
"event": "Application Installed"
}
Delete device
We automatically remove a device when we register an event called Application Uninstalled
. Our SDK automatically sends this event when people uninstall your app.
However, device tokens are transient tokens can expire based on your push provider, and you’ll likely register for a new device token whenever someone closes and re-opens your app. We automatically prune devices from our messaging platform when tokens are invalidated, but we don’t do this as a part of event subscriptions. You may want to send additional calls to delete previous devices as we prune them from your Journeys tab.
{
"messageId": "i6yatl",
"timestamp": "2022-11-24T22:48:17.593Z",
"type": "track",
"email": "cool.person@example.com",
"properties": {
"device_id": "long-device-token"
},
"userId": "97980cfea0067",
"event": "Application Uninstalled"
}
Track event
The track
call represents an activity someone performs—typically in your app or on your website. If you send this event and the person you reference in the event doesn’t exist, we’ll create them.
You’ll notice that the track event excludes several event names. The Customer.io Journeys API contains methods and endpoints that don’t map naturally to other source calls—like deleting people, suppressing people, and so on. We’ve mapped these calls to track
events with specific names. You can always change the name of the event in the Actions tab of your destination settings. Events that don’t match the specially-defined names act as standard track events in Customer.io.
{
"messageId": "i6yatl",
"timestamp": "2022-11-24T22:48:17.593Z",
"type": "track",
"email": "cool.person@example.com",
"properties": {
"class_name": "Customer.io Basics",
"class_code": "cio101",
"start_date": 1679410730
},
"userId": "97980cfea0067",
"event": "enrolled"
}
Page views and screens
There are two special kinds of track events: page
and screen
calls. These represent the page(s) people visit on your website and the screens people visit in your mobile app respectively. You can use these events to monitor the places people do and don’t visit in your website or app. You might also use page and screen calls to follow up with people, to see if they were still interested in a particular product, online class, and so on.
{
"messageId": "efxqsi",
"timestamp": "2022-11-24T22:55:59.498Z",
"type": "page",
"email": "cool.person@example.com",
"properties": {
"session_started": 1679410730,
"url": "http://www.example.com"
},
"userId": "97980cfea0067",
"name": "home"
}
{
"messageId": "9zk6c",
"timestamp": "2023-03-20T22:56:06.259Z",
"type": "screen",
"email": "cool.person@example.com",
"properties": {
"session_started": 1679410730
},
"userId": "97980cfea0067",
"name": "home"
}
Merge people
Customer.io lets you merge profiles. If you use the Journeys Web SDK, we’ll automatically merge anonymous profiles with their identified counterparts when you identify them. But for any other case—if you’re not using our Journeys Web SDK or you want to merge two non-anonymous profiles—you’ll want to set up a Merge People action.
This action uses on the alias
call from your sources. You’ll set the userId
and previousId
values in the alias
call, where:
userId
is the ID of the profile that you want to remain in customer.iopreviousId
is the ID of the profile that you want to merge into theuserId
profile and remove.
The userId
inherits 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. from the previousId
that are not already set on the userId
; if the userId
and the previousId
both have an attribute, the userId
takes precedence.
The userId
also inherits events performed by the anonymousId
. Note that events merged from the previousId
person cannot trigger campaigns.
{
"previousId": "97980cfea0067",
"id": "cool_person"
}
Suppress and unsuppress people
In Journeys, suppressing a person deletes their profile and prevents you from reusing their ID or email—whichever identifier you pass in the event.
You can suppress or unsuppress users by sending events called User Suppressed
and User Unsuppressed
respectively.
In most cases, you’ll want to delete people without suppressing them. Suppressing people is typically a last resort—along the lines of GDPR “right to be forgotten” requests.
{
"messageId": "4vl6zh",
"timestamp": "2022-11-24T22:56:14.144Z",
"type": "track",
"event": "User Suppressed",
"userId": "97980cfea0067"
}
Conversion timestamps
If you want to convert ISO-8601 strings to timestamps, set Convert Timestamps when setting up actions. This converts attributes containing ISO-8601 strings (like 2023-05-18T22:58:45+00:00
) to Unix timestamps (like 1684475925
). We’ll only convert valid ISO-8601 date-times. If you store your timestamps in another format, we won’t convert them.