FAQ

What is TCPA compliance and why does it require knowing a user's state?

The TCPA (Telephone Consumer Protection Act) is a series of US legislation that dictates limitations on how automated systems can reach out to customers over phone and SMS. Some TCPA regulations are federal, but states can impose their own requirements, meaning that the rules dictating how phone and SMS messages can be automated vary from state to state. You need to know what state a user lives in before you can send them TCPA-compliant messages.

For more on TCPA regulations, see TCPA.

How should a user's region and timezone be formatted so that Airkit can parse them correctly?

In order for Airkit to parse a user's established region and timezone, both region and timezone must be formatted correctly. Regions must be described by their State/Province Abbreviation Key, and timezones must be described by their TZ database names. (In Web applications, the timezone automatically saved and stored under session.timeZone is automatically saved in this format.)

If you want to read more about region and timezone designation, you can find a deeper dive into the subject in TCPA.

What is session.timeZone?

session.timeZone, is an automatically collected and managed global variable. It refers to the Actor's timezone by its TZ database name.. For more on what data is automatically collected and managed, see Standard Journey Data.

Like all global variables, session.timeZone is referenced by referring to the Session namespace.

What is the Actor and why does it need to be initialized?

An Actor represents someone who goes on an Airkit Journey. They can be identified by their phone numbers and their email addresses, because they serve as unique properties that are tied directly to the app user.

Out of the box, Actors are structured such that the Actor Namespace has the following 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) - defines when Notifications can and cannot be sent to the Actor from the Journey Builder. 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.

You can use dot notation when referencing a property within the Actor Namespace. For instance, to reference the Actor's phone number, access actor.phone wherever Airscript is accepted.

Variables saved in the Actor namespace are just that: locally-stored variables. They do not automatically establish communication channels any more than other locally-stored variables do.

In order to automatically parse and establish communication channels, relevant Actor properties must be copied into Airkit's actor_internal database. This is what is done in the process of Initializing the Actor. Once an Actor has been initialized with a value for actor.phone, it will send all outgoing calls and SMS messages to that phone number.

For more on Actors and the process of initializing them, see Actors.

What are Time Slots and Availability Schedules?

Availability Schedules define the windows of time in which appointments can be scheduled. They are made by combining the requirements of arbitrarily many Time Slots.

Time Slots define simple patterns of one-off or reoccurring blocks of time. A Time Slot might be, for instance, every day from 8AM to 9PM PST.

As Time Slots are the component parts of Availability Schedules, the blocks of time they describe are necessarily more simple. Consider that first example of a Time Slot: every day from 8AM to 9PM PST. This includes major holidays, and there is no easy way to define a Time Slot so that the repeating block of time does not appear on major holidays. Every day from 8AM to 9PM PST except for on multiple arbitrary dates does not count as a simple pattern.

More complex patterns, such as every day from 8AM to 9PM PST except for on multiple arbitrary dates including major holidays are best built out as Availability Schedules. When defining Availability Schedules, a Time Slot like every first day of the year can be subtracted from a Time Slot like every day from 8AM to 9PM PST, resulting in the more complex Availability Schedule every day from 8AM to 9PM PST except the first day of the year. Because Availability Schedules can be constructed out of arbitrarily many Time Slots, there is no limit to how intricate Availability Schedules can become.

Out of the box, Airkit comes with several Time Slots and Availability Schedules (as well as their component Time Slots) pre-configured. These correspond to regional TCPA regulations; utilizing them streamlines the process of creating TCPA-compliant apps.

For further discussion of Time Slots and Availability Schedules, see Schedules Builder.

What is a Schedule Object?

A Schedule Object is a type of App Object with a pre-defined structure intended to capture all relevant information pertaining to a scheduled appointment. Schedule Objects are used in tandem with a Scheduler Web Control; when a Schedule Object is associated with a Scheduler, all relevant information collected by users from the Scheduler will be automatically inserted into that Schedule Object in AirData.

A Schedule Object must contain the following six properties:

• session_id (string) - indicates the Journey that the appointment is associated with. This corresponds the Session ID (designated session.id) automatically assigned as a session-level variable at the start of each Journey

