80

Getting Started: Integration Planning

Once you’re familiar with how Customer.io works, it’s time to start thinking about how to connect your system with ours. Before we discuss how to send your data, we recommend planning out the types of messages you will be sending to your customers. You’ll also want to think about what data you need to personalize, segment, and measure the effectiveness of your messages.

To help you plan your integration, this guide will cover the flow of data to and from Customer.io. We’ll also offer some tips and best practices to help you along the way. You’ll learn about the various ways you can connect your system with Customer.io later in this series when we discuss Integration Methods.

Workspaces and Profile IDs

It’s important to understand how data is organized in Customer.io. When you signed up, we created an Account for your business. Within each Account, you can create Workspaces.

You have options when it comes to Workspace configurations:

• Multi-Identifier Workspaces: In a Multi-Identifier Workspace, both email and ID must be unique, but only one is required when creating or updating a Person in Customer.io. This Workspace type is best for managing both pre- and post-signup messages in a single Workspace.
  • If you want to update an email address identifier using the customer’s ID, you must enable the Allow updates to email using ID setting.
• ID-Based Workspaces: Customer.io does not enforce uniqueness of the email Attribute in id-based Workspaces. We also do not automatically dedupe email addresses for you. This allows flexibility but may catch you by surprise if you do not take measures on your end to ensure you only have one profile per user. (The only Attribute we require to be unique per Person is id.)
• Email-Based Workspaces: Email addresses are used as the identifier in an Email-Based Workspace. That means that each profile must have a unique email address.

Learn more about our Workspace configuration options.

Data In and Out

Our system is designed to receive information about your customers and the activities they perform in your systems, as well as send data back to you about People, Campaigns, and Metrics. This allows you to send highly targeted messages in Customer.io based on that activity. A deliberate approach to mapping your product’s user and behavioral data to Customer.io is critical for your success. The information you want to use to segment your audience and personalize messages is the data you’ll want to send to Customer.io.

Data In

Data Out

Best Practices

• Not every database field in your system needs to be in Customer.io. Consider limiting the data you send to Customer.io to what you need for messaging and segmentation purposes. Anything more than that could make it difficult for your team to understand which data to use. Taking a conservative approach to your data plan ensures a great experience when using Customer.io.
• You should not send us sensitive, personal information. This includes bank account information, personal health details, credit card numbers, or other secure details. This type of information should not be used directly in email or other types of messages due to their sensitive nature.
• API limits apply even when your data is being sent by third-party services like Segment.com and Zapier.

Deep Dive: Data In

Profile Attributes

Profile Attributes are properties stored on a customer’s profile. While there are a few reserved attributes, you can send any data you like. Attributes are named values you use in various places throughout Customer.io. If you want to customize your messages using data that is unique to each Person, you should store that data as Attributes on their profile.

Required Attributes

id or email are the only required attributes depending on the type of Workspace that you configured. All new Workspaces are Multi-Identifier by default, and only one of those identifiers are required to create or update a profile. We also generate a special identifier called cio_id that you can use to update a person’s other identifiers. Read more about updating identifiers.

Reserved Attributes (also optional, but recommended)

You can name your optional Attributes anything you want, but there are a handful of reserved Attribute names that we recommend you use. The following Attributes have special meaning in Customer.io and may be used in a special way in your account:

• created_at (lower case) The created_at Attribute should hold a Unix timestamp/Epoch time format value (in seconds) equal to when the Person was created in your system. 
• unsubscribed (lower case) Global unsubscribes in Customer.io are managed using the unsubscribed Attribute value.  The unsubscribed Attribute should be assigned a value of “true” for anyone that is to be treated as unsubscribed from all messaging. Learn more about how we use the unsubscribed Attribute and learn how to manage granular subscription preferences with our subscription center.
• email (lower case) If you plan to use the Email Action, your profiles must have a valid email address stored in their profile. You are welcome to use a different Attribute name for email addresses. Just be aware that the default Attribute we use across Customer.io is email. You will need to override our default where possible.
• phone (lower case) If you plan to use the Twilio Action, your profiles must have a phone number stored in their profile. The default Attribute we use in the message editor is phone but your Attribute could be named something like phone_number or mobile_phone instead.
• timezone (lower case) Sending us this Attribute will allow you to enable the Time Zone Match feature.
• named_user This reserved attribute for Airship Actions is no longer available for new customers, but relates to the named_user value in Airship.

