---
id: nlg
sidebar_label: NLG
title: 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:

:::info 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.

:::

```json
{
  "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: 

Key | Description
---|---
`response` | The name of the response predicted by Rasa.
`id` | An optional string representing the response variation ID, can be null.
`arguments` | Optional keyword arguments that can be provided by custom actions.
`tracker` | A dictionary containing the entire conversation history.
`channel` | The 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: 

```json
{
    "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](./responses.mdx), a response needs to contain at the very least
either `text` or `custom` to be a valid response. 

:::caution 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`: 

```yaml-rasa title="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:

```yaml-rasa title="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
```
