Let external events and reminders trigger intents

changelog/4964.feature.rst

@@ -0,0 +1,5 @@
+External events and reminders now trigger intents (and entities) instead of actions.
+
+Add new endpoint ``/conversations/<conversation_id>/trigger_intent``, which lets the user specify an intent and a
+list of entities that is injected into the conversation in place of a user message. The bot then predicts and
+executes a response action.

changelog/4964.improvement.rst

@@ -0,0 +1,2 @@
+``ReminderCancelled`` can now cancel multiple reminders if no name is given. It still cancels a single
+reminder if the reminder's name is specified.

changelog/4964.removal.rst

@@ -0,0 +1,2 @@
+The endpoint ``/conversations/<conversation_id>/execute`` is now deprecated. Instead, users should use
+the ``/conversations/<conversation_id>/trigger_intent`` endpoint and thus trigger intents instead of actions.

docs/_static/spec/rasa.yml

@@ -255,8 +255,9 @@ paths:
       tags:
       - Tracker
       summary: Run an action in a conversation
+      deprecated: true
       description: >-
-        Runs the action, calling the action server if necessary.
+        DEPRECATED. Runs the action, calling the action server if necessary.
         Any responses sent by the executed action will be forwarded
         to the channel specified in the output_channel parameter.
         If no output channel is specified, any messages that should be
@@ -296,6 +297,57 @@ paths:
         500:
           $ref: '#/components/responses/500ServerError'
 
+  /conversations/{conversation_id}/trigger_intent:
+    post:
+      security:
+        - TokenAuth: []
+        - JWT: []
+      operationId: triggerConversationIntent
+      tags:
+        - Tracker
+      summary: Inject an intent into a conversation
+      description: >-
+        Sends a specified intent and list of entities in place of a
+        user message. The bot then predicts and executes a response action.
+        Any responses sent by the executed action will be forwarded
+        to the channel specified in the ``output_channel`` parameter.
+        If no output channel is specified, any messages that should be
+        sent to the user will be included in the response of this endpoint.
+      parameters:
+        - $ref: '#/components/parameters/conversation_id'
+        - $ref: '#/components/parameters/include_events'
+        - $ref: '#/components/parameters/output_channel'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/IntentTriggerRequest'
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  tracker:
+                    $ref: '#/components/schemas/Tracker'
+                  messages:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/BotMessage'
+        400:
+          $ref: '#/components/responses/400BadRequest'
+        401:
+          $ref: '#/components/responses/401NotAuthenticated'
+        403:
+          $ref: '#/components/responses/403NotAuthorized'
+        409:
+          $ref: '#/components/responses/409Conflict'
+        500:
+          $ref: '#/components/responses/500ServerError'
+
   /conversations/{conversation_id}/predict:
     post:
       security:
@@ -905,21 +957,34 @@ components:
       type: object
       properties:
         name:
-          description: >-
-            Name of the action to be executed.
+          description: Name of the action to be executed.
           type: string
           example: utter_greet
         policy:
-          description: >-
-            Name of the policy that predicted the action (optional).
+          description: Name of the policy that predicted the action.
           type: string
+          nullable: true
         confidence:
-          description: >-
-            Confidence of the prediction (optional).
+          description: Confidence of the prediction.
           type: number
+          nullable: true
           example: 0.987232
       required: ["name"]
 
+    IntentTriggerRequest:
+      type: object
+      properties:
+        name:
+          description: Name of the intent to be executed.
+          type: string
+          example: greet
+        entities:
+          description: Entities to be passed on.
+          type: object
+          nullable: true
+          example: {"temperature": "high"}
+      required: ["name"]
+
     Message:
       type: object
       properties:
@@ -1592,4 +1657,3 @@ components:
         properties:
           use_entities:
             type: boolean
-

docs/api/events.rst

@@ -88,7 +88,7 @@ Reset all Slots
 Schedule a reminder
 ~~~~~~~~~~~~~~~~~~~
 
-:Short: Schedule an action to be executed in the future.
+:Short: Schedule an intent to be triggered in the future.
 :JSON:
     .. literalinclude:: ../../tests/core/test_events.py
       :lines: 1-
@@ -99,8 +99,33 @@ Schedule a reminder
     .. autoclass:: rasa.core.events.ReminderScheduled
 
 :Effect:
