Forem: Petr Janik

RASA - Session persistence

Petr Janik — Thu, 28 Jul 2022 08:41:14 +0000

In this article, we will add session persistence to the web chat application created in the previous post. This will allow a user to continue in the conversation with the chatbot even after a browser tab / window is closed.

First, we need to enable session persistence in the Rasa chatbot project. Set session_persistence to true.



# credentials.yml
socketio:
  user_message_evt: user_uttered
  bot_message_evt: bot_uttered
  session_persistence: true

Now the frontend will be responsible for generating a session ID and sending it to the Rasa server. It needs to emit a session_request event with session_id immediately after the connect event.

We'll manage the session ID by storing it in the localStorage.



function getSessionId() {
    const storage = localStorage;
    const storageKey = 'RASA_SESSION_ID';
    const savedId = storage.getItem(storageKey);
    if (savedId) {
        return savedId;
    }
    const newId = socket.id;
    storage.setItem(storageKey, newId);
    return newId;
}

The function getSessionId returns a session ID stored in the localStorage. If there is no such ID, it creates a new one, stores it in the localStorage and returns it. The session ID can be any string (number does not work) unique to every user (website visitor). socket.id is a good candidate.

Now when we have the getSessionId function, we can use it to get a session ID and send it immediately after the connect event. Change the connect event handler in index.html to the following:



socket.on('connect', function () {
    console.log('Connected to Socket.io server.');
    socket.emit('session_request', {
        'session_id': getSessionId(),
    });
    console.log(`Session ID: ${getSessionId()}`);
});

The same session ID must be sent with every user_uttered event. The event is emitted in two places:

in the appendQuickReplies function when the quick reply button is clicked and
when the form is submitted, i.e. when a user clicks Send.

We'll create a function utter(msg) that will send a message passed as a parameter and the session ID.



function utter(msg) {
    socket.emit('user_uttered', {
        'message': msg,
        'session_id': getSessionId(),
    });
}

Lastly, we will replace the two mentioned occurrences of the user_uttered event with calls to the utter function.



function appendQuickReplies(quickReplies) {
    const quickRepliesNode = document.createElement('div');
    quickRepliesNode.classList.add('quick-replies');
    quickReplies.forEach(quickReply => {
        const quickReplyDiv = document.createElement('button');
        quickReplyDiv.innerHTML = quickReply.title;
        quickReplyDiv.classList.add('button');
        quickReplyDiv.addEventListener('click', () => {
            messages.removeChild(quickRepliesNode);
            appendMessage(quickReply.title, 'sent');
            /** NEW CODE **/
            utter(quickReply.payload);
            /** ******** **/
        });
        quickRepliesNode.appendChild(quickReplyDiv);
    });
    messages.appendChild(quickRepliesNode);
    scrollToBottom();
}



form.addEventListener('submit', function (e) {
    e.preventDefault();
    const msg = messageInput.value;
    if (msg) {
        /** NEW CODE **/
        utter(msg);
        /** ******** **/
        messageInput.value = '';

        appendMessage(msg, 'sent');
    }
});

Run the application

Serve the application on http://localhost:8080 by running npx http-server webchat.
In a new terminal window, run the rasa server with enabled cors for all origins: rasa run --cors "*".
In another terminal window, run the actions server: rasa run actions.
Open http://127.0.0.1:8080 and chat with the chatbot!

You can see that the chatbot continues the conversation (it remembers the previous answers) even when we open a new tab.

What we implemented in this article is briefly described in the Rasa documentation here.

Repository for this tutorial:

petr7555 / rasa-dev-tutorial

You can checkout the state of the repository at the end of this tutorial by running:



git clone --branch 24-session-persistence git@github.com:petr7555/rasa-dev-tutorial.git

RASA - Giving voice to web chatbot

Petr Janik — Thu, 28 Jul 2022 08:30:00 +0000

In this article, we will add text-to-speech to the web chat application created in the previous post. There won't be anything new specific to Rasa, but you will learn how to improve the chatbot integration into a website.

We will add a button that will toggle between enabled and disabled states. When enabled, the received messages from the chatbot will be read aloud by the browser.

HTML

We'll start by adding the button to HTML.
At the beginning of the <body>, we define two symbols – one for volume on and the other for volume off.



...
<body>
  <svg aria-hidden="true" style="position: absolute; width: 0; height: 0; overflow: hidden;" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
    <defs>
      <symbol id="icon-volume_on" viewBox="0 0 24 24">
        <path d="M14.016 3.234q3.047 0.656 5.016 3.117t1.969 5.648-1.969 5.648-5.016 3.117v-2.063q2.203-0.656 3.586-2.484t1.383-4.219-1.383-4.219-3.586-2.484v-2.063zM16.5 12q0 2.813-2.484 4.031v-8.063q1.031 0.516 1.758 1.688t0.727 2.344zM3 9h3.984l5.016-5.016v16.031l-5.016-5.016h-3.984v-6z"></path>
      </symbol>
      <symbol id="icon-volume_off" viewBox="0 0 24 24">
        <path d="M12 3.984v4.219l-2.109-2.109zM4.266 3l16.734 16.734-1.266 1.266-2.063-2.063q-1.547 1.313-3.656 1.828v-2.063q1.172-0.328 2.25-1.172l-4.266-4.266v6.75l-5.016-5.016h-3.984v-6h4.734l-4.734-4.734zM18.984 12q0-2.391-1.383-4.219t-3.586-2.484v-2.063q3.047 0.656 5.016 3.117t1.969 5.648q0 2.203-1.031 4.172l-1.5-1.547q0.516-1.266 0.516-2.625zM16.5 12q0 0.422-0.047 0.609l-2.438-2.438v-2.203q1.031 0.516 1.758 1.688t0.727 2.344z"></path>
      </symbol>
    </defs>
  </svg>
  <header class="header">
    <p class="title">Chat with Rasa chatbot</p>
  </header>
