Merge pull request #421 from RasaHQ/bug_issue-8223

utter_message explicitly takes in response and template

changelog/8223.bugfix.md

@@ -0,0 +1 @@
+`utter_message` in `CollectingDispatcher` now explicitly takes in both `response` and `template`. Note that the parameter `template` will be deprecated in Rasa SDK 3.0.0. Please use `dispatcher.utter_message(response=...)` instead.

docs/docs/sdk-dispatcher.mdx

@@ -84,11 +84,11 @@ Passing multiple arguments will result in a rich response (e.g. text and buttons
   dispatcher.utter_message(json_message = date_picker)
   ```
 
-  - `template`: The name of a response template to return to the user. This response template should
+  - `response`: The name of a response to return to the user. This response should
               be specified in your assistants [domain](http://rasa.com/docs/rasa/domain).
 
   ```python
-  dispatcher.utter_message(template = "utter_greet")
+  dispatcher.utter_message(response = "utter_greet")
   ```
 
   - `attachment`: A URL or file path of an attachment to return to the user.
@@ -116,7 +116,7 @@ Passing multiple arguments will result in a rich response (e.g. text and buttons
 
   - `**kwargs`: arbitrary keyword arguments, which can be
               used to specify values for [variable interpolation in response variations](http://rasa.com/docs/rasa/responses). For example,
-              given the following response template:
+              given the following response:
 
   ```yaml
   responses:
@@ -127,7 +127,7 @@ Passing multiple arguments will result in a rich response (e.g. text and buttons
   You could specify the name with:
 
   ```python
-  dispatcher.utter_message(template = "utter_greet_name", name = "Aimee")
+  dispatcher.utter_message(response = "utter_greet_name", name = "Aimee")
   ```
 
 #### **Return type**

docs/static/spec/action-server.yml

@@ -41,7 +41,7 @@ paths:
                   $ref: "./rasa.yml#/components/schemas/Domain"
       responses:
         200:
-          description: Action was executed succesfully.
+          description: Action was executed successfully.
           content:
             application/json:
               schema:
@@ -88,6 +88,7 @@ components:
         - $ref: '#/components/schemas/ImageResponse'
         - $ref: '#/components/schemas/AttachmentResponse'
         - $ref: '#/components/schemas/TemplateResponse'
+        - $ref: '#/components/schemas/ResponseResponse'
 
     TextResponse:
       description: Text which the bot should utter.
@@ -107,7 +108,17 @@ components:
       additionalProperties:
         description: Keyword argument to fill the template
         type: string
-      required: ["template"]
+    ResponseResponse:
+      description: Response the bot should utter.
+      type: object
+      properties:
+        response:
+          description: Name of the response
+          type: string
+      additionalProperties:
+        description: Keyword argument to fill the response
+        type: string
+      required: ["response"]
     ButtonResponse:
       description: Buttons which should be sent to the user.
       type: object

rasa_sdk/executor.py

@@ -33,19 +33,27 @@ def utter_message(
         image: Optional[Text] = None,
         json_message: Optional[Dict[Text, Any]] = None,
         template: Optional[Text] = None,
+        response: Optional[Text] = None,
         attachment: Optional[Text] = None,
         buttons: Optional[List[Dict[Text, Any]]] = None,
         elements: Optional[List[Dict[Text, Any]]] = None,
         **kwargs: Any,
     ) -> None:
-        """"Send a text to the output channel"""
-
+        """Send a text to the output channel."""
+        if template and not response:
+            response = template
+            warnings.warn(
+                "Please pass the parameter `response` instead of `template` "
+                "to `utter_message`. `template` will be deprecated in Rasa 3.0.0. ",
+                FutureWarning,
+            )
         message = {
             "text": text,
             "buttons": buttons or [],
             "elements": elements or [],
             "custom": json_message or {},
-            "template": template,
+            "template": response,
+            "response": response,
             "image": image,
             "attachment": attachment,
         }
@@ -115,14 +123,14 @@ def utter_button_template(
     def utter_template(
         self, template: Text, tracker: Tracker, silent_fail: bool = False, **kwargs: Any
     ) -> None:
-        """"Send a message to the client based on a template."""
+        """Send a message to the client based on a template."""
         warnings.warn(
             "Use of `utter_template` is deprecated. "
-            "Use `utter_message(template=<template_name>)` instead.",
+            "Use `utter_message(response=<template_name>)` instead.",
             FutureWarning,
         )
 
-        self.utter_message(template=template, **kwargs)
+        self.utter_message(response=template, **kwargs)
 
     def utter_custom_json(self, json_message: Dict[Text, Any], **kwargs: Any) -> None:
         """Sends custom json to the output channel."""

rasa_sdk/knowledge_base/actions.py

@@ -130,7 +130,7 @@ async def run(
         if not object_type:
             # object type always needs to be set as this is needed to query the
             # knowledge base
-            dispatcher.utter_message(template="utter_ask_rephrase")
+            dispatcher.utter_message(response="utter_ask_rephrase")
             return []
 
         if not attribute or new_request:
@@ -140,7 +140,7 @@ async def run(
                 dispatcher, object_type, attribute, tracker
             )
 
-        dispatcher.utter_message(template="utter_ask_rephrase")
+        dispatcher.utter_message(response="utter_ask_rephrase")
         return []
 
     async def _query_objects(
@@ -220,15 +220,15 @@ async def _query_attribute(
         )
 
         if not object_name or not attribute:
-            dispatcher.utter_message(template="utter_ask_rephrase")
+            dispatcher.utter_message(response="utter_ask_rephrase")
             return [SlotSet(SLOT_MENTION, None)]
 
         object_of_interest = await utils.call_potential_coroutine(
             self.knowledge_base.get_object(object_type, object_name)
         )
 
         if not object_of_interest or attribute not in object_of_interest:
-            dispatcher.utter_message(template="utter_ask_rephrase")
+            dispatcher.utter_message(response="utter_ask_rephrase")
             return [SlotSet(SLOT_MENTION, None)]
 
         value = object_of_interest[attribute]

tests/test_executor.py

@@ -64,6 +64,40 @@ def test_deprecated_utter_elements():
         "elements": [1, 2, 3],
         "custom": {},
         "template": None,
+        "response": None,
+        "image": None,
+        "attachment": None,
+    }
+
+
+def test_utter_message_with_template_param():
+    dispatcher = CollectingDispatcher()
+    with pytest.warns(FutureWarning):
+        dispatcher.utter_message(template="utter_greet")
+
+    assert dispatcher.messages[0] == {
+        "text": None,
+        "buttons": [],
+        "elements": [],
+        "custom": {},
+        "template": "utter_greet",
+        "response": "utter_greet",
+        "image": None,
+        "attachment": None,
+    }
+
+
+def test_utter_message_with_response_param():
+    dispatcher = CollectingDispatcher()
+    dispatcher.utter_message(response="utter_greet")
+
+    assert dispatcher.messages[0] == {
+        "text": None,
+        "buttons": [],
+        "elements": [],
+        "custom": {},
+        "template": "utter_greet",
+        "response": "utter_greet",
         "image": None,
         "attachment": None,
     }
@@ -165,6 +199,7 @@ async def test_reload_module(
         "elements": [],
         "custom": {},
         "template": None,
+        "response": None,
         "image": None,
         "attachment": None,
     }
@@ -196,6 +231,7 @@ async def test_reload_module(
         "elements": [],
         "custom": {},
         "template": None,
+        "response": None,
         "image": None,
         "attachment": None,
     }