Actions Overview

Actions are how you program the Tasks your Autopilot bot performs. Actions are executed once a user invokes a Task during the dialogue. A user can be directed to a Task by the natural language understanding or by being redirected from another Task.

Actions can be any of the following:

• Say - instructs Autopilot what to speak or text back to the user.
• Play - instructs Autopilot to play pre-recorded audio to the user.
• Collect - instructs Autopilot to collect data from the user in a conversational form.
• Listen -instructs Autopilot to listen for user input, perform natural language understanding and route to the appropriate task.
• Redirect - instructs Autopilot to redirect the session to a specified task or URL.
• Handoff - hands off a voice call from an Autopilot bot to a TwiML voice URL or TaskRouter queue to connect the user to a human.
• Remember - instructs Autopilot to store a key-value pair in the assistant's memory.
• Show - instructs Autopilot to send images on channels that support them.

Every time a Task is invoked, Autopilot will execute the Actions for that Task. Actions are defined in a JSON array where each action is an object in the array. The array is then executed sequentially.

Actions allow you to write one conversational app that works across different channels like Twilio Programmable Voice, Twilio Programmable SMS, or your own custom channels.

Responding with Actions

When a Task is triggered, Autopilot makes a request to the URL configured on that Task and expects a response containing a valid sequence of Actions. You can set up the Task to respond with Actions that are either generated statically or dynamically.

Static Actions

You should respond with statically generated Actions if you don't need your bot to use any data from the context of the current conversation with the user in its dialogue. You can set up a task to respond with static Actions using the Actions Bin in the console or your own endpoint.

Dynamic Actions

You should respond with dynamically generated Actions if your bot needs to use data from the current conversation context in the dialogue, like the name or phone number of the user, or data from another data source, like the last purchase the user made for example. You can set up a Task to respond with dynamic Actions using the Redirect Action and Twilio Functions or your own endpoint.

Action Execution

Actions are executed sequentially in the context of a Dialogue and a Task until there are no more Actions or a transitional action is found. When there is a Redirect or a Collect, the actions are fetched in advance so that a single ordered response can be returned to the appropriate channel.

Say, Show and Remember are executed sequentially. Once any of these actions are executed Autopilot continues to the next one.

Redirect, Collect and handoff are transitional actions that change the flow of the dialogue, therefore any Task defined after any of these actions in the same JSON document will not be executed.

Allowed Sequences

The following sequences are allowed in the same JSON document

• Say, Play, Show, or Remember (in any order)
• Executes the Say/Show/Remember actions then dialogue will end.

• Say, Play, Show or Remember (in any order) then Redirect
• Executes the Say/Show/Remember actions then redirect to the specified Task or URL.

• Say, Play, Show or Remember (in any order) then Collect
• Executes the Say/Show/Remember actions then starts executing the Collect data collection Task.

• Say, Play, Show or Remember (in any order) then Handoff
• Executes the Say/Show/Remember actions then hands off to a human.

Invalid Sequences

• Redirect, Handoff, or Collect then Say, Play, Show or Remember
• The Say/Show/Remember actions will never execute as the dialogue is redirected to another Task or URL by the Redirect action.

• Redirect or Collect then Handoff
• The Handoff will never execute as the dialogue is redirected to another Task or URL by the Redirect action.

• Collect -> Redirect
  • The Redirect will never execute as the dialogue is redirected to another Task or URL by the Collect on_complete Redirect.

Task Context

All Autopilot Actions are executed within the context of a Task. This context changes when:

• A "redirect":"task://another-task" is used to redirect to another Task.
• A Collect is used to do data collection and on complete executes a Redirect action to another Task
• A Listen action is executed and the user is routed to a different Task.

The context of the task does not change when:

• A "redirect":"https://myapp.com/actions" is used to fetch more actions or build conditional logic. These are executed within the context of the same Task.

Dialogue termination

A Dialogue is terminated when one of the following happens

• There are no more Actions to execute in the JSON and there are no transitional Actions (Redirect, Collect, or Handoff).
• When a call is hung up by the user, the dialogue is terminated
• In messaging channels, if the user does not respond within 4 hours, the dialogue times out and is terminated.
• A Handoff action is used, the assistant hands off the session and ends the dialogue.

Actions JSON Schema

All the actions are defined in the following JSON Schema:

https://carnelian-neanderthal-8008.twil.io/assets/ActionsSchema.json

Follow this link to see the schema in full.

Example Actions JSON

{
	"actions": [
		{
			"say": "Hi there! I'm Jaimie your new Assistant. How can I help you"
		},
		{
			"listen": true
		}
	]
}
​

Create and Update Actions via the API

You can also use the Task Action Resource to create and update your assistant's task actions via the API.