...

Objects created inside a <defs> element are not rendered directly. To display them, we will reference them with a <use> element:



...
<form id="form">
  <input id="message-input" autocomplete="off" autofocus/>
  <svg id="icon-volume-on" style="display: none" class="button voice-icon">
    <use xlink:href="#icon-volume_on"></use>
  </svg>
  <svg id="icon-volume-off" class="button voice-icon">
    <use xlink:href="#icon-volume_off"></use>
  </svg>
  <button class="button">Send</button>
</form>
...

We already had the <input> and <button> and only added the two <svg> elements which contain a <use> element.
We want the feature to be disabled by default and display only the volume off icon. Hence we hide the volume on icon by adding style="display: none" to it.

Styles

Let's make the button nicer by adding this to the <style> tag in the <head>:



.voice-icon {
    fill: currentColor;
    font-size: 22px;
    width: 1em;
}

This should be the result:

JavaScript

The last step is to add the behaviour.
Let's create a toggleVoice function and add it as a click listener to the two buttons.



let voiceEnabled = false;
const iconVolumeOn = document.getElementById('icon-volume-on');
const iconVolumeOff = document.getElementById('icon-volume-off');

function toggleVoice() {
    if (voiceEnabled) {
        voiceEnabled = false;
        iconVolumeOn.style.display = 'none';
        iconVolumeOff.style.display = 'block';
    } else {
        if ('speechSynthesis' in window) {
            voiceEnabled = true;
            iconVolumeOn.style.display = 'block';
            iconVolumeOff.style.display = 'none';
        } else {
            alert("Sorry, your browser doesn't support text to speech.");
        }
    }
}

iconVolumeOn.addEventListener('click', toggleVoice);
iconVolumeOff.addEventListener('click', toggleVoice);

Depending on whether the voice is enabled or disabled, the function displays the appropriate icon and hides the other icon. It also sets voiceEnabled accordingly. The voice is enabled only when the SpeechSynthesis API is supported by the user's browser (this API is described later on).

You can now toggle the button:

For the text-to-speech, we'll use Web Speech API. It allows us to create a SpeechSynthesisUtterance instance to which we assign a text.
When this instance is passed to the window.speechSynthesis.speak function, the browser reads the text aloud.

We want to read aloud every message from the chatbot after it is received, therefore we add this code at the end of the appendMessage function:



if (voiceEnabled && type === "received") {
    const voiceMsg = new SpeechSynthesisUtterance();
    voiceMsg.text = msg;
    window.speechSynthesis.speak(voiceMsg);
}

That's it!

Run the application

Serve the application on http://localhost:8080 by running npx http-server webchat.
In a new terminal window, run the rasa server with enabled cors for all origins: rasa run --cors "*".
In another terminal window, run the actions server: rasa run actions.
Open http://127.0.0.1:8080 and chat with the chatbot!

Repository for this tutorial:

petr7555 / rasa-dev-tutorial

You can checkout the state of the repository at the end of this tutorial by running:



git clone --branch 23-text-to-speech git@github.com:petr7555/rasa-dev-tutorial.git

RASA - Socket.IO integration

Petr Janik — Mon, 30 Aug 2021 07:01:05 +0000

We already saw how to integrate Rasa chatbot with Tiwlio and Google Chat. In this article, I will show you how to integrate the Rasa chatbot with another messaging channel – Socket.IO.

This will be the result:

What is Socket.IO?

Socket.IO is a library that enables real-time bi-directional communication between a client and a server. It uses the WebSocket protocol.

You can write a simple chat application to learn the basics of Socket.IO.

Socket.IO is composed of two parts:

A server that integrates with the Node.JS HTTP Server – socket.io.
A client library that loads on the browser side – socket.io-client.

Let's get started!

By adding the following configuration to credentials.yml in your Rasa chatbot project, you will enable the Socket.IO server.



# credentials.yml
socketio:
  user_message_evt: user_uttered
  bot_message_evt: bot_uttered
  session_persistence: false

All that is left is a client.
Create a folder named webchat in the Rasa chatbot project.
Inside the webchat folder, create a new index.html file.
This file will contain the source code for the interactive web chat. You can view the complete code here.

Let's start with a markup.
At the top of the page, there will be a header.
All sent and received messages will be displayed in the middle. At the bottom, we will have a form with text input and a button to send messages.



<!DOCTYPE html>
<html>
  <head>
    <title>Socket.IO chat</title>
    <style>
      /* styles */
    </style>
  </head>
  <body>
    <header class="header">
      <p class="title">Chat with Rasa chatbot</p>
    </header>
    <div id="messages"></div>
    <form id="form">
      <input id="message-input" autocomplete="off" autofocus/>
      <button class="button">Send</button>
    </form>
  </body>
</html>

At the current stage, the page looks like this and doesn't do anything:

To connect to the Socket.IO server provided by Rasa, we need Socket.IO client library. We'll include it as a script from CDN before the closing </body> tag in index.html.



