All SMS conversations take place between an Airkit application and the Actor who is accessing it. This document provides an overview of how to conceptualize and manage these conversations.

The Application

Under the hood, Airkit uses Twilio to manage SMS conversations. In order to send or receive SMS messages, an application must be associated with a Twilio number, which must be bought from Twilio, configured at the Org level, and then selected within the Settings of the relevant application. For more on associating Twilio numbers with Airkit applications, see Connecting Twilio Numbers.

The Actor

Every Session has an Actor, which represents an individual person going through an application flow. In order to exchange SMS messages with the Actor, the application needs to know the Actor's phone number. This means that the Actor must be correctly initialized in order to establish a proper communication channel between the application and the Actor; see Conversations with Actors for more information.

Defining SMS Conversations

Automatic SMS Conversations can be defined in two separate ways.

• SMS Notifications define one-off, outgoing messages.
• Chat Bots define two-way conversations.

Of the two, only Chat Bots are capable of parsing incoming messages. Chat Bots must be used whenever you want to receive reply through SMS. However, that is not to say SMS Notifications cannot contain calls to action. An SMS Notification might, for example, contain a web link and invite the Actor to navigate to it.

For more on SMS Notifications, see SMS Notification Basics. For more on Chat Bots, see Chat Bot Basics.

TCPA Compliance

TCPA (Telephone Consumer Protection Act) is a series of US legislation that dictates how automated systems can reach out to customers via SMS channels. Airkit's out-of-the-box tools streamline TCPA enforcement, but because TCPA compliance is state- and timezone-dependent, this information must be properly configured in order to automate SMS conversations that abide by TCPA regulations. For more information, see TCPA.

Tracking Outgoing SMS Messages

The status of outgoing texts sent from all Apps within an Organization can be found in the Console, under App Health. To see the status of text messages associated with a particular application, select the relevant application in the Stage, and select the SMS tab in the Inspector that appears.

In addition to seeing the total number of texts sent from the application, you can also check on the status of each text. The status categories are, broadly:

• Pending - The text is in the process of being dispatched.
• Delivered - The text was successfully delivered to the recipients device.
• Sent - The text was successfully sent to the nearest upstream carrier, but no confirmation was (yet) received that it was delivered to the recipient's device.
• Failed - The text failed to be delivered.

Examining an individual text can provide more detail on its status. Under the hood, Twilio handles SMS messages in Airkit; see Twilio's documentation on possible status values for more details.

Common Errors

When Previewing an application, texts can be sent as many times as needed for testing purposes. However, when an application is published, Airkit does not allow it to send the same text message to the same number multiple times with a 30-minute period. This provides an extra layer of protection against spamming users with redundant texts. However, it can also cause some unexpected behavior when testing an application that’s been published to a Development environment.

Attempting to send a text message to the same phone number multiple times in 30-minute period will throw the error labeled error.platform.message-limiter.duplicate-message-sent. This prevents any text messages but the first from reaching the relevant phone.

However, when testing applications, it is often useful to go through the designated flow multiple times in quick succession. To work around the safeguards for testing purposes, you can insert an Airscript expression into your automated text message so it is technically unique each time it is sent. For instance, say you have a variable, actor.first_name, that references the user’s first name. You can insert this into the body of the text so that the content of the text changes depending on how the user’s first name was defined:

"Hello, {{actor.first_name}}!"

You can also append a random number to the beginning or end of the text, using the function RANDOM. This way, each iteration of the text will contain a different number sequence, allowing multiple iterations to be sent to the same number for testing purposes:

"Hello! {{FORMAT_NUMBER(RANDOM(),"")}}"

In the above example, the function RANDOM is used in tandem with the function FORMAT_NUMBER to return a string.