Added advanced usage to README.md

README.md

@@ -67,3 +67,56 @@ nlu:
 ```
 
 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"
+```