<script src="https://cdnjs.cloudflare.com/ajax/libs/socket.io/4.1.3/socket.io.js"
        integrity="sha512-PU5S6BA03fRv1Q5fpwXjg5nlRrgdoguZ74urFInkbABMCENyx5oP3hrDzYMMPh3qdLdknIvrGj3yqZ4JuU7Nag=="
        crossorigin="anonymous" referrerpolicy="no-referrer"></script>

Below this <script> we have just added, add another <script> that will contain the application logic.

Connect to the Rasa Socket.IO server:



<script>
    // Connect to RASA server
    const socket = io("http://localhost:5005");
</script>

The URL has a form of http://<host>:<port>, where the host and port are the appropriate values from your running Rasa server.

When the client connects, a connected event will be emitted. We can react to it and log a message into the console.



socket.on('connect', function () {
    console.log("Connected to Socket.io server");
});

In a similar way, log any connection errors.



socket.on('connect_error', (error) => {
    // Write any connection errors to the console 
    console.error(error);
});

When the user clicks the Send button, we obtain the input value and emit a user_uttered event, passing the input value as a value of a message field.
user_uttered is the event name for user messages we configured in credentials.yml.
We also append the message to the page and add corresponding classes for adding CSS later on.
Lastly, scroll to the bottom of the page.



const messages = document.getElementById('messages');
const form = document.getElementById('form');
const messageInput = document.getElementById('message-input');

form.addEventListener('submit', function (e) {
    e.preventDefault();
    const msg = messageInput.value;
    if (msg) {
        socket.emit('user_uttered', {
            "message": msg,
        });
        messageInput.value = '';

        appendMessage(msg, "sent");
    }
});

function appendMessage(msg, type) {
    const item = document.createElement('div');
    item.textContent = msg;
    item.classList.add("message");
    item.classList.add(`message_${type}`);
    messages.appendChild(item);
    scrollToBottom();
}

function scrollToBottom() {
    window.scrollTo(0, document.body.scrollHeight);
}

Rasa server processes the message and sends a response in the bot_uttered event payload.
bot_uttered is the event name for bot messages we configured in credentials.yml.
The response can contain various fields. We will handle text, attachment and quick_replies.



socket.on('bot_uttered', function (response) {
    console.log("Bot uttered:", response);
    if (response.text) {
        appendMessage(response.text, "received");
    }
    if (response.attachment) {
        appendImage(response.attachment.payload.src, "received");
    }
    if (response.quick_replies) {
        appendQuickReplies(response.quick_replies);
    }
});

If the response contains text, we want to display it in the chat as a message from the chatbot. This is done with the same method we used to append user's message but with a different class and therefore different CSS.

If the response contains attachment, we want to grab the attachment source and display it as an image sent by the chatbot.



function appendImage(src, type) {
    const item = document.createElement('div');
    item.classList.add("message");
    item.classList.add(`message_${type}`);
    const img = document.createElement('img');
    img.src = src;
    img.onload = scrollToBottom;
    item.appendChild(img);
    messages.appendChild(item);
}

If the response contains quick_replies, we want to display them as buttons that the user can click to send a message without a need for typing.

We attach a click event listener to each button to:

remove the quick replies,
append the title of the quick reply the user clicked on as a message from the user,
send the underlying quick reply payload.



function appendQuickReplies(quickReplies) {
    const quickRepliesNode = document.createElement('div');
    quickRepliesNode.classList.add("quick-replies");
    quickReplies.forEach(quickReply => {
        const quickReplyDiv = document.createElement('button');
        quickReplyDiv.innerHTML = quickReply.title;
        quickReplyDiv.classList.add("button");
        quickReplyDiv.addEventListener("click", () => {
            messages.removeChild(quickRepliesNode);
            appendMessage(quickReply.title, "sent");
            socket.emit('user_uttered', {
                "message": quickReply.payload,
            });
        })
        quickRepliesNode.appendChild(quickReplyDiv);
    })
    messages.appendChild(quickRepliesNode);
    scrollToBottom();
}

Styles

Finally, to make the page nicer, let's add some CSS.
First, add a CSS reset. Then add the rest of the styles.



/** CSS RESET        **/
/** ...              **/
/** END OF CSS RESET **/

body {
    --white-color: #f3f4fb;
    --black-color: black;
    --blue-color: #5a18ee;
    --light-purple-color: #7f7afc;
    --light-violet-color: #8c54f4;
    --darker-violet-color: #713dc3;
    --dark-violet-color: #5d2db0;
    font-family: Roboto, sans-serif;
    background-color: var(--blue-color);
}

#form {
    padding: 0.25rem;
    position: fixed;
    bottom: 0;
    left: 0;
    right: 0;
    display: flex;
    height: 3rem;
    box-sizing: border-box;
    background-color: var(--black-color);
}

#message-input {
    flex-grow: 1;
    padding: 0 1rem;
    border-radius: 2rem;
    margin: 0.25rem;
    background-color: var(--white-color);
}

#message-input:focus {
    outline: none;
}

.button {
    background: var(--light-violet-color);
    border: none;
    padding: 0 1rem;
    margin: 0.25rem;
    border-radius: 3px;
    outline: none;
    color: var(--white-color);
    font: inherit;
}

.button:hover {
    background: var(--darker-violet-color);
}

.button:active {
    background: var(--dark-violet-color);
}

#messages {
    display: flex;
    flex-direction: column;
    padding: 10px 10px 60px 10px;
}

.message {
    padding: 0.5rem 1rem;
    border-radius: 10px;
    word-wrap: break-word;
    max-width: calc(100% - 40px - 32px);
    margin-bottom: 10px;
}

.message_received {
    background: var(--white-color);
    color: var(--black-color);
    border-bottom-left-radius: 0;
    align-self: flex-start;
}

