Changes to Beacon Identify Custom Attributes

As we focus on bringing better customer management tools to Help Scout, we are shifting to using Customer Properties and deprecating Beacon identify custom attributes as of April 1, 2021. This guide will help your development team through the move to Customer Properties.

Note: If your Beacon implementation only uses the default embed code without any customization, you are all set!

In this article

Beacon Identify and Custom Attributes

Our Beacon JavaScript API includes the identify method used to pass visitor data from your site to the embedded Beacon. Historically, that method has allowed data to be passed from your site or app to Help Scout to be used for these five purposes:

  1. To create a new customer profile for each visitor that opens your Beacon — If a customer profile already exists, it will update the existing profile for that visitor. If you include data for any of the native customer profile fields (name, email, company, jobTitle, and avatar), we’ll also set or update those on the profile
  2. To let Beacon know that we know the name and email address of the visitor and pre-populate and hide those fields on the Send a message screen — We also use their name and email address to skip asking these questions at the start of a Beacon chat.
  3. To authenticate a user in Secure Mode and retrieve their previous conversations — Secure Mode ensures that your app has authenticated that the visitor is who they say they are.
  4. To collect custom data attributes and display them in the Beacon sidebar app for the conversation created by an identified visitor — You can add up to 100 of these custom attribute-value pairs to the identify method.
  5. To use those custom data attributes to trigger the display of Messages

The first three functions of the identify method as shown above will continue to operate as they do currently. If you're using Beacon identify only to pass along native customer profile data and/or authentication data, no changes are required.

Transition Timeline and What's Changing

Identify custom attributes will no longer be supported after April 1. The changes required to switch from identify attributes to Customer Properties should be minimal, but we want to give you time to make your changes to avoid disruptions.

After April 1:

  • The Beacon sidebar app will no longer be available. Once you’ve migrated your identify custom attributes to Customer Properties as outlined here, you’ll see the data in the Customer Properties sidebar app.
  • Customer data passed into Beacon identify custom attributes must match a Customer Property ID. Data that does not match to a Customer Property will be ignored.

Current Standard, Plus, and Company plans include support for Customer Properties. If you're on a Basic plan or a legacy plan that doesn’t have access to Customer Properties, you’d need to upgrade to a current plan in order to gain access to that feature.

If you have questions about your plan and your options regarding the transition, please reach out to our support team!

Why Customer Properties?

A major focus of our product roadmap is enabling you to do more with your customer data in Help Scout. The foundation of our customer data future is Customer Properties, which we introduced last year.

Identify custom attributes were originally introduced with that same spirit in mind, but over time, we’ve run into limitations associated with their implementation. The Customer Properties feature was designed to improve on identify custom attributes in the following ways:

  • Customer Properties are connected to the customer record, where identify custom attributes were connected to a conversation. This often could be confusing, as much of the data was specifically tied to a customer, not to a single conversation with that customer. If you were using the identify method to pass conversation level data, you'll want to switch to using Custom Fields instead, which can be passed via Beacon using the prefill method.
  • Customer Properties can be set and updated via a variety of sources — via Beacon identify, in the Customer Profile, and using our Mailbox API — whereas identify custom attributes could only be set and updated via Beacon identify.
  • Customer Properties feature multiple complex data types allowing for more advanced validation and forms of interaction within Help Scout, where identify custom attribute values can only be strings and numbers.
  • Customer Properties will make it possible to add functionality across Help Scout to help you do more with your customer data. Customer Properties are already available in the Mailbox API for you to build with, and our future plans include further use in integrations and Workflows so that you are able to take actions on those properties.

How to Move to Customer Properties

Locate your current Beacon identify code in your repository, app, or website.

This will help with completing the subsequent steps as you will need to create the Customer Properties to match or make changes to your custom code. Take note of the identify custom attributes that you are passing through. The attributes name, email, avatar, company, jobTitle, and signature will continue to function the same. These changes only apply to the custom attributes you have defined.

Create Customer Properties for your identify custom attributes.

See Customer Properties: Create and Edit Customer Properties for the instructions. You'll need to create a Customer Property to match each identify custom attribute you want to use.

The Property ID only accepts alphanumeric characters, hyphens, and underscores — no spaces or other special characters — and is case sensitive. If your Beacon identify custom attribute already fits this naming convention, use that as your Property ID and you are all set!

If your Beacon identify custom attribute included other special characters or spaces, you will need to adjust those to fit the Property ID rules.

Modify your Beacon embed code to populate the Customer Properties.

Make sure that the Beacon identify custom attributes are using your new Customer Properties Property IDs.

Messages: If you have any Beacon Messages configured to use identify custom attributes in conditional triggers, make sure you edit the trigger to account for the new attribute name as well.

Example Scenarios

Below are two possible examples of the steps you might need to take to make the move.

Your identify custom attribute can be used as a Property ID

The identify custom attribute you have been using already conforms to the rules for the Customer Properties Property ID — it uses only alphanumeric characters, hyphens, or underscores.

You only need to create a new Customer Property and set the Property ID to match your identify custom attribute as billing-frequency.

The custom attribute you have been using can not be used as a Property ID and you are using it in a conditional trigger in a Beacon Message

The identify custom attribute you have been using does not conform to the rules for the Customer Properties Property ID — it uses spaces or other special characters.

Create a new Customer Property and set the Property ID to use only the accepted characters.

Then modify your Beacon code to send the custom attribute using that Property ID you just created.

Now head to the settings for the Message in your Beacon using Billing Frequency as the identify trigger, and change that to billing-frequency.

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.