Optional Attributes

Profile Attributes are a great place to store data you want to use to personalize the messages you send from Customer.io. Consider adding personal information like first_name, last_name, plan_name or last_login_date as well.

Attributes: Tips and Best Practices

• Use lowercase letters for your Attribute names. Attribute names are case-sensitive so id, ID and Id are all different Attributes in Customer.io.

• Avoid attribute names that contain spaces. This will allow you to use Liquid code in your content like {{ customer.first_name }} instead of having to remember that Attributes with spaces must be used like {{ customer["first name"] }} instead. 

• Use only alphanumeric characters for your Attribute names. Non-alphanumeric characters can cause odd issues that are hard to spot. If you use non-alphanumeric characters in attributes, you’ll have to treat them differently from standard alphanumeric attribute names when referencing attributes using Liquid code in your content.

  For example, if your attributes are address.street or $street, you cannot reference them in standard liquid syntax as {{customer.address.street}} or {{customer.$street}}.

  You would have to use {{customer["address.street"]}} or {{customer["$street"]}} instead.

• Use properly formatted timestamps. For maximum segmentation options, it is critical that you send timestamp values to Customer.io in the correct format. (Such as when using the created_at Attribute mentioned above.) If you aren’t familiar with the Unix timestamp/Epoch time format, please review our timestamp FAQ.

• Validate email addresses and phone numbers before sending them to Customer.io. Check for common input errors like “hotmaol.com” or phone numbers that do not have enough digits.

• Ensure phone numbers are stored in E.164 format: [+][country code][subscriber number including area code]. This is good practice in general, but it is required when used in Twilio Actions. 

• Stick within the limits. There’s no limit on the number of Attributes you can store in each profile. However, to help us guarantee your account’s reliability and performance, we do have limits in place for the amount of data that can be stored per Attribute.

• Format the data based on its intended use. Attributes can be a string, boolean or a number.

  • Use booleans, not strings for state:
    • Good: account_manager: true
    • Bad: account_manager: 'true'
  • Numbers should be passed as numbers, not strings:
    • Good: num_projects: 15
    • Bad: num_projects: '15'

Attributes: Practical Examples

Here are some examples of what you can do once you have data in your Peoples’ profile Attributes:

• Segmentation - If you store a Person’s subscription plan as an Attribute (e.g., free/basic/premium), you can create Segments to match specific subscriber types. With Segments like that you can ensure certain messages only get sent to People who have subscribed to a particular plan. (E.g., subscription_plan: premium)
• Messaging - If you store a Person’s birthday as an Attribute, you can send them a message every year on their birthday. You can create Campaigns that trigger based on any date stored as an Attribute.
• Customization - If you store Attributes like first_name, you can personalize messages by displaying the Person’s name in the subject or body using Liquid.
• Accommodation - If you store a Person’s preferred contact method as “SMS”, you can use that attribute to ensure you send them SMS messages instead of email messages.

Events

Events are actions people perform in your app, on your website, etc—things like button clicks, scrolling to the bottom of a page, or purchases. When you send us events, you can start campaigns and segment your users based on the things they do (or don’t do) in your app.

Consider a streaming music service. Examples of events users perform include:

• create_playlist
• play
• upgrade
• skip_song
• star_song
• search

Track activities that users perform to derive value or enjoyment from your service. It’s less productive to track generic, non-descriptive activities like button clicks. Instead, send in user activity that maps to specific, meaningful behavioral goals.