.message_sent {
    color: var(--white-color);
    background: var(--light-purple-color);
    border-bottom-right-radius: 0;
    align-self: flex-end;
}

.header {
    background-color: var(--black-color);
    color: var(--white-color);
    text-align: center;
    padding: 12px;
}

.title {
    font-size: 23px;
}

.quick-replies {
    display: flex;
    align-self: flex-end;
    height: 2.5rem;
    box-sizing: border-box;
}

Run the application

Now let's start the application from the webchat folder by running npx http-server ..

Because the rasa server will be running on http://localhost:5005 and our chat application is running on http://localhost:8080, we need to enable CORS for the rasa server.

Run the rasa server with enabled cors for all origins: rasa run --cors "*". Alternatively, enable only a specific host and port: rasa run --cors "http://127.0.0.1:8080".
In a new terminal window, run the actions server: rasa run actions.
Open http://127.0.0.1:8080 and chat with the chatbot!

The web chat we created does not support all Rasa functionality and it could be improved in many ways. If you want to add Rasa chat to your webpage, consider rasa-webchat which provides more features.

To learn more about Socket.IO channel connector, visit the Rasa documentation.

Repository for this tutorial:

petr7555 / rasa-dev-tutorial

You can checkout the state of the repository at the end of this tutorial by running:



git clone --branch 22-socketio-integration git@github.com:petr7555/rasa-dev-tutorial.git

RASA - Google Chat integration

Petr Janik — Mon, 09 Aug 2021 17:22:55 +0000

In a previous article, we saw how we can integrate a Rasa chatbot with Twilio messaging channel. In this article, I will show you how to integrate the chatbot with another messaging channel – Google Chat.

Who can use Google Chat

Google Chat (previously called Google Hangouts Chat) is Google's paid team chat service, provided only as part of Google Workspace. This means regular Google account is not enough, you have to be inside a Google Workspace.
Furthermore, in order to add a chatbot to Google Chat, you have to be an admin of that workspace.

Creating a Google Workspace

First, let's create a new workspace. To be able to create a new Google Workspace, you need to own a domain. You either already have one or you can purchase it.
Go to https://workspace.google.com/ and click Get started. Fill in the business name, number of employees, country and your contact info (follow the Google Workspace setup wizard).
Enter your domain name (e.g. petrjanik.com, but it must be yours). Complete the rest of the setup wizard.

Next, sign in to the newly created account. You will be prompted to select a payment plan. Google Workspace is a paid service, but it offers 14 days free trial, which will be enough for this experimental Rasa integration. Click Next. You will now need to fill in your address and payment method and details. You won't be billed until the 14 days free period ends. You can delete the account before the first payment.

You will be taken to the Admin console.

You will see a prompt to verify the domain you have entered earlier. You have to verify it in order to proceed with the setup. If you don't see the prompt, click Home -> Domains -> Manage domains. Click Verify domain. Follow the verification process till the end.

Creating a Google Cloud project

After the domain is verified, go to the Google Cloud Platform Console. We will create a new project and enable the Google Chat API.

Click Select a project -> NEW PROJECT.

Fill in the project name, organization and location. Click CREATE. Wait until it is created.
Select that project.
Search for "APIs & Services" and go there.

Click + ENABLE APIS AND SERVICES.
Search for "Google Chat API". Open the Google Chat API search result and click ENABLE.

On the Hangouts Chat API page, go to the Configuration.

Enter the name of the chatbot, avatar URL and a description. You can select whether the chatbot works in direct messages or in rooms and direct messages with multiple users.

In the Connection settings section, select Bot URL. The URL have the form of https://<host>:<port>/webhooks/hangouts/webhook. The protocol must be https, not http. Replace host and port with the host and port of your running rasa server. You can expose locally running rasa server using ngrok. Please refer to the previous article to find out how to use ngrok.

To make this channel endpoint available for Google Chat, all you need to do is to add the following to credentials.yml in your Rasa chatbot project.

# credentials.yml
hangouts:
  # no credentials required here

Run the rasa server: rasa run.
In a new terminal window, run the actions server: rasa run actions.
In a new terminal window, run ngrok: ngrok http 5005.
Ngrok is listening on port 5005 since this is where the rasa server is running.
Copy the https version of the tunnel URL that was generated by ngrok and paste it into the Bot URL input followed by /webhooks/hangouts/webhook.

Lastly, choose who in your domain can install this chatbot.
Click SAVE.

Start a chat with the chatbot

Go to the Google Chat application.
Click on Start a chat and search for your chatbot.

Now you are ready to chat with the chatbot! 🎉

You can see that Google Chat nicely displays rich responses as cards.

To learn more about Google Hangouts Chat channel connector, visit the Rasa documentation.

Repository for this tutorial:

petr7555 / rasa-dev-tutorial

You can checkout the state of the repository at the end of this tutorial by running:

git clone --branch 21-google-chat-integration git@github.com:petr7555/rasa-dev-tutorial.git

RASA - Synonyms

Petr Janik — Sat, 07 Aug 2021 11:39:21 +0000

Synonyms map extracted entities to a value other than the literal text extracted. You can use synonyms when there are multiple ways users refer to the same thing. Think of the end goal of extracting an entity and from there, figure out which values should be considered equivalent.

We have a frequency entity.



# domain.yml
# ... previous content ...
entities:
  # ... other entities ...
  - frequency

This entity is used to fill the frequency slot that has two possible values: once a week and twice a week.



