Getting Started: Integration Planning

Getting Started: Integration Planning


This document is part of a complete series on Getting Started with Customer.io.

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 send to Customer.io for us to be able to help you send those messages.

To help you plan your integration, this guide will discuss what data you can send to Customer.io and the data you can get 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.

Jump Around

  1. Data you can send to Customer.io
  2. Data you can get from Customer.io
  3. Data In or Out - Points to Consider

Data you can send to Customer.io

Our system is designed to receive information about your customers and the activity they perform in your system. This lets us send highly targeted messages based on that activity. A deliberate approach to mapping your product's user and behavioral data to Customer.io is critical for your success.

You may want to send us:

What to send Description When
Profile Attributes Properties stored per Person in your account. Send when you store data that is unique to an individual so you can use it for messaging or segmenting.
Events Actions performed by the People in your account. Send when you want to trigger an Event-triggered Campaign or when you want to log an activity for the purpose of segmenting users by what they've done (or haven't done) in your system.
Page Views Special events that describe web pages visited by your People. Send when you want to segment People based on pages they have (or haven't) visited on your website.
Devices The physical objects used by People in your account to interact with your system. Only required when you send mobile push notifications through Customer.io.
Triggers Data sent to trigger specific API Triggered Broadcasts. Only required when using API Triggered Broadcasts to send messages through Customer.io.

Practical Examples

Profile Attributes:

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)
  • 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:

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.

Page Views:

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.

Devices:

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.

Triggers:

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."

Data you can get from Customer.io

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:

Where What
Various places within your account. Export CSV files containing data about a single Person, many People, Campaign Metrics and Delivery Logs.
Using our API Pull various data pertaining to Customers (People), Campaigns, Newsletter Broadcasts, Segments, Message Templates, Messages (Deliveries), Exports, Activities, Sender Identities, Reporting Webhooks.
Using Email Webhook Set up an endpoint we can use to send information about events as they occur in real time.
Using Webhook Action items Add a template for us to use in any of your Campaign or Broadcast workflows to send data to any public API you choose.

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.

Data In or Out - Points to Consider

As you plan your integration you may need a bit more insight into how Customer.io works. Below you'll find a list of more points to consider as you work through your planning process.

Tips and Overall Best Practices

  • Not every database field in your system needs to be in Customer.io. You should limit the data you send to Customer.io to what is needed for messaging and segmentation our system. Anything more than that will clutter up your account. We strongly recommend only sending data that will be used for those purposes. That will help ensure great performance and a snappy experience when using Customer.io.
  • You should not send us any 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.
  • Customer.io does not enforce uniqueness of the email Attribute. 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. (id is the only Attribute we require to be unique per Person.)
  • The API limits associated with sending data to Customer.io will apply even when your data is being sent through third-party services like Segment.com, Hull.io and Zapier.

Working with Profile Attributes

Profile Attributes map to bits of data you know about the individual users in your system.

Required Attributes

  • id (lower case)
    The id Attribute is the only Attribute that is required per Person and it cannot be changed once it has been set. The id Attribute must be unique for every profile because it is what we use to differentiate each Person in your Workspace. We do not use their other contact information (i.e., their email address or phone number) for that purpose. This means multiple profiles can have the same email address, phone number.

Optional Attributes

  • Empty, id-only profiles aren't very valuable to your organization so you'll also want to store some contact information per Person. Common contact Attributes include, email, phone (when sending Twilio SMS) and/or named_user (when sending via Urban Airship Action).
  • Profile Attributes are also a great place to store data you want to use to personalize the content you send People via Customer.io. Consider adding personal information like first_name, last_name, plan_name or last_login_date as well.

Reserved Attributes (also optional, but recommended)

You can name your optional Attributes anything you wish but there are a handful of reserved Attribute names that we recommend you make use of. Each of the following Attributes, when used, 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 (without milliseconds) equal to when the Person was created in your system.
  • unsubscribed
    (lower case) 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. Learn more about how we use the unsubscribed Attribute. Otherwise, if you'd like a bit more control, you can manage this behaviour yourself.
  • 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.
  • named_user
    (lower case) If you plan to use the Urban Airship Push Action, the named_user profile Attribute should contain the named user detail that’s stored in your Urban Airship account.
  • timezone
    (lower case) Sending us this Attribute will allow you to enable the Time Zone Match feature.

Tips and Best Practices for Profile Attributes

  • Use all 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. You will have to remember to treat them differently when using Liquid code in your content. For example,
    {{ customer.address.street }} will not work. You will have to use
    {{customer["address.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'

Working with Events

Events map to actions your users take within your system (and occasionally to actions your service makes on a user’s behalf, such as recommendations).

Consider a streaming music service. Examples of events that your 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.

Tips and Best Practices for Events

  • 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.
  • Use caution when backfilling historical Events because they will trigger your existing active Campaigns when the backfilled Events match the Campaign's configuration.

Working with 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 }}.

Tips and Best Practices for Event Attributes

  • 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 broadcast or Segment-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.

Working with 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.

Tips and Best Practices for Page Views

  • 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.

Working with 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.

Tips and Best Practices for Devices

  • Typically, Device IDs should be sent every time the app is launched on a client Device. Our recommendation is to make these calls using one of our client libraries from your backend system rather than directly from your app.
  • 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.

Working with 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.

Tips and Best Practices for API Triggered Broadcasts

  • 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 not change. 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.
Was this article helpful?