GuidesHelp Centre
Contact

Managing Comms Preferences

Suggest Edits

The goal of this guide is to replicate the functionality provided by Omneo Profile portal.
The Shapes SDK provides the tools needed to easily access comms preferences.

Before you begin

  1. Review the guide on Shapes SDK
  2. Configure a development version of your current site. This could be a cloned version of your Shopify theme, development store or custom application.
  3. Make sure you have access to your Omneo CX Manager.
    The existing Profile Portal configuration can be obtained here.
  4. Review the full definition of each comms preference in the Omneo Helpcenter Article

What is covered in this guide

  1. What are comms preferences?
  2. Displaying a profiles comms preferences via the Shapes SDK
  3. Reviewing your Profile Portal configuration
  4. Updating a profiles comms preferences
  5. Shapes SDK or Omneo API?
  6. Where to go from here

What are comms preferences?

These are a profiles communication settings. Comms preferences contain a variety of fields (mostly booleans) that allow profiles to opt in and out of communications by the brand.
For a complete list of settings available against a profile, check out the API docks Profile Attributes (Comms).

🚧

Before continuing with the below

Ensure you have a working Shapes SDK configuration on your front end
Review the Shapes SDK guide, and learn how to configure your front end with Omneo Shapes.

Displaying a profiles comms preferences via the Shapes SDK

Profile Comms are a part of the profile object obtained via shapes.
To obtain a customers comms preferences, you will need to hydrate your profile object as below. 

//Hydrate Shapes Data, and execute function on ready.

let handler = function(data){
      console.log(data.data, 'Ready!')
    };

shapesClient.hydrate('profile');
shapesClient.on('profile.ready', handler);

The profile hydrate function will return a profile record. This data is available in the callback function as data
alternatively, this can be accessed by using shapesClient.find('profile').data

After requesting the data, you should have a profile object in the same structure as below.
The data needed for comms preferences is located in data.attributes.comms

{
   "address":null,
   "addresses":[
      
   ],
   "attributes":{
      "comms":{...}, // Here are your comms preferences!
      "appearance":{...},
      "dates":[
         
      ]
   },
   "avatar_url":null,
   "birth_date":"1999-01-01",
   "birth_day":1,
   "birth_days":255,
   "birth_days_past":109,
   "birth_month":1,
   "birth_year":1999,
   "company":"Arkade",
   "created_at":"2020-09-24 05:47:43",
   "currency":null,
   "custom_attributes":[
      
   ],
   "email":"[email protected]",
   "external_id":null,
   "first_name":"test",
   "full_name":"test user",
   "gender":"male",
   "id":"919a7950-a01b-48a9-9291-2f36c328c935",
   "identities":[
      
   ],
   "joined_at":"2020-09-24 05:46:51",
   "joined_location":null,
   "joined_location_id":null,
   "last_name":"user",
   "mobile_phone":"+61422785871",
   "mobile_phone_country":61,
   "mobile_phone_e164":"+61422785871",
   "mobile_phone_national":"422785871",
   "mobile_phone_national_prefix":"0422785871",
   "next_birthday":"2022-01-01",
   "occupation":null,
   "preferred_location":null,
   "preferred_location_id":null,
   "profile_type":null,
   "secondary_phone":null,
   "statuses":[
      
   ],
   "tags":['tag'],
   "tier":null,
   "tier_handle":null,
   "title":"Mr",
   "updated_at":"2021-04-14 06:34:21"
}

Your comms preference data should look similar to the below:

{
   "created_at":"2020-09-24 05:47:43",
   "email_account":true,
   "email_benefits":true,
   "email_bookings":true,
   "email_bounced":false,
   "email_discover":true,
   "email_feedback":true,
   "email_location":false,
   "email_optout":false,
   "email_promo":true,
   "email_reminders":true,
   "email_service":true,
   "email_verification":"not_sent",
   "phone_account":true,
   "phone_benefits":true,
   "phone_bookings":true,
   "phone_bounced":false,
   "phone_discover":true,
   "phone_feedback":true,
   "phone_location":true,
   "phone_optout":false,
   "phone_promo":false,
   "phone_reminders":true,
   "phone_service":true,
   "phone_verification":"not_sent",
   "post_account":true,
   "post_benefits":true,
   "post_bookings":true,
   "post_bounced":false,
   "post_discover":true,
   "post_feedback":true,
   "post_location":true,
   "post_optout":false,
   "post_promo":false,
   "post_reminders":true,
   "post_service":true,
   "post_verification":"not_sent",
   "profile_id":"919a7950-a01b-48a9-9291-2f36c328c935",
   "push_account":true,
   "push_benefits":true,
   "push_bookings":true,
   "push_bounced":false,
   "push_discover":true,
   "push_feedback":true,
   "push_location":true,
   "push_optout":false,
   "push_promo":true,
   "push_reminders":true,
   "push_service":true,
   "sms_account":false,
   "sms_benefits":false,
   "sms_bookings":true,
   "sms_bounced":false,
   "sms_discover":false,
   "sms_feedback":false,
   "sms_location":false,
   "sms_optout":false,
   "sms_promo":false,
   "sms_reminders":true,
   "sms_service":true,
   "sms_verification":"not_sent",
   "terms_accepted_at":null,
   "terms_accepted_version":null,
   "updated_at":"2021-04-14 06:35:05"
}

