# Scenes

[Video](https://www.youtube.com/watch?v=CI-dSFP6_g4)

In combination with [intents](https://developers.google.com/assistant/conversational/intents), scenes are the other major building
block of your [conversation model](https://developers.google.com/assistant/conversational/actions#conversation_model). Scenes
represent individual states of your conversation and their main purpose is to
organize your conversation into logical chunks, execute tasks, and return
prompts to users.

Some features of scenes include:

- **Looped execution** - Scenes execute within a loop until it meets transition criteria that you define. This lets you create control logic flows much more efficiently within a single scene.
- **Dialog separation** - In combination with intents, scenes let you group dialogs into logical chunks, giving you easy ways to build user request and Action response pairs.
- **Intent match scoping** - Because only one scene can be active at a time, you can scope intent matching to scenes of your choice and have them match only when those scenes are active.
- **Slot filling** - You can use slot filling within a scene to collect multiple pieces of typed user input, without having to create multiple intents
- **In-scene conditions** - You can check slots, session, user, and home storage to carry out simple, conditional logic without triggering a webhook.

You can define scenes as part of your conversational model as a *custom scene* .
The conversational logic of Assistant also includes *system scenes* that
provide standard functionality for your conversation.

## Custom scenes

A custom scene is a building block of conversational logic that forms a part of
your Action's conversation model. Custom scenes have stages that define how and
when it starts, called the *Activation* , the conversational processing it
performs, called the *Execution lifecycle* , and how the scene ends, called the
*Transition*:

- [**Activation**](https://developers.google.com/assistant/conversational/scenes#activation) - Before a scene can execute, you must activate it through a global intent match or scene transition.
- [**Execution**](https://developers.google.com/assistant/conversational/scenes#execution) - When a scene is active, it executes in a well-defined lifecycle that lets you carry out a variety of tasks such as slot filling, conditional checking, prompt generation, and triggering webhook events.
- [**Transition**](https://developers.google.com/assistant/conversational/scenes#transition_and_exits) - When a scene meets criteria that you define, such as matching an intent or completing slot filling, you can transition to another scene to carry out even more logic. Alternatively, you can transition to the **End conversation** system scene, which ends the conversation with the user.

![](https://developers.google.com/static/assistant/conversational/images/scene-overview.svg) **Figure 1.** A common scene transition. A global intent activates a scene during invocation, the scene consumes user input and matches an intent, which transitions and activates another scene.

### Activation

Before a scene can execute, it needs to be active. Only one scene can be active
at any time. You can activate scenes in the following ways:

- **Invocation** - When user input matches a global intent's language model, you can activate a scene to process the invocation.
- **Static scene transition** - When a scene meets transition criteria, you can define a transition to another scene.
- **Dynamic scene transition** - Within a webhook handler, you can [programmatically transition to another scene](https://developers.google.com/assistant/conversational/webhooks#transition_scenes).

### Execution lifecycle

When a scene is active, it executes within a well-defined lifecycle that loops
until the scene meets transition criteria that you set. A scene's execution
lifecycle is separated into optional stages that run in the following order:

1. [**On enter**](https://developers.google.com/assistant/conversational/scenes#on_enter) - This stage runs only once when a scene is
   activated. You can trigger a webhook or prompt the user to do one-time setup
   of your scene.

2. [**Conditions**](https://developers.google.com/assistant/conversational/scenes#conditions) - Conditions lets you evaluate certain
   criteria before advancing lifecycle stages, triggering a webhook, or sending
   prompts. This stage can define transition criteria to exit the execution loop.

3. [**Slot filling**](https://developers.google.com/assistant/conversational/scenes#slot_filling) - A scene can automatically prompt users
   until it collects all required slots (typed data). A scene prompts for a
   single slot each time through its execution loop. If any slots are missing,
   the scene's lifecycle eventually loops back to the slot filling stage and
   prompts for the next required slot. This stage can define transition criteria
   to exit the execution loop.

4. [**Prompts**](https://developers.google.com/assistant/conversational/scenes#prompts) - Assistant delivers the prompt queue to the
   user and clears the queue. The prompt queue is the merged collection of
   prompts that were aggregated since the last time this stage cleared the queue.

5. [**Input**](https://developers.google.com/assistant/conversational/scenes#input) - Assistant consumes and returns user input to your
   scene, so you can process it, which might include intent matching (global
   intents or user intents within a scene), continuing slot filling (if it
   isn't complete), or handling no match or no input errors. This stage can
   define transition criteria to exit the execution loop. If it doesn't
   transition, the execution loop returns to the conditions stage.

![](https://developers.google.com/static/assistant/conversational/images/scene-lifecycle.svg) **Figure 2.** Scene execution lifecycle

The following sections describe each lifecycle stage in more detail.

#### On enter

On enter is the only stage that doesn't execute in a scene's execution loop.
It does one-time initialization of your scene in the following order:

- If the Assistant runtime can fill any slots from a previously matched intent, it does so now to prepare the scene for the slot filling stage. For example, some user input might match an intent and provide a slot. That intent match activates a scene and can fill a slot in a scene if the slot names match.
- If a webhook is enabled, it triggers an event synchronously and waits for your web service to return a response.
- When the runtime receives a webhook response, it resolves any parameter references in prompts and selects a prompt candidate based on the user surface and then selects one variant for the candidate to send to the user later.
- If the webhook response contains a prompt, it adds it to the prompt queue. If a static prompt also exists, the webhook prompt is merged into the prompt queue first, followed by the static prompt.
- If the webhook response contains a transition, it does so now. If not, the scene continues to the slot filling stage.

#### Conditions

Conditions lets you check session, user, or slot data for a condition to be
true. For example, you can check to see if all slots are filled and set that
as a criteria to transition to another scene to process the slots.

- The Assistant runtime evaluates each condition in the order that they're specified. The first condition that evaluates to `true` executes the associated handler and stops conditions evaluation.
- A condition `else if scene.slots.status = "FINAL"` is automatically added to the condition list if you do slot filling. This optional condition checks for slot filling to be complete and can trigger a webhook or add prompts to the prompt queue.

After condition evaluation, if the scene doesn't define a transition, it
continues to slot filling.

#### Slot filling

This stage adds a slot prompt for a single, unfilled and required slot. If you
don't define any slots in the scene, this stage does nothing.

- The Assistant runtime selects the first unfilled slot and adds the corresponding prompt to the prompt queue. Because the scene's execution loops, additional, unfilled slots are handled later when the execution loop returns to this stage.
- The current, active slot can have error handling prompts that override the ones defined in the scene's input stage.
- When the user fills a slot, you can validate it in a web service by triggering a webhook.

#### Prompts

The Assistant runtime delivers the prompt queue to the user, clears the queue,
and consumes user input.

#### Input

The Assistant runtime tries to match the input to an intent or a slot:

- In the case of a user intent match, the scene executes the associated intent handler (user or system intent). A scene's intent handler takes precedence over any global intents. If you didn't define a transition, the scene execution loops back the conditions stage.
- In the case of a slot match, the scene returns to the slot filling stage.
- In the case of a system intent match (for example, no input or no match),
  you can add prompts to the prompt queue, trigger a webhook, or transition. In
  the event of multiple no match prompts defined, the Assistant runtime chooses
  the most relevant, in the following order: slot filling, scene, then global
  no match prompts. Consecutive no matches generate a corresponding event:

  - `no_match_1`
  - `no_match_2`
  - `no_match_final`

  Each level of no match (slot filling, scene, and global) can trigger webhook
  events. By default, the third and final no match ends the conversation.

### Transition

Transitions can happen in the following stages:

- **Conditions** - You can transition to another scene based on conditions you define. A common condition to check for is slot filling to be complete.
- **Input (user intent matching)** - If an intent matches, it can trigger a transition to another scene.
- **Input (system intent matching)** - You can trigger webhooks during any system intent match event. For no match and no input events, the scene, by default, transitions to the **End conversation** scene after three occurrences.

## System scenes

System scenes let you use built-in, conversational logic provided by
Assistant, which lets you add standard conversational flows to your user
experience. For example, the account linking system scene lets Assistant
momentarily take over to carry out the account linking flow, returning the
information you need to actually link the user's accounts. System scenes don't
follow the standard scene lifecycle.

The following list describes supported system scenes and how to use them:

- **End conversation** - Closes the mic and ends the conversation with the user. The Assistant takes back control of the user experience after this scene executes.
- **Account linking** - Guides the user through an account linking flow and provides your Actions the required information to link the user's account on your backend servers with the user's Google account. See the [account
  linking](https://developers.google.com/assistant/identity) documentation for more information on how to use this scene.
- **Daily updates** - Guides the user through a confirmation flow to add your Actions to a user's daily updates. See the [daily
  updates](https://developers.google.com/assistant/engagement/daily) documentation for more information on how to use this scene.
- **Notifications** - Guides the user through a confirmation flow to receive notifications from your Actions. See the [push
  notifications](https://developers.google.com/assistant/engagement/notifications) documentation for more information on how to use this scene.