Domains

The Domain defines the universe in which your assistant operates. It specifies the intents, entities, slots, and actions your bot should know about. Optionally, it can also include responses for the things your bot can say.

An example of a Domain

As an example, the domain created by rasa init has the following yaml definition:

intents:
  - greet
  - goodbye
  - affirm
  - deny
  - mood_great
  - mood_unhappy
  - bot_challenge

responses:
  utter_greet:
  - text: "Hey! How are you?"

utter_cheer_up:
  - text: "Here is something to cheer you up:"
    image: "https://i.imgur.com/nGF1K8f.jpg"

utter_did_that_help:
  - text: "Did that help you?"

utter_happy:
  - text: "Great, carry on!"

utter_goodbye:
  - text: "Bye"

utter_iamabot:
  - text: "I am a bot, powered by Rasa."

session_config:
  session_expiration_time: 60
  carry_over_slots_to_new_session: true

What does this mean?

Your NLU model will define the intents and entities that you need to include in the domain. The entities section lists all entities extracted by any entity extractor in your NLU pipeline.

For example:

entities:
   - PERSON          # entity extracted by SpacyEntityExtractor
   - time            # entity extracted by DucklingHTTPExtractor
   - membership_type # custom entity extracted by CRFEntityExtractor
   - priority        # custom entity extracted by CRFEntityExtractor

Slots hold information you want to keep track of during a conversation. A categorical slot called risk_level would be defined like this:

slots:
   risk_level:
      type: categorical
      values:
      - low
      - medium
      - high

Actions are the things your bot can actually do. For example, an action could:

respond to a user,
make an external API call,
query a database, or
just about anything!

Custom Actions and Slots

To reference slots in your domain, you need to reference them by their module path. To reference custom actions, use their name. For example, if you have a module called my_actions containing a class MyAwesomeAction, and module my_slots containing MyAwesomeSlot, you would add these lines to the domain file:

actions:
  - my_custom_action
  ...

slots:
  - my_slots.MyAwesomeSlot

The name function of MyAwesomeAction needs to return my_custom_action in this example (for more details, see Custom Actions).

Responses

Responses are messages the bot will send back to the user. There are two ways to use these responses:

If the name of the response starts with utter_, the response can directly be used as an action. You would add the response to the domain:

responses:
     utter_greet:
  - text: "Hey! How are you?"

Afterwards, you can use the response as an action in the stories:

## greet the user
* intent_greet
  - utter_greet

When utter_greet is run as an action, it will send the message from the response back to the user.

You can use the responses to generate response messages from your custom actions using the dispatcher: dispatcher.utter_message(template="utter_greet");.

Images and Buttons

Responses defined in a domain’s yaml file can contain images and buttons as well:

responses:
  utter_greet:
  - text: "Hey! How are you?"
    buttons:
    - title: "great"
      payload: "great"
    - title: "super sad"
      payload: "super sad"
  utter_cheer_up:
  - text: "Here is something to cheer you up:"
    image: "https://i.imgur.com/nGF1K8f.jpg"

Custom Output Payloads

You can also send any arbitrary output to the output channel using the custom: key. Note that since the domain is in yaml format, the json payload should first be converted to yaml format.

For example, although date pickers are not a defined parameter in responses because they are not supported by most channels, a Slack date picker can be sent like so:

responses:
  utter_take_bet:
  - custom:
      blocks:
      - type: section
        text:
          text: "Make a bet on when the world will end:"
          type: mrkdwn
        accessory:
          type: datepicker
          initial_date: '2019-05-21'
          placeholder:
            type: plain_text
            text: Select a date

Channel-Specific Responses

For each response, you can have multiple response templates. If you have certain response templates that you would like sent only to specific channels, you can specify this with the channel: key. The value should match the name defined in the name() method of the channel’s OutputChannel class.

responses:
  utter_ask_game:
  - text: "Which game would you like to play?"
    channel: "slack"
    custom:
      - # payload for Slack dropdown menu to choose a game
  - text: "Which game would you like to play?"
    buttons:
    - title: "Chess"
      payload: '/inform{"game": "chess"}'
    - title: "Checkers"
      payload: '/inform{"game": "checkers"}'
    - title: "Fortnite"
      payload: '/inform{"game": "fortnite"}'

Variables

You can also use variables in your responses to insert information collected during the dialogue.

responses:
  utter_greet:
  - text: "Hey, {name}. How are you?"

Rasa will automatically fill that variable with a value found in a slot called name.

Variations

If you want to randomly vary the response sent to the user, you can list multiple response templates and Rasa will randomly pick one of them.

responses:
  utter_greeting:
  - text: "Hey, {name}. How are you?"
  - text: "Hey, {name}. How is your day going?"

Ignoring entities for certain intents

If you want all entities to be ignored for certain intents, you can add the use_entities: [] parameter to the intent in your domain file.

intents:
  - greet:
      use_entities: []

Session configuration

A conversation session represents the dialogue between the assistant and the user. Conversation sessions can begin in three ways:

the user begins the conversation with the assistant,
the user sends their first message after a configurable period of inactivity,
a manual session start is triggered with the /session_start intent message.

You can define the period of inactivity after which a new conversation session is triggered in the domain under the session_config key. session_expiration_time defines the time of inactivity in minutes after which a new session will begin. carry_over_slots_to_new_session determines whether existing set slots should be carried over to new sessions.

The default session configuration looks as follows:

session_config:
  session_expiration_time: 60  # value in minutes, 0 means infinitely long
  carry_over_slots_to_new_session: true  # set to false to forget slots between sessions

The values specified will determine session behavior and state retention.