Reviewing your Profile Portal configuration.

As you may have noticed with the above, there are many comms fields to choose from.
Most integrations will not need each and every one of these fields displayed on the front end. This could cause some confusion with end users.

To display the same fields as your brands Profile Portal, we first need to review the configuration to determine what fields it is using.
At the same time, we can note down any unique text used to describe each field.

Open your Profile Portal config in your Omneo CX Manager.

If you're not sure about your tenant just look in the URL when loading your Omneo CX Manager (or ask someone who uses the manager often)

  1. Navigate to https://{your_tenant}.manager.getomneo.com/settings/plugins/profileportal
  2. Expand the "Component Settings" field, to reveal the entire JSON config.
  3. Copy this config to a local JSON file (optional)
  4. Locate the messaging field. This contains all comms preference data. This may look like the below:
"messaging":{
    "fields":{
      "email":[
        "email_promo",
        "email_benefits",
        "email_optout"
      ],
      "sms":[
        "sms_promo",
        "sms_benefits"
      ]
    }
  },

Each of the fields specified in the fields object relates to a specific group of comms preferences. Each field under that specifies the Comms data attribute.
In the above example, we can see Profile portal uses
For email preferences:
email_promo
email_benefits
email_optout
For SMS preferences:
sms_promo
sms_benefits

Using the above fields, we can separate these from the full list mentioned previously, to get a final list of comms preferences to display on the front end.
Front end developers can pick and choose the data out of the Comms payload, and display it on the front end.

🚧

Get any description text used in Profile Portal

You may wish to log into my.{tenant}.com and review the descriptions setup against each profile comms preference. You can then replicate this in the new integration, to create an identical experience.

Updating a profiles comms preferences

By now, you should have decided on the Comms preferences to be used in your integration.
After displaying these to the end user, you will now need to modify these attributes, allowing the user to maintain them.
The Shapes SDK provides a wrapper around the Omneo API, allowing developers to easily use its functions. To update comms preferences, you will need to use shapesClient.put(), and provide a payload. Using your already authenticated ShapesClient, a PUT request will modify the customer profile, updating the comms preferences.
This can be done by:

  1. Obtain the Omneo ID.
    This can be obtained from the data returned from hydrate() , (data.id)
  2. Use this ID, when calling shapesClient.put()
  3. Specify a payload of changes needing to be made to the profile or comms.
  4. Use shapesClient.put() to modify the profile
var payload = {
  attributes:{
    comms:{
      email_optout : false,
      email_benefits : true
    }
  }
}
shapesClient.put('profile', payload, true);

📘

Update the entire profile.

shapesClient.put() is a wrapper for the Omneo API.
The full profile object can be modified in the above request (not just the comms)
If required, any attribute such as first_name or last_name could also be modified along side the attributes

Common Issues

1. I don't have any Profile Portal settings configured in Omneo, or the ones I have do not include 'messaging'
This may be because your Profile Portal has not been configured yet.
Because of this, we cannot use Profile Portal to source our comms preferences from. Instead, you can decide the comms preferences you wish to use yourself.
Start by reviewing the Profile Attributes (Comms) API docs, to see what each of the fields means.
To start, you can use email_promo, email_benefits, email_optout, sms_promo, sms_benefits.
These preferences are the basis of any integration and offer the basic opt in/out for SMS and Email.
2. I have custom_attributes configured in my Profile Portal settings.
In this case, your Profile Portal is configured to add some custom_attributes against the profile.
This is common when bespoke fields need to be tracked against a profile. If these fields need to be replicated in your integration, you will need to use shapesClient.put() to call the Omneo API and modify the custom attributes as needed.

Updated almost 3 years ago