Initialize Actor

The Initialize Actor Action sets the values for the Journey's current Actor. The Actor is an object that represents the current user's information.


When Initialize Actor is triggered, the actor variable is copied into Airkit's actor_internal variable for the current Journey. The main use of the actor_internal variable is so that a Chat Bot or Voice Bot knows which phone number to text or call.

The diagram below represents a Journey right before the Initialize Actor Action is called. The actor variable has been set using the Set Variable Action.

organizing info

This next diagram represents what happens when the Initialize Actor Action is triggered. Whatever is stored in the actor variable gets copied to Airkit's internals. Note that it is not possible for your App to access the actor_internal variable directly.

organizing info

Chat Bots, Voice Bots, and SMS Notifications can only text or call the user once the actor_internal has been initialized with a phone number. Email Notifications can only be sent once actor_internal has been initialized with an email address.

If there is an active Journey with an actor_internal whose phone number is the same as the actor when Initialize Actor is called, the Existing Session Behavior is triggered, as described below.

Default Behavior

Note that by default, a new App will start with two Actions added to the Session Start Event (found in the Connections Builder under Session): a Set Variable Action that copies session.start to your actor variable and the Initialize Actor Action. This is to easily allow for typical incoming phone and SMS behavior.


When the user begins a Journey with an incoming call or text, the session.start variable is populated with the user's phone number. The App copies that value to actor then calls Initialize Actor, which Dialogue Bots (ie: Voice Bots and Chat Bots) to reply to the user immediate through the channel they used to begin their Journey.

If your App requires more complex behavior, such as collecting the user's phone number or email address in a Web Flow and using those to send outgoing calls, texts, or Email Notifications, it will be necessary to add a new Initialize Actor Action to the Web Flow once the actor variable has been set with the relevant information.

Use Cases

  • To initialize the Actor when a user texts a Chat Bot and starts a new Journey, so that the Chat Bot can reply
    • This is the Default Behavior as described above
  • To collect the user's phone number in a Web Flow, then initialize the internal Actor to start a Voice Bot or Chat Bot with that user


Existing Session Behavior

If there is another active Journey with the same phone number in actor_internal when Initialize Actor is called, this property will determine how your App responds.


If there is an existing Journey with the same phone number, the latest text or call will take over that existing Journey.

This is most useful for a Chat Bot. When a user texts a Chat Bot, the Chat Bot should continue from the state of the running Chat Bot Journey. If a Chat Bot used the Fail behavior, each new text would start the Chat Bot over from the beginning.


If there is an existing Journey with the same phone number, the newer incoming call or text will be rejected.

This is most useful for a Voice Bot. If there is an active call with a user, and another call comes in with the same phone number (using Google Voice or similar), the second call should not be able to connect with the running Voice Bot Journey.


In this example, the Initialize Actor Action is triggered from an Event, which is capturing the informaion the user entered in a form. This way, the user and all their information saved in the  actor Variables will be set as the Actor of the Session.