11

Segment destination (classic)

This page describes Segment’s classic integration with Customer.io as a destination. This integration is in maintenance mode. In general, we suggest that you use the newer Destination Actions integration to pipe data from any one of Segment’s hundreds of Source integrations into your Customer.io workspace. You can find more details in Segment’s documentation.

Set up a Segment Destination integration

1. Go to Settings > Integrations and click the Segment Destination integration.
2. Click Configure Segment.
3. Pick the Workspace and Source you want to associate your integration with, and then click Allow.

You can also set up this integration from the Segment interface using the API credentials provided on the Customer.io Segment Destination page.

Identifying people through segment

If you’re not familiar with the Segment API, take a look at the Identify method. It’s very similar to Adding or Updating people in Customer.io

Here’s an example request:

analytics.identify('userId123', {
  email: 'john.doe@example.com'
});

When you identify a new user, the user is added to your Customer.io workspace. If the user already exists, the request updates the existing person’s attributes.

If your Customer.io workspace supports both email and id as identifiers (the default setting as of June 2021), you can identify people either by id or their email trait. This provides a path to identify people who enter your system as leads (by email) and then assign them an ID in Customer.io when they become a customer or user.

• If you don’t have an ID, send your identify call an empty userId in the identify call and an email trait. Customer.io automatically maps the email trait to a person’s email attribute.
• If you have an ID, set the userId in the identify call to the person’s ID and pass email as a trait. This sets both a person’s id and email attributes in Customer.io. If you previously identified a person by email, your request updates that person and assigns them an id.

Converting leads to customers

If your workspace supports both id and email identifiersThe attributes you use to add, modify, and target people. Each unique identifier value represents an individual person in your workspace., you may want to identify a lead first by email, and then assign them an id when they become a customer or user.

To create a lead and then assign them an id when they become a customer or user:

1. Identify a lead by sending an identify request with an email trait and empty userId passing their email as the userId. This creates your lead in Customer.io—a person who has an email, but does not yet have an id.

       analytics.identify('', {
         // The email address does not belong to anybody
         // so we create a new person
         email: 'person@example.com'
         first_name: 'person',
         interested_in: 'baseball'
       });

2. Later, when that person becomes a customer, pass their new id as the userId in your Identify call, and pass their email as a trait. We’ll update the lead (who you first identified by email) with the new ID—as long as this person does not already have an id value and the id you use does not already exist.

   analytics.identify('userId123', {
     // the email belongs to the lead you identified in the previous step
     // so we'll assign an id to this person—userId123.
     email: 'person@example.com',
     account_created: 1629224941
   });

In this second request, if the ID already belongs to a person, we’ll attempt to update that person. If the ID and email already exist, you’ll receive an error.

Update email and ID values that have already been set

After you set a person’s email or id identifiersThe attributes you use to add, modify, and target people. Each unique identifier value represents an individual person in your workspace. in Customer.io, changing them can be tricky.

Email: if you allow updates to email using id, you can change the email address to any value that isn’t already in use with id. Otherwise you need to pass the cio_id in the format cio_<cio_id value> to change the email address.

ID: you must pass the cio_idAn identifier for a person that is automatically generated by Customer.io and cannot be changed. This identifier provides a complete, unbroken record of a person across changes to their other identifiers (id, email, etc). in the format cio_<cio_id value> to change id values.

analytics.identify('cio_<cio_id value>', {
  email: 'new.email@example.com',
  id: 'new-id-value'
});

You can find a person’s cio_id value by going to their People page or by looking up a person with the customers API.

Unsubscribing Users

To unsubscribe a user, simply pass unsubscribed: true in your Segment identify call. Be sure the id and/or email values match the values in Customer.io. You can find these values by selecting a person on the People page, and clicking Attributes. Here is an example that unsubscribes a user:

analytics.identify('userId123', {
    email: 'john.doe@example.com',
    unsubscribed: true
  }
)

Identifying people in workspaces that only support ID

In older workspaces, or workspaces using “classic” settings, you can only identify people by ID.

You do not need to pass an email address unless you intend to send emails. If you intend to send emails, you must provide the email address as a trait labeled email.

Segment Suppression and Deletion

To help comply with GDPR and CCPA regulations, Segment supports a set of Suppression and Deletion tools. These tools are separate from Customer.io’s own suppression and deletion tools.

In Segment, suppressed users are blocked across all sources; any message sent to Segment via a suppressed userId is blocked at their API (with the exception of device-mode destinations). Suppressions are not synchronized between Segment and Customer.io, however when you suppress and delete a customer via Segment’s UI, that deletion is passed along to Customer.io to ensure that the suppressed and deleted person is removed.

Segment Alias Call

Customer.io does not support alias calls or anonymous events from Segment. Segment uses ananonymousId trait to identify users, and it’s not possible to connect anonymous user data with a newly created person in Customer.io. As a result, you could end up with duplicate profiles. You might have come across this issue if You’re integrated via Segment and want to change ids.

Rather than using anonymous events, we suggest that you identify people by email, and then assign them an id as they become customers. See identifying users through segment above.

If you send an identify call with some attributes attached, we look at the identifiersThe attributes you use to add, modify, and target people. Each unique identifier value represents an individual person in your workspace. in the call. If we don’t recognize any of the identifiers in the call, we create a new user with those attributes. If any of the identifiers in the call already exist, we update only the attributes that are different compared to the previous call. We do not update or change the id. So if the id is new to Customer.io, we create a new (duplicate) user.

Resolve existing duplicates

If you have duplicate people in your system, you can resolve profiles through the following process:

1. Export a CSV of your customers from the People page by clicking on the Export to CSV button.
2. Identify the duplicates. We recommend keeping the first instance of each—the one with an oldest created_at timestamp.
3. Create a new CSV file with all of the people (by id or email) you want to delete.
4. Delete those users with our API.

Prevent new users from causing duplicates

For new users, we strongly suggest you identify people by email if they do not yet have an ID.

1. Pass email as the userId in Segment’s identify call.
2. Update a person’s ID using an identify call after they sign up for your service.

Anonymous Events from Segment

If you want to send anonymous events from Segment, you should consider upgrading to Segment’s new Destination Actions feature. We have instructions to set up Destination Actions with Customer.io here.

If you can’t upgrade to Segment’s Destination Actions feature, and you need to message a customer before they’ve signed up, you should record an event by email and then send an invite campaign to people in Customer.io who have an email address but do not have an ID.

Some useful links

• The full list of Segment methods are supported with Customer.io.
• Segment have outlined integrations that support the Alias method.

As always, if you need any help with this process or have any questions, please let us know!