# Actions

Actions are the things your bot runs in response to user input. There are three kinds of actions in Rasa:

> 1. **Utterance actions**: start with `utter_`, just send a message to the user
> 2. **Custom actions**: any other action, these actions can run arbitrary code
> 3. **Default actions**: e.g. `action_listen`, `action_restart`, `action_default_fallback`

## [Utterance Actions](https://legacy-docs-v1.rasa.com/1.2.9/core/actions/#utterance-actions)

To define an utterance action (`ActionUtterTemplate`), add an utterance template to the domain file that starts with `utter_`:

```
templates:
  utter_my_message:
    - "this is what I want my action to say!"
```

It is conventional to start the name of an utterance action with `utter_`. If this prefix is missing, you can still use the template in your custom actions, but the template cannot be directly predicted as its own action. See [Responses](https://legacy-docs-v1.rasa.com/1.2.9/core/responses/#responses) for more details.

If you use an external NLG service, you don’t need to specify the templates in the domain, but you still need to add the utterance names to the actions list of the domain.

## [Custom Actions](https://legacy-docs-v1.rasa.com/1.2.9/core/actions/#custom-actions)

An action can run any code you want. Custom actions can turn on the lights, add an event to a calendar, check a user’s bank balance, or anything else you can imagine.

Rasa will call an endpoint you can specify when a custom action is predicted. This endpoint should be a webserver that reacts to this call, runs the code, and optionally returns information to modify the dialogue state.

To specify your action server, use the `endpoints.yml`:

```
action_endpoint:
  url: "http://localhost:5055/webhook"
```

And pass it to the scripts using `--endpoints endpoints.yml`.

You can create an action server in node.js, .NET, Java, or any other language and define your actions there - but we provide a small Python SDK to make development there even easier.

### [Custom Actions Written in Python](https://legacy-docs-v1.rasa.com/1.2.9/core/actions/#custom-actions-written-in-python)

For actions written in Python, we have a convenient SDK which starts this action server for you.

The only thing your action server needs to install is `rasa-sdk`:

```
pip install rasa-sdk
```

Note: You do not need to install `rasa` for your action server. E.g., it is recommended to run Rasa in a Docker container and create a separate container for your action server. In this separate container, you only need to install `rasa-sdk`.

The file that contains your custom actions should be called `actions.py`.

If you have `rasa` installed, run this command to start your action server:

```
rasa run actions
```

Otherwise, if you do not have `rasa` installed, run this command:

```
python -m rasa_sdk --actions actions
```

In a restaurant bot, if the user says “show me a Mexican restaurant”, your bot could execute the action `ActionCheckRestaurants`, which might look like this:

```python
from rasa_sdk import Action
from rasa_sdk.events import SlotSet

class ActionCheckRestaurants(Action):
   def name(self) -> Text:
      return "action_check_restaurants"

def run(self,
           dispatcher: CollectingDispatcher,
           tracker: Tracker,
           domain: Dict[Text, Any]) -> List[Dict[Text, Any]]:

cuisine = tracker.get_slot('cuisine')
      q = "select * from restaurants where cuisine='{0}' limit 1".format(cuisine)
      result = db.query(q)

return [SlotSet("matches", result if result is not None else [])]
```

You should add the action name `action_check_restaurants` to the actions in your domain file. The action’s `run` method receives three arguments. You can access the values of slots and the latest message sent by the user using the `tracker` object, and you can send messages back to the user with the `dispatcher` object, by calling `dispatcher.utter_template`, `dispatcher.utter_message`, or any other `rasa_sdk.executor.CollectingDispatcher` method.

### Details of the `run()` method:

#### `async` Action.`run`( `dispatcher`, `tracker`, `domain`)

Execute the side effects of this action.

##### Parameters

- **dispatcher** – the dispatcher which is used to send messages back to the user. Use `dispatcher.utter_message()` or any other `rasa_sdk.executor.CollectingDispatcher` method.
- **tracker** – the state tracker for the current user. You can access slot values using `tracker.get_slot(slot_name)`, the most recent user message is `tracker.latest_message.text` and any other `rasa_sdk.Tracker` property.
- **domain** – the bot’s domain

##### Returns

A dictionary of `rasa_sdk.events.Event` instances that are returned through the endpoint.

Return type: `List[Dict[str, Any]]`

### [Execute Actions in Other Code](https://legacy-docs-v1.rasa.com/1.2.9/core/actions/#execute-actions-in-other-code)

Rasa will send an HTTP `POST` request to your server containing information on which action to run. Furthermore, this request will contain all information about the conversation. [Action Server](https://legacy-docs-v1.rasa.com/1.2.9/api/action-server/#action-server) shows the detailed API spec.

As a response to the action call from Rasa, you can modify the tracker, e.g., by setting slots and sending responses back to the user. All of the modifications are done using events. There is a list of all possible event types in [Events](https://legacy-docs-v1.rasa.com/1.2.9/api/events/#events).

### [Proactively Reaching Out to the User Using Actions](https://legacy-docs-v1.rasa.com/1.2.9/core/actions/#proactively-reaching-out-to-the-user-using-actions)

You may want to proactively reach out to the user, for example, to display the output of a long-running background operation or notify the user of an external event.

To do so, you can `POST` to this [endpoint](https://legacy-docs-v1.rasa.com/1.2.9/api/http-api.html#tag/Tracker/paths/~1conversations~1{conversation_id}~1execute/post), specifying the action that should be run for a specific user in the request body. Use the `output_channel` query parameter to specify which output channel should be used to communicate the assistant’s responses back to the user. If your message is static, you can define an `utter_` action in your domain file with a corresponding template. If you need more control, add a custom action in your domain and implement the required steps in your action server. Any messages that are dispatched in the custom action will be forwarded to the specified output channel.

Proactively reaching out to the user is dependent on the abilities of a channel and hence not supported by every channel. If your channel does not support it, consider using the [CallbackInput](https://legacy-docs-v1.rasa.com/1.2.9/user-guide/connectors/your-own-website/#callbackinput) channel to send messages to a webhook.

Note: Running an action in a conversation changes the conversation history and affects the assistant’s next predictions. If you don’t want this to happen, make sure that your action reverts itself by appending an `ActionReverted` event to the end of the conversation tracker.

### [Default Actions](https://legacy-docs-v1.rasa.com/1.2.9/core/actions/#default-actions)

There are eight default actions:

| Action Name | Description |
| --- | --- |
| `action_listen` | Stop predicting more actions and wait for user input. |
| `action_restart` | Reset the whole conversation. Can be triggered during a conversation by entering `/restart` if the [Mapping Policy](https://legacy-docs-v1.rasa.com/1.2.9/core/policies/#mapping-policy) is included in the policy configuration. |
| `action_default_fallback` | Undo the last user message (as if the user did not send it and the bot did not react) and utter a message that the bot did not understand. See [Fallback Actions](https://legacy-docs-v1.rasa.com/1.2.9/core/fallback-actions/#fallback-actions). |
| `action_deactivate_form` | Deactivate the active form and reset the requested slot. |
| `action_revert_fallback_events` | Revert events that occurred during the TwoStageFallbackPolicy. |
| `action_default_ask_affirmation` | Ask the user to affirm their intent. |
| `action_default_ask_rephrase` | Ask the user to rephrase their intent. |
| `action_back` | Undo the last user message (as if the user did not send it and the bot did not react). Can be triggered during a conversation by entering `/back` if the MappingPolicy is included in the policy configuration. |

All the default actions can be overwritten. To do so, add the action name to the list of actions in your domain:

```
actions:
- action_default_ask_affirmation
```

Rasa will then call your action endpoint and treat it as every other custom action.