# domain.yml
# ... previous content ...
slots:
  # ... other slots ...
  frequency:
    type: categorical
    values:
      - once a week
      - twice a week
    influence_conversation: true

The slot is filled during the newsletter_form.



# domain.yml
# ... previous content ...
forms:
  newsletter_form:
    # ... other slots ...
    frequency:
      - type: from_entity
        entity: frequency

Users might also refer to the once a week value as once or once per week

In this case, we will define once and once per week as synonyms to once a week:
Then, if either of these phrases is extracted as an entity, it will be mapped to the value once a week.

There are two ways of defining synonyms:

First option

Create a synonym key and list the mapped synonyms.



# data/nlu.yml
# ... previous content ...
  - intent: inform_frequency
    examples: |
      # ... other examples ...
      - [once a week](frequency)
      - [once](frequency)
      - [once per week](frequency)

  - synonym: once a week
    examples: |
      - once
      - once per week

We can see, that even though user entered "once per week", the extracted entity was "once a week".

Second option

We can also define synonyms in-line in our training examples by specifying the value of the entity:



# data/nlu.yml
# ... previous content ...
  - intent: inform_frequency
    examples: |
      # ... other examples ...
      - [twice a week](frequency)
      - [twice]{"entity": "frequency", "value": "twice a week"}
      - [twice per week]{"entity": "frequency", "value": "twice a week"}

We can see, that even though user entered "twice", the extracted entity was "twice a week".

Since frequency is now an entity, we need to annotate it in the test stories.

You can learn more about synonyms in the documentation here and here.

Repository for this tutorial:

petr7555 / rasa-dev-tutorial

You can checkout the state of the repository at the end of this tutorial by running:



git clone --branch 20-synonyms git@github.com:petr7555/rasa-dev-tutorial.git

RASA - Messaging channels - Twilio

Petr Janik — Thu, 05 Aug 2021 07:41:24 +0000

Messaging channels are interfaces such as Facebook Messenger, live chat window on a website, smart speaker etc.

Rasa uses pre-built connectors for a variety of messaging channels. You can also create your own custom connector.

In this article, we will connect our chatbot to the Twilio. We will be then able to communicate with the chatbot via SMS (text messages).

Our assistant is running locally on our PC. To make it available to external services, we will use ngrok. This tool simulates hosting our assistant on a server by creating a tunnel URL.
Download ngrok and make it available on PATH.

Create a Twilio account, if you don't have one already.
Then, create a new project.
After you have created the project, go to Console Dashboard.
Click Get a trial phone number and choose a phone number.

On the Console Dashboard – from the Project Info section – copy Account SID, Auth token and Phone number and add it to credentials.yml in the following format:

twilio:
  account_sid: "<your account sid>"
  auth_token: "<your auth token>"
  twilio_number: "<your twilio number>"

Copy the https version of the tunnel URL that was generated by ngrok and go to Twilio Phone Numbers page. Click on your assigned phone number in Active Numbers.
In Messaging section, put inside the A message comes in webhook input box the https URL from ngrok followed by /webhooks/twilio/webhook and save.

Send a text message to that Twilio phone number and the chatbot will reply!

You can connect as many messaging channels as you want.

To learn more about Twilio channel connector, visit the documentation.

You can learn more about messaging channels in the documentation.

Repository for this tutorial:

petr7555 / rasa-dev-tutorial

You can checkout the state of the repository at the end of this tutorial by running:

git clone --branch 19-messaging-channels git@github.com:petr7555/rasa-dev-tutorial.git

RASA - Custom submit action

Petr Janik — Tue, 27 Jul 2021 10:54:12 +0000

Eventually, we would like to do more than just print the user's responses to the screen.

In this article, we will learn how to send the form data to Airtable API.

Create an account on Airtable, if you already don't have one. A free account is enough.

On the Account overview page, generate an API key. Note this key aside.

Then visit https://airtable.com/shrnO6866oXVl7adV. Click Copy base. This will create a new base named Rasa dev tutorial with one table named Table 1.

In the upper right corner, click Help, then click API documentation. This opens an autogenerated API documentation for the base.

Copy the base ID starting with app. You will need it soon.

In the project root, create a new .env file:



AIRTABLE_API_KEY=key*****
BASE_ID=app*****
TABLE_NAME=Table%201

The TABLE_NAME is the name of the table in your Rasa dev tutorial base. Because it contains a space, the space is encoded for URL as %20.

Put your own AIRTABLE_API_KEY and BASE_ID in.
These values should be kept secret. Add the .env file to .gitignore, so that you don't accidentaly commit it to your version control system.

Add the following to .gitignore.



# keep secret keys out of VCS
.env

We will load those variables in the actions/actions.py with this code:



# actions/actions.py
load_dotenv()

airtable_api_key = os.getenv("AIRTABLE_API_KEY")
base_id = os.getenv("BASE_ID")
table_name = os.getenv("TABLE_NAME")

Make sure you have your python virtual environment activated (source venv/bin/activate).
Install two new packages. We will use them soon.



pip install python-dotenv requests

Add them to the requirements.txt file:



rasa==2.3.1
python-dotenv==0.15.0
requests==2.25.1

In actions/actions.py, you will need these imports:



# actions/actions.py
from typing import Text, List, Optional, Dict, Any
from rasa_sdk.forms import FormValidationAction
from rasa_sdk.executor import CollectingDispatcher
from rasa_sdk import Tracker, Action
from dotenv import load_dotenv
import os
import requests
import json
import uuid

In actions/actions.py, create a new method.