Events: Practical Examples

Here are some examples of what you can do once you start sending Events to Customer.io:

• Timely Messaging - If you send an event that describes a purchase that a Person just made in your system, you can send them a receipt with an upsell offer right away while you are still on their mind.
• Segmentation - If you send an event every time someone achieves a goal in your app, you can create a Segment that matches People who have done that event six times in the last month. With a Segment like that you can send a targeted message to your most engaged users.
• Intervention - If you send an event every time someone submits a support request, you can send a Slack message to your team for someone to investigate when the same Person has submitted more than three requests in a week.

Events: Tips and Best Practices

• Use only alphanumeric characters for your Event names. *, +, and | characters are not supported in event names. If you attempt to use them anyway, you may experience issues that are hard to spot. For example, using "have performed the event event1|event2" in your segment criteria will be interpreted as "have performed the event 'event1' OR 'event2'". There currently is no way to escape these characters in your segment criteria order to find events with names that have those characters in them. If you must separate words, we recommend using underscores _.
• Track activities that users perform to derive value or enjoyment from your service. It’s less productive to track generic, non-descriptive activities like button clicks. Instead, send in user activity that maps to specific, meaningful behavioral goals.
• Use a simple naming convention that is readable, easy to understand, and corresponds to the activity you are tracking.
• If you send an Event using a profile id that doesn’t exist in your Customer.io account, a new Person will be created using the profile id sent with the Event. That profile will not have any Attributes (other than id) until you send them separately.
• Historical event data should include the timestamp when the event originally occurred. If the timestamp is not included, Customer.io will interpret the event as occurring at the time the event is sent.

   

  Please be aware that backfilling event data may trigger campaigns or messages, if those events are used as triggers!

  • A backdated event WILL trigger event-triggered campaigns if the event’s timestamp is within the last 3 days (72 hours).
  • A backdated event WILL NOT trigger event-triggered campaigns if the event’s timestamp is older than 3 days (72 hours).

Event Attributes

Just as profile Attributes (above) describe People, the Event Attributes you send in your Events describe each instance of the Event. Event Attributes are not required but sending them will make your Events more valuable. Event Attributes can be used to create Segments and to customize the messages you send in any Campaign that is triggered by your Event.

For example, you could send the following Event and Event Attribute data:

• Event Name (the action taken by the user):
  • enrolled
• Event Attributes (data describing each instance of the Event):
  • course_title
  • course_fee
  • course_instructor
  • course_url
  • course_img_url

With an Event like that you can create Segments like “Has enrolled in any course”, “Has enrolled in Pigeon Calling 101” or “Has never been taught by Jane Smith”. Additionally, when you trigger a Campaign using this Event, you will be able to include any of the Event Attribute values in messages you send from your Event-triggered Campaigns. This is done using Liquid code in your content like, {{ event.course_instructor }}.

Event Attributes: Tips and Best Practices

• For Event Attributes, we recommend you use the same best practices as described above for profile Attributes.
• There’s no limit on the number of Event Attributes you can send with each Event. However, we do have limits in place for the overall size of the event data.
• Event Attributes are only accessible when configuring Segment conditions and in messages sent by Event-triggered Campaigns. They cannot be accessed in Broadcasts, Segment-triggered Campaign content, or Date-triggered Campaign content.
• Event Attributes should not contain profile Attribute data. The Event will be tied to the user profile.
• Event Attributes are stored with the Event. They do not change and they do not automatically become profile Attributes as they are meant to describe the Event, not the Person. Event Attribute data can be added to a Person’s profile as part of Campaign’s workflow if desired.

Page Views

Send us data about the pages your People view so you can build useful Segments using that data. This is done using our JavaScript snippet or our API.

Page Views: Practical Examples

Here are some examples of what you can do once you start sending Page Views to Customer.io:

