node-red-contrib-rasa-actionserver

Rasa Action Server on Node-RED

Rasa action server on Node-RED (or short rasaas ) is a set of nodes that can be used to implement an action server for Rasa-based chatbots. The current version of Rasa Action Server on Node-RED is developed and tested with Rasa v3.05 and Node-RED v2.1.5/Node v12.20.1 and Node-RED v3.0.2/Node v16.19.1.

Rasa

Rasa is a platform for building chatbots. A dialogue with a Rasa chatbot consists of a series of intents uttered by the user and actions by which the chatbot responds to the intents. Rasa chatbots can serve as conversational assistants, meaning, users give orders in natural language, which the assistant fulfills in the background. The chatbot delegates actions, which it is not able to perform by built-in means, to action servers. In Rasa terminology, these actions are termed custom actions, as they have to be implemented when building the conversational assistant. An action server is a system component which manages the fulfillment of custom actions.

Rasa action servers run as stand-alone servers and communicate with the chatbot via rest calls. Most often, fulfilling user orders involves calling further services. Rasa brings a Python SDK that supports setting up action servers. This can require a lot of coding, which can be a barrier for non-coders. Here, a platform like Node-RED, which specializes in wiring together services, APIs and even hardware devices, can be useful.

Node-RED

Node-RED is a low-code platform running on Node.js. With Node-RED, you get a browser-based GUI where you can create flows by drag-and-dropping nodes from a palette onto the flow editor. There are several core nodes which come with Node-RED natively as well as a wealth of additional nodes that are contributed by numerous sources.

You create a flow by connecting nodes in the visual editor. A flow passes JSON objects from node to node, with the nodes manipulating the JSON payload and performing the actions for which they were built.

Among the Node-RED core nodes, there are an HTTP in node as well as its counterpart, an HTTP response node. The HTTP in node creates an HTTP endpoint. An HTTP request hitting this endpoint triggers the flow starting at the HTTP in node. Normally, this flow should end in an HTTP response that answers the HTTP request with an HTTP response carrying a payload that the intermediate nodes of the flow have built. So, when an action server for Rasa is set up on Node-RED, custom action requests can be received by an HTTP in, and an HTTP response can serve the response to Rasa with the nodes in the flow creating this response.

Rasa uses JSON for communication with its action servers. Node-RED has several core nodes for manipulating JSON, with or without programming in JavaScript. Additionally, it is easy to install contributed nodes that connect to a multitude of APIs, like, e.g, database APIs, and cloud service APIs.

Rasa Action Server on Node-RED

Rasa Action Server on Node-RED implements a set of nodes that make it easy to set up an action server for Rasa chatbot on Node-RED. Specifically, these nodes implement the Rasa action server HTTP API as specified in Rasa Action Server HTTP API.

Currently, there are nodes for sending button responses, text responses, images and attachments. If other types of responses are needed, these may be generated by Node-RED built-in nodes.

How to use

Typical structure of a flow

A Rasa Action Server on Node-RED flow starts with a Node-RED core HTTP in node that handles the requests sent to the action server. The flow ends with a Node-RED core HTTP response node answering the requests sent by a Rasa chatbot.

The second node in Rasa Action Server on Node-RED flow should be the Init node. The Init node transforms the message object as emitted by the HTTP in node. It stores additional information in the flow scope (instead of node scope), in particular, the HTTP request and response objects that are required by the HTTP response node for completing the request. Consequently, the last node in a Rasa Action Server on Node-RED flow is an HTTP response node.

The second-to-last node is the Rasa Action Server on Node-RED finish node. This node assembles the message object into the correct format for the HTTP response node.

If an action server is able the perform several actions, a switch node following the init node can route the flow to corresponding branches.

The actions of the Rasa Action Server on Node-RED like, e.g., calls to APIs or databases are implemented by Node-RED nodes, speeding up development as pre-built Node-RED nodes for Web APIs and services can be used and wired together by visual programming.

The results of the actions, API calls, database queries, and so on, need to be transformed into a Rasa-compatible format before sending them back to Rasa chatbot. Specifically, the Rasa chatbot expects as a result responses that it utters in its dialog with a user.

Nodes generating responses

Currently, Rasa Action Server on Node-RED has three nodes that give support for these transformations:

• sendtext generates a simple text response,
• sendbuttons generates a response that generates buttons to be shown to the user,
• sendextra adds an image or an attachment to a response.

The nodes offer two options for providing content (i.e., text, references to images or attachments, or buttons) for the responses:

• specify a fixed text or content in the config of the node,
• specify in the node config how to retrieve the text or content from msg.payload.

A Rasa chatbot expects to receive an array of responses from the action server. The chatbot will present the responses to the user one by one corresponding to their order in the array. The nodes allow to specify the position where the response should appear in the responses array.

Admittedly, the send text node is redundant to some extent, since the other send nodes can also generate text responses. Nevertheless, the send text node helps to make the flows clearer and more declarative.

A node for setting slots

Slots are the memory of a Rasa chatbot. A slot is identified by a name and can store a piece of information that the chatbot has gathered during the dialogue. Slots are also sent to the action server in a custom action request. Typically, slot values serve as parameters for the actions that an action server performs. E.g., a weather bot needs to know the targeted location in order to yield correct weather information.

Slot values can easily be read and evaluated by Node-RED nodes. In some cases, it is necessary to clear or set Rasa slots within a custom action. This is supported by the setslots node.

An node for testing

Further, a simrasa node is provided. It sends a rasa-like message to the action server so that the actions can be tested without actually running rasa. simrasa is short for "Simulate rasa". The node emits a msg object containing all elements of a rasa action request that are needed for testing. In order to test an action, the http in node of an action server flow is substituted by an simrasa node. The action can be configured in the simrasa node. See the example flow in the rasa_simrasa_integ_test folder for details.

Testing

Since version v1.2, Rasa Action Server on Node-RED includes unit tests. Furthermore, it includes a test setup comprising a small Rasa chatbot and a Node-RED flow.

Installation

• Prerequisite: you have installed Node-RED
• Add Node-RED-contrib-rasa-actionserver to Node-RED palette
• Design your flow. Start it with an HTTP in node listening at /webhook
• Configure the action server endpoint in Rasa endpoints.yml, e.g.,

action_endpoint:
        url: http://127.0.0.1:1880/webhook

References

• Rasa Action Server HTTP API
• Weber, Irene: Low-code from frontend to backend: Connecting conversational user interfaces to backend services via a low-code IoT platform. In: CUI 2021 - 3rd Conference on Conversational User Interfaces. Bilbao (online) Spain : ACM, 2021 — DOI 10.1145/3469595.3469632 (preprint to be found in the media folder).

How to cite Rasa Action Server on Node-RED

In academic contexts, please cite the paper mentioned above as

^{@inproceedings{weberCuiLowcode2021, author = {Weber, Irene}, title = {Low-code from frontend to backend: {Connecting} conversational user interfaces to backend services via a low-code {IoT} platform}, booktitle = {{CUI} 2021 - 3rd {Conference} on {Conversational} {User} {Interfaces}}, address = {Bilbao (online) Spain}, doi = {10.1145/3469595.3469632}, isbn = {978-1-4503-8998-3}, url = {https://dl.acm.org/doi/10.1145/3469595.3469632}, publisher = {ACM}, month = jul, year = {2021}, pages = {1--5} }}