Identity Objects

The Identity Object is a special type of App Object that comes pre-defined in every app. It is important because it defines the structure of data pertaining to the Actor, the customer going through the application flow. The actor variable is structured as an Identity Object, and it is crucial that the actor variable be able to reference that structure.

📘 In the vast majority of use cases, no data will actually be stored under the Identity Object. The presence of the Identity Object is important because it structures data pertaining to the Actor, which is saved and accessed during the relatively short-term length of a Journey. It is not often used for long-term data storage the way most App Objects are – although, depending on use-case, it can be.

Identity Structure

Out of the box, the Identity App Object has eight associated properties:

• first_name (string) - the Actor's first name.

• last_name (string) - the Actor's last name.

• full_name (string) - the Actor's full name.

• email (string) - the Actor's email address. This cans serve as a unique identifier.

• phone (string) - the Actor's phone number. This can serve as a unique identifier.

• timezone (string) - the Actor's timezone. Timezones must be described by their TZ database names, or the Actor will not parse them as meaningful timezones.

• region (string) - the Actor's region. Regions must be described by their State/Province Abbreviation Key, or the Actor will not parse them as meaningful regions.

• calendar_restriction (string, Availability Schedule Key) - for the sake of TCPA compliance, this value is automatically generated out of timezone and region when applicable.

  • Availability Schedule Keys are made in the Schedules Builder. For more on how to conceptualize calendar restrictions, see Using Availability Schedules.

Application of Identity Object Properties

The Identity Object defines the structure of the Actor, which, upon initialization, defines the behavior of Notifications and Dialogue Bots (ie: Voice and Chat Bots). For a deeper discussion on Actor initialization, see Actors and Conversations with Actors.

It is possible to initialize the Actor with only some of the properties described by the Identity App Object. Each property is used to define different capabilities upon initialization.

first_name, last_name, and full_name

These properties exist to make the person represented by the Actor more intuitive. There is no change in behavior when the Actor is initialized with values for actor.first_name, actor.last_name, or actor.full_name.

email

This property defines the email address that outgoing Email Notifications will be sent to. It is only after the Actor has been initialized with a value for actor.email that Email Notifications can be sent.

For more on Email Notifications, see Notifications Builder.

phone

This property defines the phone number that will be used to establish phone and SMS communication channels. This includes Voice Bots, Chat Bots, and SMS Notifications. It is only after the Actor has been initialized with a value for actor.phone that SMS Notifications can be sent and Dialogue Bots (ie: Voice Bots and Chat Bots) can be started.

For more on initializing the Actor with a value for actor.phone, see Conversations with Actors.

timezone, region, and calendar_restriction

These properties are used to enforce TCPA-compliance when sending outgoing Notifications.

When an Actor is initialized with values for actor.timezone and actor.region, a value for actor.calendar_restriction will be defined automatically, such that:

actor.calendar_restriction = "TCPA-{{actor.region}}-{{actor.timezone}}"

This actor.calendar_restriction value references an out-of-the-box Availability Schedule that describes TCPA-compliant time windows within the Actor's region and timezone. Outgoing Notifications sent from Journey Steps will only be sent within the designated blocks of time.

🚧 Enforcing TCPA through the calendar_restriction only applies to Notifications sent from Journey Steps. Initializing the Actor with values for actor.timezone and actor.region will not enforce TCPA compliance in Dialogue Bots or Notifications sent as Actions, which are made TCPA-compliant through other means. For more, see How To enforce TCPA.

While the value of actor.calendar_restriction will be defined automatically when an Actor is initialized with values for actor.timezone and actor.region, it is also possible to manually define the value of actor.calendar_restriction so that it references another Availability Schedule and applies restrictions accordingly. For more on Availability Schedules, see Customizing Schedule Availability.