# actions/actions.py
def create_newsletter_record(email, frequency, notifications, can_ask_age, age):
    request_url = f"https://api.airtable.com/v0/{base_id}/{table_name}"

    headers = {
        "Content-Type": "application/json",
        "Accept": "application/json",
        "Authorization": f"Bearer {airtable_api_key}",
    }

    data = {
        "fields": {
            "Id": str(uuid.uuid4()),
            "Email": email,
            "Frequency": frequency,
            "Notifications?": notifications,
            "Can ask age?": can_ask_age,
            "Age": age,
        }
    }

    try:
        response = requests.post(
            request_url, headers=headers, data=json.dumps(data)
        )
        response.raise_for_status()
    except requests.exceptions.HTTPError as err:
        raise SystemExit(err)

    print(f"Response status code: {response.status_code}")
    return response

This method creates a URL, HTTP header and body and sends a POST request to Airtable API endpoint.
The body contains data we have obtained during the form loop from the user.
uuid.uuid4() is used to generate a unique identifier for the record.

Also in actions/actions.py, create a new class.
This class is a custom action. It extends an Action class. We can call this action in our rules and stories with - action: submit_newsletter_form, since submit_newsletter_form is what the name method returns.



# actions/actions.py
class SubmitNewsletterForm(Action):

    def name(self) -> Text:
        return "submit_newsletter_form"

    async def run(
            self, dispatcher, tracker: Tracker, domain: Dict[Text, Any],
    ) -> List[Dict[Text, Any]]:
        email = tracker.get_slot("email")
        frequency = tracker.get_slot("frequency")
        notifications = tracker.get_slot("notifications")
        can_ask_age = tracker.get_slot("can_ask_age")
        age = tracker.get_slot("age")

        response = create_newsletter_record(email, frequency, notifications, can_ask_age, age)

        dispatcher.utter_message("Thanks, your answers have been recorded!")

        return []

The run method is called when the action is called.
First, we get the slot values.
Then, we send them to the Airtable API using our previous method create_newsletter_record.
Lastly, we use dispatcher to utter a custom message.

The return value is a list of events that should follow. There are none in this case.

Don't forget to add this action to domain.yml.



# domain.yml
# ... previous content ...
actions:
  # ... previous actions ...
  - submit_newsletter_form

Call this action after the utter_subscribed action in the data/stories.yml and data/rules.yml.



# data/stories.yml
# ... previous content ...
stories:
  # ... previous stories ...
  - story: interactive_story_1
    steps:
      - intent: subscribe
      - action: newsletter_form
      - active_loop: newsletter_form
      - slot_was_set:
          - requested_slot: email
      - intent: chitchat
      - action: utter_ask_continue
      - intent: affirm
      - action: newsletter_form
      - slot_was_set:
          - requested_slot: email
      - slot_was_set:
          - requested_slot: frequency
      - intent: chitchat
      - action: utter_ask_continue
      - intent: affirm
      - action: newsletter_form
      - slot_was_set:
          - requested_slot: frequency
      - active_loop: null
      - action: utter_subscribed
      - action: submit_newsletter_form



# data/rules.yml
# ... previous content ...
rules:
  # ... previous rules ...
  - rule: submit form
    condition:
      - active_loop: newsletter_form
    steps:
      - action: newsletter_form
      - active_loop: null
      - action: utter_subscribed
      - action: submit_newsletter_form

Add the action also to the tests.

Retrain the model: rasa train.
Start the actions server: rasa run actions.
In a new terminal window, start the rasa shell: rasa shell.

The submit action created a new record in the table.

You can learn more about actions in the documentation.

In the next chapter, we will look at messaging channels.

Please note that I needed to make some changes to the notifications slot. Those changes can be seen on GitHub.

Repository for this tutorial:

petr7555 / rasa-dev-tutorial

You can checkout the state of the repository at the end of this tutorial by running:



git clone --branch 18-custom-submit-action git@github.com:petr7555/rasa-dev-tutorial.git

RASA - Custom forms

Petr Janik — Fri, 18 Jun 2021 05:53:10 +0000

What if we wanted to have a question in our form that should be asked only if the answer to the previous question was "yes"?

This is where custom actions come in handy.

A custom action can run any code you want, including API calls, database queries etc. They can turn on the lights, add an event to a calendar, check a user's bank balance, or anything else you can imagine.

You can learn more about custom actions in the documentation.

We will add two questions to our existing newsletter subscription form. First one asking if the user is OK with telling us their age and second one asking the age. Naturally, we want to ask the second question only if the user is fine with it.

To store the information from the user, we need to have the corresponding slots.

# domain.yml
# ... previous content ...
slots:
  # ... previous slots ...
  can_ask_age:
    type: bool
    influence_conversation: false  
  age:
    type: text
    influence_conversation: false

We also need to add the slots to the form, so that the corresponding questions are asked during the form loop.

# domain.yml
# ... previous content ...
forms:
  newsletter_form:
    # ... previous slots ...
    can_ask_age:
      - type: from_intent
        intent: affirm
        value: true
      - type: from_intent
        intent: deny
        value: false
    age:
      - type: from_entity
        entity: age

can_ask_age is a bool slot. If the intent is affirm, the value assigned to that slot will be true. If the intent is deny, the value assigned to that slot will be false.

You can learn more about boolean slots in the documentation.

Notice that we can use any number of type keys telling how the slot should be filled. The first one from the top that is matched is used.

Now let's add the questions. Remember, the name must be either utter_ask_<form_name>_<slot_name> or utter_ask_<slot_name>.