-    When added to a tracker, core will schedule the action to be
-    run in the future.
+    When added to a tracker, Rasa Core will schedule the intent (and entities) to be
+    triggered in the future, in place of a user input. You can link
+    this intent to an action of your choice using the :ref:`mapping-policy`.
+
+
+Cancel a reminder
+~~~~~~~~~~~~~~~~~~~
+
+:Short: Cancel one or more reminders.
+:JSON:
+    .. literalinclude:: ../../tests/core/test_events.py
+      :lines: 1-
+      :start-after: # DOCS MARKER ReminderCancelled
+      :dedent: 4
+      :end-before: # DOCS END
+:Class:
+    .. autoclass:: rasa.core.events.ReminderCancelled
+
+:Effect:
+    When added to a tracker, Rasa Core will cancel any outstanding reminders that
+    match the ``ReminderCancelled`` event. For example,
+
+    - ``ReminderCancelled(intent="greet")`` cancels all reminders with intent ``greet``
+    - ``ReminderCancelled(entities={...})`` cancels all reminders with the given entities
+    - ``ReminderCancelled("...")`` cancels the one unique reminder with the given name
+    - ``ReminderCancelled()`` cancels all reminders
+
 
 Pause a conversation
 ~~~~~~~~~~~~~~~~~~~~

docs/core/actions.rst

@@ -102,36 +102,6 @@ e.g. by setting slots and send responses back to the user.
 All of the modifications are done using events.
 There is a list of all possible event types in :ref:`events`.
 
-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 <../../api/http-api/#operation/executeConversationAction>`_ ,
-specifying the action which 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 which 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 :ref:`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 a ``ActionReverted`` event to the end of the
-   conversation tracker.
-
 .. _default-actions:
 
 Default Actions

docs/core/responses.rst

@@ -156,3 +156,32 @@ The endpoint then needs to respond with the generated response:
   }
 
 Rasa will then use this response and sent it back to the user.
+
+
+.. _external-events:
+
+Proactively Reaching Out to the User with External Events
+---------------------------------------------------------
+
+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`` an intent to the
+`trigger_intent endpoint <../../api/http-api/#operation/triggerConversationIntent>`_.
+The intent, let's call it ``EXTERNAL_sensor``, will be treated as if the user had sent a message with this intent.
+You can even provide a dictionary of entities as parameters, e.g. ``{"temperature": "high"}``.
+For your bot to respond, we recommend you use the :ref:`mapping-policy` to connect the sent intent ``EXTERNAL_sensor``
+with the action you want your bot to execute, e.g. ``utter_warn_temperature``.
+You can also use a custom action here, of course.
+
+Use the ``output_channel`` query parameter to specify which output
+channel should be used to communicate the assistant's responses back to the user.
+Any messages that are dispatched in the custom action will be forwarded to the specified output channel.
+Set this parameter to ``"latest"`` if you want to use the latest input channel that the user has used.
+
+.. note::
+
+   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 :ref:`callbackInput` channel to send messages to a webhook.

rasa/core/agent.py

@@ -521,6 +521,20 @@ async def execute_action(
             sender_id, action, output_channel, self.nlg, policy, confidence
         )
 
+    async def trigger_intent(
+        self,
+        intent_name: Text,
+        entities: List[Dict[Text, Any]],
+        output_channel: OutputChannel,
+        tracker: DialogueStateTracker,
+    ) -> None:
+        """Trigger a user intent, e.g. triggered by an external event."""
+
+        processor = self.create_processor()
+        await processor.trigger_external_user_uttered(
+            intent_name, entities, tracker, output_channel,
+        )
+
     async def handle_text(
         self,
         text_message: Union[Text, Dict[Text, Any]],

rasa/core/constants.py

@@ -24,6 +24,7 @@
 
 # start of special user message section
 INTENT_MESSAGE_PREFIX = "/"
+EXTERNAL_MESSAGE_PREFIX = "EXTERNAL: "
 
 USER_INTENT_RESTART = "restart"
 
@@ -37,6 +38,9 @@
 
 BEARER_TOKEN_PREFIX = "Bearer "
 
+# Key to access data in the event metadata which specifies if an event was caused by an external entity (e.g. a sensor).
+IS_EXTERNAL = "is_external"
+
 # the lowest priority intended to be used by machine learning policies
 DEFAULT_POLICY_PRIORITY = 1
 # the priority intended to be used by mapping policies