# Opsdroid-RasaSR

Opsdroid Rasa Simple Respond is a bot that will simply respond with a randomly chosen phrase when rasa detects an intent. This skill is completely configurable from the opsdroid config, so there is no need to touch the source code unless you want more advanced behaviour.

## Usage

In order to edit your opsdroid configuration, make sure you are in your opsdroid virtual environment (if applicable) and run `opsdroid config edit`. Then you can add the following yaml in order to start the bot (note that this does not include connector configurations and you may need to merge the sections here with existing sections if you already have opsdroid set up).

```
parsers:
        rasanlu:
                url: http://localhost:5005
                models-path: models
                token: SUPER_SECRET_TOKEN
                min-score: 0.8

skills:
        rasa_greet:
                path: '/path/to/__init__.py'
                intent: 'greet'
                response_options:
                        - 'Why, hello there!'
                        - "What's up, ma dude"
                        - "Hello!"
                        - "Hiya!"
                        - "Wazzup"
                        - "How ya doin?"
```

You can include many of skills going the the same path with different intents and response\_options in order to be able to respond to many different types of message.

Of course, you will also need Rasa installed and running on your machine (`rasa run --enable-api --auth-token SUPER_SECRET_TOKEN`), and we will need to provide either a model or an intents file. Either way, we need an intents file. See the following example for the syntax.

```
version: "2.0"

nlu:
- intent: greet
  examples: |
    - hey
    - hello
    - hi
    - hello there
    - good morning
    - good evening
    - moin
    - hey there
    - let's go
    - hey dude
    - goodmorning
    - goodevening
    - good afternoon

- intent: goodbye
  examples: |
    - good afternoon
    - cu
    - good by
    - cee you later
    - good night
    - bye
    - goodbye
    - have a nice day
    - see you around
    - bye bye
    - see you later
```

And, again, you can add more intents here so that Rasa can recognise them. Put these intents in a file called intents.yml and Opsdroid will automatically send that to Rasa to train. 

## Advanced Usage

If you need to have more advanced responses, there are two more features available. You can enable the usage of entities, which allows you to substitute entities detected in the message into the response. You can also define a callback function that can be used to construct a message if more complex behaviour is required.

### Entity Substitution

In order to enable the ability to use entities, you must first add `use_entities: True` under this skill in your Opsdroid configuration file. This will allow the skill to extract the entities and automatically make substitutions. In order for the skill to know where to make the substitutions, we will be using f-string syntax. If an entity is required, but was not extracted by Rasa, then the substitution will fail. At this point, we will use a fallback response. If you wish to customise the possible fallback responses, add these to your Opsdroid config file under `fallback_response_options`.

Note on entity names: In order to have unique keys for each entity, the name of each entity is suffixed with an index representing the order in which the entities occurred. For example, the following input would lead to the following names (assuming Spacy entity extractor):

> What is the weather in Berlin and Dublin in November?

Entity name (key) | Entity value (value)
--- | ---
GPE0 | Berlin
GPE1 | Dublin
DATE0 | November

Here is an example of a skill config using this feature:

```
skills:
        location_repeater:
                path: "/path/to/skill.py"
                intent: "location_repeater"
                use_entities: True
                response_options:
                    - "You are in {GPE0}"
                    - "I think you are in {GPE0}"
                fallback_response_options:
                    - "Sorry, I couldn't figure out where you are."
```

### Callback Creation

If you need more advanced responses, you may want to use the callback feature. Firstly, you need to write a Python (same version that you are using for Opsdroid) function that takes in the message object (see Opsdroid for more documentation on how to use that), and a dictionary of extracted entities. This function should return a string which will be the message to be sent back to the room the request was made in.

Now you will need to add a few lines to your opsdroid configuration file. If you don't enable `use_entities`, then, even if Rasa detects the usage of entities, these will *not* be passed through to your function (None will be sent instead). You then need to provide the name of the python file with your function and the name of the function within that. Here is an example config for the example weather callback provided in this repo:

```
skills:
        rasa_weather:
                path: '/path/to/skill.py'
                intent: "weather"
                response_options:
                        - "Weather request received"
                use_entities: True
                fallback_response_options:
                        - "Sorry, Rasa did not extract sufficient entities to fulfil your request"
                callback_file: "/path/to/weather_callback.py"
                callback_name: "create_message"
```