# domain.yml
# ... previous content ...
responses:
  # ... previous responses ...
  utter_ask_can_ask_age:
    - text: Can I ask what your age is?
  utter_ask_age:
    - text: What is your age?

Right now, the "What is your age?" question is always asked. This is because all slots that are part of a form are mandatory and have to be filled before the form ends. Luckily for us, there is an easy way to tell the chatbot what the mandatory slots are based on what we already know – like that the user does not want to share their age.

This is accomplished through custom actions. Custom actions live in actions/actions.py file.

For our use case, we will use a form validation action.
Form validation action is a class that extends a FormValidationAction class.
It has to implement a name method, which returns the name of that action. If we name it validate_<form_name>, it will be run automatically after each step of the form.

You can learn more about validation actions in the documentation.

We then override the required_slots method to tell what slots are mandatory and have to be filled.

You can learn more about this dynamic behaviour in the documentation.

# actions/actions.py
class ValidateNewsletterForm(FormValidationAction):
    def name(self) -> Text:
        return "validate_newsletter_form"

    async def required_slots(
            self,
            slots_mapped_in_domain: List[Text],
            dispatcher: "CollectingDispatcher",
            tracker: "Tracker",
            domain: "DomainDict",
    ) -> Optional[List[Text]]:
        if not tracker.get_slot("can_ask_age"):
            slots_mapped_in_domain.remove("age")

        return slots_mapped_in_domain

slots_mapped_in_domain parameter is a list of names of slots in our form. We remove the slot age from required slots if the value of can_ask_age slot is not True.

Any custom action that we want to use in our stories must be added into the actions section of our domain.

# domain.yml
# ... previous content ...
actions:
  - validate_newsletter_form

Lastly, uncomment the following code in endpoints.yml. This tells Rasa where to look for custom actions.

# endpoints.yml
action_endpoint:
  url: "http://localhost:5055/webhook"

Because we are using custom actions, we have to run an actions server. Run rasa run actions in a new terminal window.

You can learn more about this command in the documentation.

In another terminal, run rasa train && rasa shell.

We can see that when a user answers "no", the age is not asked, and the value is None.

You can learn more about the action server in the documentation.

In the next chapter, we will look at custom submit action.

Repository for this tutorial:

petr7555 / rasa-dev-tutorial

You can checkout the state of the repository at the end of this tutorial by running:

git clone --branch 17-custom-forms git@github.com:petr7555/rasa-dev-tutorial.git

RASA - Rich responses

Petr Janik — Thu, 10 Jun 2021 19:51:02 +0000

You can make responses rich by adding visual and interactive elements. There are several types of elements that are supported across many channels:

Buttons

We can create buttons in response by listing them under the text key. Each button has a title, which is the text displayed on the buttons that the user sees, and a payload, which is the message that is sent from the user to the assistant when the button is clicked.

payload can be either the message itself, intent, or both intent and entities.

We will extend the form from previous chapters.

Update the utter_greet intent to look like this:

# ... previous content ...
  utter_greet:
    - text: Hey! How are you?
      buttons:
        - title: great
          payload: I feel great
        - title: subscribe
          payload: I want to subscribe

This will display two buttons, each sending the corresponding text as if user typed it. It is then classified as one of the intents we have in our domain.

As part of our form, the chatbot is asking whether or not to enable notifications. Instead of making a button send a message and then hope it gets classified as a particular intent, we can directly specify the intent of each button (note the forward slash /).

# ... previous content ...
  utter_ask_notification:
    - text: Do you want notifications?
      buttons:
        - title: Yes
          payload: /affirm
        - title: No
          payload: /deny

Lastly, let's suppose that the user has two emails, one for work and one personal. We will let them choose which one they want to use for the subscription.

# ... previous content ...
  utter_ask_email:
    - text: Which email would you like to use?
      buttons:
        - title: Work email
          payload: /inform_email{{"email":"example@work.com"}}
        - title: Personal email
          payload: /inform_email{{"email":"example@home.com"}}

Here we are specifying both the intent and the entity.

Let's see the whole form in action:

It is up to the implementation of the output channel how the defined buttons are displayed. For example, some channels have a limit on the number of buttons you can provide.

We can see that terminal can't display the buttons. However, Rasa X can.

Images

You can add images to a response by providing a URL to the image under the image key. Let's add an image to the utter_greet response:

# ... previous content ...
  utter_greet:
    - text: Hey! How are you?
      buttons:
        - title: great
          payload: I feel great
        - title: subscribe
          payload: I want to subscribe
    image: http://gph.is/1LfEFeu

In the terminal, only link is visible:

In Rasa X, the image is visible:

You can learn more about rich responses in the documentation.

In the next chapter, we will look at custom forms.

Repository for this tutorial:

petr7555 / rasa-dev-tutorial

You can checkout the state of the repository at the end of this tutorial by running:

git clone --branch 16-rich-responses git@github.com:petr7555/rasa-dev-tutorial.git

RASA - Slots in detail

Petr Janik — Thu, 03 Jun 2021 08:54:09 +0000

Entities are automatically saved to slots that have the same name.

Let's create a new age entity:



# domain.yml
# ... previous content ...
entities:
  # ... previous entities ...
  - age

and a new age slot:



# domain.yml
# ... previous content ...
slots:
  # ... previous slots ...
  age:
    type: text
    influence_conversation: false

Let's create a new intent as well:



# data/nlu.yml
# ... previous content ...
  - intent: inform_age
    examples: |
      - My age is [20 years](age)
      - I am [15](age)
      - I am [47 years](age)
      - I am [8 years](age) old

