Conversations with Actors

The previous section discussed what Actors are and their significance in enabling omni-channel Sessions. Here, we take a deeper dive into how to apply the concept of Actors by examining their relevance in establishing various communication channels, an important component of creating omni-channel Session.

Channels that require Actor Initialization

Chat Bots and Voice Bots

Two-way text and phone conversations are managed through Chat Bots and Voice Bots respectively. Dialogue Bots (the collective term for Chat Bots and Voice Bots) define how incoming messages are parsed and responded to. Each one is typically designed around a conversation flow. A Dialogue Bot might, for instance, share order tracking information upon request or walk Actors through the process of completing a survey. Chat Bots are defined and edited in the Chat Bots Builder, Voice Bots in the Voice Bots Builder.

Dialogue Bots are triggered as Actions. Specifically, Chat Bots are triggered by the Start Chat Bot Action and Voice Bots by the Start Voice Bot Action. These Actions can be taken at any point after the Actor has been initialized with an appropriate value stored as actor.phone. For a more detailed walkthrough of how to set up Dialogue Bots, see Building a Simple Chat Bot and Building a Simple Voice Bot.

SMS and Email Notifications

Notifications are outgoing email or SMS messages that do not require a response through the same channel. While Notifications cannot parse replies or incoming messages, they can still be used to prompt responses from the recipient. For example, Notifications might contain web links or cues to prepare for a previously-scheduled meeting. Most commonly, Notifications are used to send reminders or follow-up messages spurring users to continue a half-finished Session.

Both SMS and Email Notifications are defined and edited in the Notifications Builder.

Notifications can be sent as Actions. SMS Notifications are sent by the Send SMS Notification Action and can be taken at any point after the Actor has been initialized with an appropriate value stored as actor.phone. Email Notifications are sent by the Send Email Notification Action and can be taken at any point after the Actor has been initialized with an appropriate value stored as actor.email.

Initializing the Actor

The Actor can be initialized multiple times throughout a Journey. This is particularly relevant in cases when one Actor identifier is collected without the other. For instance, it's possible to begin a Session with an incoming call or text, at which case the phone number associated with the incoming call is automatically saved and used to initialize the Actor while the email of the Actor is still unknown. Should the email of the Actor later become relevant, the Actor will need to be initialized again.

Starting a Session with an incoming call or text

When a Session begins with an incoming call or text message, relevant starting parameters – such as the phone number and location of the caller – are saved automatically. (For more information on what information is automatically collected, see Information Captured from Incoming Calls and SMS.) The phone number of the incoming message is saved under the Session Namespace, which allows the value of session.start to set the actor variable. From there, the Actor can be initialized.

All of this is set up automatically as part of starting a Session. You can see this in the Connections Builder, when under Session -> Session Started. Inspecting the Session Started Event shows that it comes out-of-the-box with a configured Action Chain: one Actions sets the value of the Actor, and one Action initializes the Actor:

What number are these incoming texts and phone calls being sent to?

Whatever number you want to associate with the application!

The Console provides the means to connect your phone numbers to your Org. Once connected to an Org, phone numbers will become available in the Settings when accessing your application in the Studio. Under the Chat Bot section, you can select an available number to receive, send, and manage texts associated with your application. Likewise, under the Voice Bot section, you can select an available number to receive, send, and manage associated calls.

Once a phone number is configured, incoming messages to that phone number through the designated channel will automatically be parsed as part of a Session. For instance, suppose a phone number has been configured in the Voice Bot section of Settings. If a Session begins with the Calls a number Starting Event, any phone call made to the configured phone number will automatically trigger the start of a new Session. Any outgoing calls will also 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.

Initializing an Actor mid-Session

When a Session begins with an incoming call or text, Airkit can define actor.phone and use it to initialize the Actor by default, because the relevant data to do so is automatically collected, stored in the appropriate format, and bound to a pertinent variable. In cases where relevant Actor properties cannot be defined until a Session is already underway, the Actions required to define and initialize the Actor must be explicitly set manually and explicitly.

There are many ways to learn an Actor's phone number or email address. For instance, you could ask a user to give them directly via a form in a Web Flow, or you could pull their contact information from an external API. The varying means of collecting contact information necessitate that you explicitly define which piece of incoming data be used to define the Actor.

The process of doing so is largely a matter of replicating what is done by default when a phone number is collected through incoming calls and texts. When the phone number is collected, it can be used to set actor.phone. When the email address is collected, it can be used to set actor.email. Once both or either of these Actor properties has been set, the Actor can be initialized.

Initialize the Actor in 3 Steps

Step 1: Bind the relevant contact information to a variable.

Phone numbers and email addresses can be collected and bound to a variable just like any other value. For instance, if the relevant contact information was collected via an input box in a form, data binding will occur as part of the functionality of the input box. Note that in order to be used to properly initialize an Actor, actor.phone requires a properly-formatted phone number and actor.email requires a properly-formatted email address.

What does it mean for a phone number to be properly formatted?

Airkit expects phone numbers in the E.164 general format. Under the hood, Airkit uses the ISPHONE function to test if a string contains a valid phone number. See reference documentation on ISPHONE for more details on how phone number must be formatted in order to be parseable.

The function PARSE_PHONE can be used to convert an improperly-formatted phone number into a format that Airkit can parse, and thus use to establish a phone or SMS channel.

What does it mean for an email to be properly formatted?

Airkit expects email addresses to contain a username, followed by the @ symbol, followed by a domain. Under the hood, Airkit uses the ISEMAIL function to test if a string contains a valid email address. See reference documentation on ISEMAIL for more details on how phone number must be formatted in order to be parseable.

Step 2: Use the Set Variable Action to set the values of actor.phone and/or actor.email, as relevant.

Step 3: Use the Initialize Actor Action to initialize the Actor.

Once an Actor is initialized, communication channels associated with the relevant Actor property will be established automatically.

For instance, once an Actor is initialized with a value for actor.phone, voice and SMS channels will be established automatically. All incoming texts and calls from this phone number will be considered part of the established Session. All outgoing texts and calls will likewise be sent to the established phone number.

Likewise, once an Actor is initialized with a value for actor.email, all email Notifications will be automatically sent to the Actor's email address.