Set preferences outside of the subscription center

Updated

A subscription center helps you differentiate between the types of messages you send and lets your audience decide what kinds of campaigns and messages they want to receive. Your customers can update their preferences from within your Customer.io messages or other locations including, but not limited to, account creation.

How it works

Customer.io’s Subscription Center feature lets your audience set their subscription preferences when they click Unsubscribe or Manage your preferences in your messages. But you might want to let your audience proactively manage their preferences as a part of your sign-up flow or elsewhere.

You can set your audience’s subscription preferences using the reserved cio_subscription_preferences attributeA 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.. This attribute contains both topics and channels preferences where every individual preference is a boolean (true/false).

Topics are numbered based on the ID that you see in the UI—topic_1 corresponds to ID 1 in the left-column in your Subscription Center setup page. We set subscription preferences by topic ID rather than the topic Name, so that you can change the name of a topic without affecting your audience’s preferences.

Channels use the channel type name as the key (email, sms, push, in_app, whatsapp, slack, line, inbox). Channel preferences let people opt in or out of specific messaging channels, independent of their topic preferences.

When you send a message, a person must be subscribed to both the relevant topic and channel to receive the message.

{
   "cio_subscription_preferences": {
      "topics": {
         "topic_1": true,
         "topic_2": false
      },
      "channels": {
         "email": true,
         "sms": true,
         "push": false
      }
   }
}
Within Workspace Settings, this subscription center has a table with 5 topics. Each topic has an ID followed by a name and the default status, not subscribed or subscribed.
Within Workspace Settings, this subscription center has a table with 5 topics. Each topic has an ID followed by a name and the default status, not subscribed or subscribed.

Your subscription center starts your relationship with your audience on the right foot by letting them tell you which types of messages they’re interested in.

Create a custom subscription preferences page

If you need more flexibility over the branding and location of your subscription preferences page, you can use our App and Track APIs to fetch and update preferences within a page that you host. Use our App API to fetch susbcription preferences for your customers and our Track API to update subscription preferences. You can also set preferences using our Web SDK.

flowchart LR a[create custom form
outside Customer.io]-->b subgraph App API direction LR b[fetch preferences
on page load] end b-->c subgraph Track API or Web SDK direction LR c[set preferences when
form is submitted] end

App API: Fetch preferences

You can fetch subscription preferences from your workspace using our App API endpoint: /v1/customers/{customer_id}/subscription_preferences. The response includes both topic and channel preferences.

const axios = require('axios');

let config = {
  method: 'get',
  maxBodyLength: Infinity,
  url: 'api.customer.io/v1/customers/sdade8@example.com/subscription_preferences?id_type=email',
  headers: { 
    'Accept': 'application/json', 
    'Authorization': 'Bearer'
  }
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

API: Set preferences

If you have your own backend integration, you can send subscription preferences—including both topic and channel preferences—to your workspace through our APIs or our libraries. We’ve provided some examples below.

Our Pipelines API preserves preferences by default. Our classic Track API does not. If you use our classic Track API, we’ve provided examples to help you preserve or overwrite existing preferences depending on your use case. Channel preferences work the same way as topic preferences in all APIs.

The Pipelines API automatically preserves any preferences you don’t set. Using our example below, if there was a topic_4 that was set to true, it would remain true after the update. You can reset all preferences by passing an empty topics object. The same behavior applies to channel preferences in the channels map.

This example uses our API directly, but we also have client-side JavaScript and server-side libraries that can make things easier.

const axios = require('axios');
let data = JSON.stringify({
  "userId": "customer@example.com",
  "traits": {
    "cio_subscription_preferences": {
      "topics": {
        "topic_1": true,
        "topic_2": true,
        "topic_3": false
      },
      "channels": {
        "email": true,
        "sms": true,
        "push": false
      }
    }
  }
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://cdp.customer.io/v1/identify',
  headers: { 
    'Content-Type': 'application/json', 
    'Authorization': 'Basic <yourApiKey>:'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

Javascript/Web SDK: Set preferences

If you use our JavaScript source (which we recommend) or our classic JavaScript SDK, you can set preferences with the identify function. You can identify a person when they first sign up for your service and set their preferences or when they update their preferences in a settings page that you make available to them.

With our JavaScript client, you can pass an empty topics or channels object to overwrite a person’s preferences. Otherwise, we’ll preserve the preferences that you don’t update.

_cio.identify({
  userId: '019mr8mf4r',
  cio_subscription_preferences: {
    topics: {
      topic_1: true,
      topic_2: true,
      topic_3: false
    },
    channels: {
      email: true,
      sms: true,
      push: false
    }
  }
});
Copied to clipboard!
  Contents