and add it to domain.yml:



# domain.yml
# ... previous content ...
intents:
  # ... previous intents ...
  - inform_age

We need the chatbot's response as well:



# domain.yml
# ... previous content ...
  utter_age_back:
    - text: Your age is {age}.

The story now looks like this:



# stories.yml
# ... previous content ...
  - story: tell age
    steps:
      - intent: inform_age
      - action: utter_age_back

Let's see this in action:

The age entity was automatically saved to the age slot, because the name is the same.
Also, you can see that slots can be overwritten. First, the value of the slot was 17 years and then 64.

If a form contains a slot that is filled before the form is activated, that slot is not asked anymore as part of the form loop.

To demonstrate this, let's create the following story:



# stories.yml
# ... previous content ...
  - story: tell email
    steps:
      - intent: inform_email
      - action: utter_email_back

Normally, the chatbot would ask "What is your email address?" to fill the email slot. But since the slot is filled beforehand, it asks only frequency and notifications.

You can learn more about slots in the documentation or in my previous article.

In the next chapter, we will look at rich responses, such as buttons and images.

Repository for this tutorial:

petr7555 / rasa-dev-tutorial

You can checkout the state of the repository at the end of this tutorial by running:



git clone --branch 15-slots-in-detail git@github.com:petr7555/rasa-dev-tutorial.git

RASA - OR statements

Petr Janik — Fri, 28 May 2021 18:02:12 +0000

Another way to write shorter stories, or to handle multiple intents the same way, is to use an or statement.

For example, if you ask the user to confirm something, and you want to treat the affirm and thankyou intents in the same way. The story below will be converted into two stories at the training time:



# stories.yml
# ... previous content ...
  - story: confirm by affirm or thankyou
    steps:
      - intent: confirm
      - action: utter_ask_confirm
      - or:
          - intent: affirm
          - intent: thankyou
      - action: utter_confirmed

For this example to work, apart from the code we have from the previous chapters, I have created two new intents:



# data/nlu.yml
# ... previous content ...
  - intent: confirm
    examples: |
      - can I confirm
      - I want to confirm
      - I would like to confirm that
  - intent: thankyou
    examples: |
      - thank you
      - thanks
      - thanks a lot
      - thank you so much!

and added them to domain.yml:



# domain.yml
# ... previous content ...
intents:
  # ... previous intents ...
  - confirm
  - thankyou

We need the chatbot's responses as well:



# domain.yml
# ... previous content ...
  utter_ask_confirm:
    - text: Do you really want to confirm that?
  utter_confirmed:
    - text: Confirmed.

Let's see this in action:

You can learn more about OR statements in the documentation.

In the next chapter, we will look at slots in detail.

Repository for this tutorial:

petr7555 / rasa-dev-tutorial

You can checkout the state of the repository at the end of this tutorial by running:



git clone --branch 14-or-statements git@github.com:petr7555/rasa-dev-tutorial.git

RASA - Checkpoints

Petr Janik — Thu, 20 May 2021 15:55:12 +0000

You can use checkpoints to modularize and simplify your stories. Checkpoints can be useful, but do not overuse them. Using lots of checkpoints can quickly make your example stories hard to understand, and will slow down training.

Here is an example that contains checkpoints:

# stories.yml
# ... previous content ...
  - story: beginning of flow
    steps:
      - intent: ask_how_i_feel
      - action: utter_ask_user_question
      - checkpoint: check_asked_question

  - story: handle user affirm
    steps:
      - checkpoint: check_asked_question
      - intent: mood_great
      - action: utter_great
      - checkpoint: check_flow_finished

  - story: handle user deny
    steps:
      - checkpoint: check_asked_question
      - intent: mood_bad
      - action: utter_bad
      - checkpoint: check_flow_finished

  - story: finish flow
    steps:
      - checkpoint: check_flow_finished
      - intent: goodbye
      - action: utter_goodbye

Checkpoints can have any name.

For this example to work, apart from the code we have from the previous chapters, I have created the following intents:

# data/nlu.yml
# ... previous content ...
  - intent: mood_bad
    examples: |
      - my day was horrible
      - I am sad
      - I don't feel very well
      - I am disappointed
      - super sad
      - I'm so sad
      - sad
      - very sad
      - unhappy
      - not good
      - not very good
      - extremly sad
      - so saad
      - so sad

  - intent: goodbye
    examples: |
      - cu
      - good by
      - cee you later
      - good night
      - bye
      - goodbye
      - have a nice day
      - see you around
      - bye bye
      - see you later

  - intent: ask_how_i_feel
    examples: |
      - Ask me how I feel
      - Do you want to know how I feel?
      - Ask me about my feelings

and added them to domain.yml:

# domain.yml
# ... previous content ...
intents:
  # ... previous intents ...
  - mood_bad
  - goodbye
  - ask_how_i_feel

We need the chatbot's responses as well:

# domain.yml
# ... previous content ...
  utter_ask_user_question:
    - text: How do you feel?
  utter_great:
    - text: Glad to hear that!
  utter_bad:
    - text: I'm sorry to hear that.
  utter_goodbye:
    - text: Bye

Let's see this in action:

You can learn more about checkpoints in the documentation.

In the next chapter, we will look at OR statements.

Repository for this tutorial:

petr7555 / rasa-dev-tutorial

You can checkout the state of the repository at the end of this tutorial by running:

git clone --branch 13-checkpoints git@github.com:petr7555/rasa-dev-tutorial.git