Segment

Send user and event data from Segment to Regal

This guide describes how to use Segment to send data to Regal. It discusses how to set up Segment, create and identify users, and track events. You can also refer to Regal's Segment developer documentation here: https://segment.com/docs/connections/destinations/catalog/regal-voice/

Sending Data from Segment to Regal

Get started by enabling the Regal Destination in your Segment.

Enable the Regal Destination

  1. Email [email protected] to get your Regal API Key.
  2. In Segment, navigate to the Sources tab. Open the source from which you'd like to send data to Regal.
  3. Click Add Destination.
  4. From the list of possible destinations, choose Regal.
  5. Click Configure Regal.
  6. Enable the toggle at the top of the Regal integration.
  7. Segment will now send data from the selected source to Regal.

What data to send to Regal

Segment allows you to pass all events to Regal; however, you can also filter out events and only send those that are Relevant to Regal. Events that are relevant include:

  • Identify events - when new users are created or user traits are updated; when optIn for sms and calls is collected. Regal treats optIn as a user trait
  • Track events - related to key moments of the user lifecycle that you wish to reference in your Regal journeys; this can include email send, click, open events
  • Page or screen events - only send these if you wish to reference them in your Regal journeys

Identifying users

Identify events are used to create users and update user properties. The identify call specifies a customer identity that you can reference across the customer’s whole lifetime. Every identify call must have a User ID or an Anonymous ID, depending on how much you know about the user in question.

Anonymous ID

There are certain cases where you don’t actually know who the user is according to your database, but you still want to be able to tie them to traits, events, or page views. For example, you may not know who a user is when tracking newsletter signups or anonymous page views.

In these cases, you should use an Anonymous ID. The Anonymous ID can be any pseudo-unique identifier. For example, on your servers you can use a session id. If you don’t have any readily available identifier, you can always generate a new random one—we recommend UUIDs.

Note: Segment’s browser and mobile libraries automatically use Anonymous IDs to keep track of users as they navigate around your website or app, so you don’t need to worry about them when using those libraries.

User ID

Once a user has created an account in your application, we recommend sending along the userId with the payload instead of an Anonymous ID. A User ID is usually the unique identifier that you recognize a user by in your own database or CRM.

User IDs should be consistent across a customer’s lifetime and identify calls should include a User ID as often as possible.

The userId will appear as External ID in the Regal app, and should not be shared across users.

We recommend using database IDs instead of simple email addresses or usernames, because database IDs never change and don't include PII. Instead email address or a username can be sent along along as traits.

Traits

If an identify event contains a phone number, Regal will create a contact in your Regal Audience.

Traits in your identify events get added to the contact's profile in Regal. There are a standard set of supported traits including:

  • firstName
  • lastName
  • phone
  • email
  • age
  • gender
  • address
  • optIn

Any other traits you add become custom properties on a contact's profile in Regal.

Here's an example call to Segment's identify method, using their Analytics.js (JavaScript) Source. In this example, custom properties include: salaryBracket, employmentStatus, and savingsGoal

analytics.identify("92980cfccc067", {
  phone: "+19545552399",
  email: "[email protected]",
  firstName: "Rebecca",
  lastName: "Greene",
  age: 23,
  gender: "other",
  address: {
    AddressLine1: "201 Maiden Lane.",
    AddressLine2: "11M",
    City: "New York",
    ZipOrPostcode: "10128",
    StateProvinceCounty: "NY",
    CountryId: "US"
  },
  salaryBracket: "$100k-$500k",
  employmentStatus: "Employed",
  savingsGoal: "New Home"
});

Tracking events

The track call is how you record any actions your users perform, along with any properties that describe the action. We recommend calling track on any event you'd like Regal to use for scoring a lead or as a trigger or condition when sending and sms campaigns.

An example for a financial services company might be that you want to tigger an outbound call to a user for whom a ‘Loan Application Approved’ event has been received, but not a ‘Loan Signed’ event (with some parameter around timing).

In that case, an example track call for the ‘Loan Application Approved’ event using Segment's Analytics.js (JavaScript) Source would look like the following:

analytics.track("Loan Application Approved", {
  loanType: "Personal loan", 
  amount: 30000,
  currency: "USD",
  term: 12
})

🚧

Important

Calling track for a user that doesn't already exist in your Regal project creates a Regal user profile for them and associates it with the custom event data. However, until you call identify for that user with a phone number, their Regal profile is not available in your audience for journeys and messaging. After you've called identify for them, their user profile—along with all previously tracked events—is accessible.

Passing opt in to Regal

In order to trigger outbound calls or sms messages from Regal, you must collect the user’s explicit opt-in for those channels along with the user’s phone number.

There are 2 options for how you can let Regal know a user has opted in:

  1. Anytime you collect opt-in for sms or voice calls, you can trigger a track event after a user opts in and let the Regal team know what track event is synonymous with opt-in collected (there is no required format for this event). The product will then automatically subscribe users who perform that event. (Note: for Regal to subscribe a user, there must already be a phone provided for that user.)

  2. Alternatively, anytime you collect opt-in for sms or voice calls, you can use an identify call to pass that opt-in information to Regal by adding an optIn object like the example above. The example above

Below is an example of what an identify call would look like for a user who opted into multiple channels (sms and voice calls) at once:

analytics.identify("92980cfccc067", {
  phone: +19545552399,
  optIn: [
    {
      channel: "sms",
      subscribed: true,
      timestamp: "2020-08-25T21:23:43Z",
      ip: "172.16.254.1",
      source: "booking_flow",
      text: "By clicking the 'Submit' button below, I agree to receive automated marketing SMS and calls."
    }, 
    {
      channel: "voice",
      subscribed: true,
      timestamp: "2020-08-25T21:23:43Z",
      ip: "172.16.254.1",
      source: "booking_flow",
      text: "By clicking the 'Submit' button below, I agree to receive automated marketing SMS and calls."
  }]
});

Supported messaging channels are sms and voice.

For the identify method, the ip field is required if you are opting in users server side. (If you are opting in users client side, Segment automatically adds ip to the context, so you are not required to add it to the optIn object)

Make sure to include timestamp with the exact time the user opted in. Since traits are cached and sent with subsequent Identify calls, Regal ignores opt-ins that do not have a timestamp date.

Tracking page views

The page and screen call lets you record whenever a user sees a page of your website, along with any optional properties about the page.

Here's an example call to Segment's page method, using their Analytics.js (JavaScript) Source:

analytics.page("Page Category", "Page Name");

Segment notes the following things about the page call:

In analytics.js a page call is included in the snippet by default just after analytics.load. We do that because you must call this method at least once per page load. However, you can choose to add an optional name or properties to the default call, or call it multiple times if you have a single-page application.

Testing your integration

To check the success of your integration:

  • Go to the Recent Activity page in the Regal app to view incoming track and page events
  • Go to the Audience page in the Regal app to view your contacts (created from identify events) - remember in order for a user to appear in your audience they must have a phone. You can also view their optIn status from the Audience page

What’s Next

Once you've finished setting up the Regal Segment Destination, you can set up the Regal Segment Source to receive Regal events back in real-time.

Did this page help you?