• Monitor - You can create a Segment to match People who keep viewing your best selling products but haven’t made a purchase yet. Then you can optionally message them about an upcoming promotion for the item they’ve been looking at.
• Classify - Have topical articles? You can create a Segment to match People who viewed an article about “Game of Thrones.” Then you can use that Segment to trigger a Campaign that will update their profile to reflect that interest.

Page Views: Tips and Best Practices

• If you don’t need Segments related to Page Views, feel free to skip this part of the integration planning.
• Avoid sending Page View Events for users who are not logged into your system and already known to Customer.io. Sending Page Views for unknown users will create unusable Page View data in your account that is not assigned to any of your profiles. There will be no way for you to access or use this information.
• You can build Segments based on full URL paths or use wildcards for partial URL matching.

Devices

If you plan to use Customer.io to send push notifications via our native push feature (as opposed to using webhooks) then you will need to send us IDs for the Devices your People use. Device data is sent to us using our API. Our SDKs provide a ready-made integration to identify people who use mobile devices and send them notifications.

Devices: Practical Examples

Here are some examples of what you can do once you start sending Devices to Customer.io:

• Alert - Send People urgent push notifications based on their current location.
• Inform - Let People know about major app updates nudge them to install the new version or check out a new feature. 
• Remind - Send People reminders to complete key actions in your app.

Devices: Tips and Best Practices

• Typically, Device IDs should be sent every time the app is launched on a client Device. Our recommendation is to integrate your mobile app by installing our native mobile SDKs.
• We only store 25 Devices per customer. If a Person already has 25 Devices when a new Device is being added, we remove the Device with the oldest last_used timestamp and add the new Device.
• By default, your push notification will go to all devices associated with a particular Person.
• When testing your push configuration and messages for quality assurance (QA) purposes, we recommend that you use separate development/test and production Workspaces—especially if you need to use separate configuration credentials.

API Triggered Broadcast Data

Using API Triggered Broadcasts is a two step process. First, you set up an API Triggered Broadcast in Customer.io. Then you configure your system to send the data that will trigger the Broadcast via our API.

API Triggered Broadcasts: Practical Examples

Here are some examples of what you can do once you set up API Triggered Broadcasts and start sending trigger data to Customer.io:

• Topical Updates - Send an announcement to People about subjects they care about. Imagine two announcements using the same message templates: “Game of Thrones reboot already underway.” and “Stranger Things actors on strike over script mishap.”
• Location-based Alerts - Notify People when an incident occurs in a location they care about. Imagine one configuration that can send both: “Mapletown’s Fall Festival dates updated to October 29-30.” and “Power out in much of Manhattan.”

API Triggered Broadcasts: Tips and Best Practices

• When you trigger an API Triggered Broadcast, each trigger can have its own (optional) set of JSON data. JSON is simply the way the data is formatted. It stands for JavaScript Object Notation. Learn more in our documentation about formatting Broadcast data.
• Be mindful of the limits we’ve put in place when sending API Triggered Broadcast data.
• Trigger data has no effect on profile Attributes. Once sent, trigger data cannot be changed. Also, it does not automatically update a Person’s profile Attributes because it is only meant to provide data for the messages being sent. Trigger data can be added to a Person’s profile as part of Broadcast’s workflow if desired.
• The data in a trigger is only accessible within that Broadcast’s individual messages.

Deep Dive: Data out

You can also pull data from Customer.io for whatever external purposes your organization requires. Here’s a general overview of the kind of data you can get from Customer.io:

Practical Examples

• Generate custom reports by exporting Delivery Logs from your account and processing them in your favorite third-party analytics tool.
• Use our API to pull the ids for everyone belonging to key Segments.
• Get Webhook notifications so you can learn about email failures quickly and investigate.

App API

Learn more about the App API in our API docs.

Reporting Webhooks

Learn more by viewing our Email Webhook documentation.

CSV export

Workflow Webhook Actions

Learn more by viewing our Webhook Actions documentation.

Data Warehouse Sync

Learn more by viewing our Data Warehouse Sync documentation.