• start_time (DateTime) - refers to the beginning date and time of the appointment.

• end_time ( DateTime) - refers to the ending date and time of the appointment.

• recurrence (number)- indexes the block of time selected for the appointment. Count begins at 0 and on the first occurrence of a potential appointment window, as defined by the Time Slots that make up the Availability Schedule tied to the associated Scheduler Web Control.

• calendar_event_id (string) - serves as an identifier for the Time Slot (as defined in the Calendar Builder – note that this is not the same as the selected block of time which is indicated by recurrence) that defined the selected appointment block.

• calendar_id (string) - serves as an identifier for the particular instance of Schedule Web Control used to make the appointment. This becomes particularly relevant in cases a Journey contains multiple schedulers associated with the same Schedule Object.

For more on Schedules Objects, see Schedule Objects.

What is the difference between saving data to AirData and saving data as a global variable?

If you're familiar with the difference between saving data to the back-end and the front-end, that's precisely the difference between saving data to AirData and saving data as a global variable.

Saving data to AirData saves it to a database. This database can be queried, but the information stored within it is not by default available to be called on with the application. There's simply too much information stored in databases, and storing all that information so that it's readily available at all times wouldn't be very secure. To use data from Airdata within an application, you need to query AirData first, then save the returned information to a local variable.

Global variables are a type of local variable. They can be referenced within the application without needing to query anything, because they are stored locally.

When working with a Control Event, what does event.value refer to?

Some Control Events – such as the Value Changed Event associated with the Scheduler Web Control – have associated values. This information can be accessed within the associated Action Chain by referencing event.value or simply value, as Action Chains within Events implicitly default to referencing the Event namespace.

The format of the information stored in event.value changes depending on the nature of the Event, but in the case of the Scheduler Web Controls, its formatted according to the associated Schedule Object.

For more on Control Events, see Control Events.

What is a Journey Link?

A Journey Link leads to the most recently accessed Web Page within an existing Journey. It is capable of doing so because it contains a unique Journey identifier in the URL path.

For a deeper dive into how to conceptualize and use Journey Links, see Linking to Journeys.

Why send links as a separate text messages within a single Notification?

Most apps that process and display SMS messages come with a previewing functionality that displays a thumbnail of the associated web page with a received link. However, in order to do so, the link usually has to be sent as its own isolated SMS message. Sending a link as a separate text message makes it easier for the end user to see a preview the given link before clicking on it, ultimately resulting in a better use experience.

When are Notifications send from Journey Steps TCPA compliant?

All Notification send from Journey Steps are automatically TCPA complaint, provided you've initialized the Actor properly.

Enabling TCPA timing restrictions on Notifications sent from a Journey Step requires initializing the Actor with an appropriate value for actor.calendar_restriction.

actor.calendar_restriction expects an Availability Schedule Key, and Notifications sent from Journey Steps will only be sent within the windows of time described by the Availability Schedule. To simplify the process of defining actor.calendar_restriction, Airkit does it automatically whenever an Actor is initialized with values for actor.region and actor.time_zone, so that:

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

(This Availability Schedule Key should look very familiar! It's what we used to enforce TCPA compliance when scheduling our first two Notifications.)

This actor.calendar_restriction value references an out-of-the-box Availability Schedule that encompasses blocks of time the TCPA allows messages to be sent within the Actor's region and timezone. Outgoing Notifications sent from Journey Steps will only be sent within the allowed blocks of time.

For more on TCPA compliance and Notifications, see TCPA.

What number are outgoing text messages sent from?

This question is primarily important in the context to of publishing your application. See Publishing Your Application to learn more.

The Console provides the means to connect your phone numbers to your Org. Once connected to an Org, phone numbers will become available in Settings when accessing your application in the Studio. Under the Chat Bot section, you can select an available number to manage texts associated with your application. Once a phone number is configured, any outgoing texts will be sent from the configured number.

For more on how to associate your phone numbers with Airkit apps, see Connecting Your Twilio Numbers To Airkit.