notice

This is unreleased documentation for Rasa Documentation Main/Unreleased version.
For the latest released documentation, see the latest version (3.x).

Version: Main/Unreleased

NLG Servers

Retraining the bot just to change the text copy can be suboptimal for some workflows. That's why Rasa also allows you to outsource the response generation and separate it from the dialogue learning.

The assistant will still learn to predict actions and to react to user input based on past dialogues, but the responses it sends back to the user will be generated outside of Rasa.

When the assistant wants to send a message to the user, it will call an external HTTP server that you define.

Responding to Requests

Request Format

When your model predicts that your bot should send a response to the user, it will send a request to your server, giving you the information required to select or generate a response.

The body of the POST request sent to your NLG endpoint will be structured like this:

New in 3.6

We have added an id field to the request body. This field contains the ID of the response variation. You can use this information to compose/select a proper response variation on your NLG server.

{
"response":"utter_what_can_do",
"arguments":{
},
"id": "<response_variation_id>",
"tracker":{
"sender_id":"user_0",
"slots":{
},
"latest_message":{
"intent":{
"id":3014457480322877053,
"name":"greet",
"confidence":0.9999994039535522
},
"entities":[
],
"text":"Hello",
"message_id":"94838d6f49ff4366b254b6f6d23a90cf",
"metadata":{
},
"intent_ranking":[
{
"id":3014457480322877053,
"name":"greet",
"confidence":0.9999994039535522
},
{
"id":8842445304628198686,
"name":"ask_forget_reminders",
"confidence":5.675940428773174e-07
},
{
"id":-2566831912141022859,
"name":"bye",
"confidence":3.418941929567154e-08
},
{
"id":8340513453672591403,
"name":"ask_id",
"confidence":2.5274500714544956e-08
},
{
"id":5822154213939471096,
"name":"ask_remind_call",
"confidence":2.4177523982871207e-08
}
]
},
"latest_event_time":1599476297.694504,
"followup_action":null,
"paused":false,
"events":[
{
"event":"action",
"timestamp":1599476297.68784,
"name":"action_session_start",
"policy":null,
"confidence":null
},
{
"event":"session_started",
"timestamp":1599476297.6878452
},
{
"event":"action",
"timestamp":1599476297.6878562,
"name":"action_listen",
"policy":null,
"confidence":null
},
{
"event":"user",
"timestamp":1599476297.694504,
"text":"Hello",
"parse_data":{
"intent":{
"id":3014457480322877053,
"name":"greet",
"confidence":0.9999994039535522
},
"entities":[
],
"text":"Hello",
"message_id":"94838d6f49ff4366b254b6f6d23a90cf",
"metadata":{
},
"intent_ranking":[
{
"id":3014457480322877053,
"name":"greet",
"confidence":0.9999994039535522
},
{
"id":8842445304628198686,
"name":"ask_forget_reminders",
"confidence":5.675940428773174e-07
},
{
"id":-2566831912141022859,
"name":"bye",
"confidence":3.418941929567154e-08
},
{
"id":8340513453672591403,
"name":"ask_id",
"confidence":2.5274500714544956e-08
},
{
"id":5822154213939471096,
"name":"ask_remind_call",
"confidence":2.4177523982871207e-08
}
]
},
"input_channel":"rest",
"message_id":"94838d6f49ff4366b254b6f6d23a90cf",
"metadata":{
}
}
],
"latest_input_channel":"rest",
"active_loop":{
},
"latest_action_name":"action_listen"
},
"channel":{
"name":"collector"
}
}

Here is an overview of the high-level keys in the post request:

KeyDescription
responseThe name of the response predicted by Rasa.
idAn optional string representing the response variation ID, can be null.
argumentsOptional keyword arguments that can be provided by custom actions.
trackerA dictionary containing the entire conversation history.
channelThe output channel this message will be sent to.

You can use any or all of this information to decide how to generate your response.

Response Format

The endpoint needs to respond with the generated response. Rasa will then send this response back to the user.

Below are the possible keys of a response and their (empty) types:

{
"text": "Some text",
"buttons": [],
"image": null, # string of image URL
"elements": [],
"attachments": [],
"custom": {}
}

You can choose to provide just text, or a combination of different types of rich responses. Just like the responses defined in the domain file, a response needs to contain at the very least either text or custom to be a valid response.

Calling responses from stories

If you use an external NLG service, you don't need to specify the responses under responses in the domain. However, you still need to add the response names to the actions list of the domain if you want to call them directly from your stories.

Configuring the Server URL

To tell Rasa where to find your NLG server, add the URL to your endpoints.yml:

endpoints.yml
nlg:
url: http://localhost:5055/nlg

If your NLG server is protected and Rasa will need authentication to access it, you can configure authentication in the endpoints:

endpoints.yml
nlg:
url: http://localhost:5055/nlg
#
# You can also specify additional parameters, if you need them:
# headers:
# my-custom-header: value
# token: "my_authentication_token" # will be passed as a GET parameter
# basic_auth:
# username: user
# password: pass