Newsletter robot
Enjoyed the read?

Don't miss our next article

AI Chatbot, Digital Workplace

How to create a Botpress workplace chatbot using business data

Make your Assistant Build your free AI-powered Digital Workplace platform in minutes, with our free forever plan. Digital Assistant logo Yes please

Botpress is an unusual offering in the landscape of AI chatbots: It's open-source which immediately puts it at the top of the list for many people. It's free and can be installed on your own equipment, and that last point especially is of interest to organizations that don't want all their chatbot requests to go to a Cloud they don't control.

But if you're planning to use Botpress for an internal office chatbot, will the open-source nature of the platform be a hindrance or an advantage? To find out, we've made our own little AI chatbot using Botpress below.

1. Determine a use case

Obviously, if you are wanting to create a workplace AI chatbot you need to have a scope for your project. We've already written a guide on how to find the best use cases for enterprise chatbots which you could check out.

For our purposes, we thought it would be cool to make a chatbot that looks up our newsletter subscriber count from Mailchimp. If we look at the Mailchimp API docs it seems that functionality should be readily available to be integrated into our chatbot.

2. Set up Botpress

To install Botpress all you have to do is head over to their website click on 'Download Free' and select your platform. We're going to install Botpress on a Mac, but if you have another platform you can check with their installation instructions.

Download the Botpress development tool from the Botpress website

After you downloaded the zip file and expanded it, you want to double-click the bp file within.

Running Botpress's development tool on a Mac

In the case of a Mac, this will open Terminal and run the installation which at the end should let you know that

Botpress is ready at http://localhost:3000/

Navigate to that page and then create your admin account.

3. Create a new bot

Creating a new bot in Botpress

Next, we want to actually create our first bot by click on Create Bot and then selecting New Bot.

I'm going to call our bot the Newsletter Bot, and then as a Bot Template I will select Empty Bot before clicking on Create bot.

Adding metadata to a new chatbot in Botpress

Now we want to go straight to Edit in studio which opens the otherwise empty bot in the development environment.

Navigating to the bot editor screen in Botpress

In the Studio you have a bunch of menus along the left:

  • Content: thats where you create different bot responses. You can also create and edit responses here, or you do that from within the Flow editor directly
  • Flows: here you design the chat flows for your bot. It will look familiar to you if you ever used any graphical workflow software. Basically each 'decision point' is shown as a Node where actions can be taken. The AI will automatically determine which path it takes based on the user's language
  • NLU: short for Natural Language Understanding. You can enter training phrases here for each ‘intent’ (action you want the bot to perform or process) so the it learns what phrases correlate to your defined actions
  • Q&A: these are just basic text responses. Basically this is good for questions like ‘Hello’, ‘Help’, or ‘What can you do?’.

4. Add smalltalk

We'll stick with the Q&A menu for a moment. Basically we'll use this menu to cover some of the basic smalltalk like 'Hi'.

Adding simple Q&A responses to a bot in Botpress

Just click on Add New and enter a list of questions you can think of that should trigger a given response from the bot.

Let's say we add in a pretty common 'What can you do?' style question. Q&A questions can be asked anytime, and they can either start a flow or directly skip to a specific node. Or, of course, they can just be on their own which we will go for (which is probably the majority of Q&A's made this way).

Adding simple Q&A responses to a bot in Botpress

You can of course add more smalltalk but we will move onto the next point.

5. Creating our first Flow

Our bot has a very specific use case: Tell the user how many subscribers are in the newsletter list. If the user however asks anything that does not match this intent, we should prepare our first Flow to handle that.

So navigate to the Flows menu and then click on Insert New Node.

Then double-click the new node and rename it to something like "No_match_found".

You also have three tabs in this popup: On Enter, On Receive and Transitions that you can add Actions to. These actions will be triggered when the conversation flows into this node and they could either be a text response or something more complicated like a script.

While we will add a complicated Action further down, for now we just want a simple text response that says:

Sorry, I didn't quite understand that. Can I help you with anything else?

So in the On Enter tab click on the Plus symbol icon to add a new action.

You will now see that the Message section is still blanked out and that's because messages have to be created in the Content system first. You can do that in the same dialogue though by clicking on the Blue folder icon blue folder icon.

6. Make a transition

Transitions are links between nodes. So in our example we want to link the start node to our new No_match_found node. For that, just double-click the start node and add a Transition to it.

If you select 'Intent is' as none and 'Transition to node' as No_match_found and click Update you should see an automatic line being drawn from the first node to the second.

Editor's tip:
At this point you could try to see if the bot picks up on this already by opening the Emulator button and typing in anything. However if you do that, be sure to hit Save Save button first because Botpress won't do it for you. 😉

7. Add a real Action

By now we've covered all the basics, so we can now move onto our actual use case: Getting the subscriber count from Mailchimp into our chatbot.

Like I said above, Actions allow the execution of code so we can use that to pull data dynamically from the Mailchimp API.

To create a new Action, navigate to the Code Editor tab and add a new .js function as shown.

Obviously this is where it gets a little tricky as you have to write your own function. Below is the function I used for Mailchimp which I've annotated as I go along. However if you don't happen to use Mailchimp yourself, this code will look vastly different.

/** Your code starts below */

const axios = require('axios');

Axios is a Botpress dependency that lets us make HTTP requests.

const listID = 'xxxxxxxxx';
const API_KEY = "xxxxxxxxxxxxxxxxxxxxxxx-us10";

Define the Mailchimp list ID that you want to get information about, as well as your Mailchimp API key. You can create your API key from your Mailchimp account settings and the list ID can be obtained from the list settings themselves.

Create an API key from account settings under Extras → API keys
const configAxios = {
    headers: {
        'authorization': "Basic " + Buffer.from('randomstring:' + API_KEY).toString('base64'),
        'Content-Type': 'application/json',

This is a configuration object for our request. We need to authenticate with the Mailchimp API before it can send us any data – this is where your API key comes in.

const getData = async () => {
    try {
        const { data } = await axios.get(`${listID}?fields=stats`, configAxios);
        temp.count = data.stats.member_count;
    } catch (err) {console.log(err)}

We make a network request to the Mailchimp API lists endpoint, in this case requesting specifically the ‘stats’ field. You can see documentation of the full API response here. Once we’ve got the data, we store the part we need in a memory variable – see below for more info about this. The name of the variable is important as we’ll need it in a moment, so don’t forget it!

return getData();
/** Your code ends here */

We return the function so the bot can call it when the correct conditions have been met. Make sure to save your code at this point!

8. Commit to Memory

Memory is temporary storage in the bot that can store data returned by an Action until it is parsed into a text response. We are only going to save our variable until the end of the Flow, but there's a full explanation of how Memory works in case you want to do more with it.

In our code this line saves the return from the API as temporary memory with the name temp.count:

temp.count = data.stats.member_count;

In a little bit we will create an Action and define what the bot should actually say. Botpress will automatically suggests we use the value stored from our script so there is nothing else to do.

9. Train the intent

For the bot to understand the user input we need to train it with sample utterances. To do that, switch to the NLU menu and click on New Intent. We'll name the intent get-subscriber-count.

Now let's add some possible questions or commands that the user might say when they want to trigger our Action. You should at least 5 utterances here so the bot can understand a variety of ways users might ask for the intent.

10. Add the Action

Finally we're ready to add the Action into our Flow. So let's switch back to the Flow menu and add a new Node, then double click that to edit it.

In the On Enter tab click the Plus icon to add a new action. In the next window we will select Execute code and select the action we made earlier from the dropdown.

So now this node will receive the data but there's one more thing we need to do to be able to answer the user: Parse the data into a sentence. So let's click the Plus icon again and this time we Say something and enter the following message:

There are currently {{temp.count}} active subscribers to the adenin Newsletter.

Note how this sentence uses {{temp.count}} as the placeholder from the Memory we created to dynamically insert out answer into the sentence.

Now we need to connect our start node to this new node. Double click on the start node again and go to the Transitions tab and click the Plus icon again. This time we'll select the get-subscriber-count intent.

Once that's done, we're done. The finished flow should look something like this:

11. Debugging

Next we give the bot a final test in the Emulator by asking one of the utterances from our training data.

Whatever the reply you'll get, a debugging console to the left of the chat gives you a clue about which steps your Flow took and with what percent of confidence the bot picked an Action.

12. Deploy

Deploying your Botpress chatbot is probably the easiest part as it comes with a handy webchat component. Just go back to the Botpress main admin panel and click on Open chat. That just loads your bot into a webchat module which you can directly link to.

Alternatively it's super easy to embed the webchat directly into your website using Botpress' documentation. And since you host the bot yourself it's entirely secure and everything stays behind your firewall.

Embedding the Botpress bot also allows you to customize the look and feel to match your Intranet look and feel.

Editor's tip:
If you're using a static site you can even get a module for webchat from npm.

Since version 12 you can also deploy your bots to external Channels, among them Microsoft Teams and Slack. That's extremely helpful and makes Botpress an even better tool for internally-facing chatbots, as most coworkers will want to use their chatbots on either one of those two.

However, the setup is a little long-winded as you can't simply go into a 'store' to enable these for your collaboration app. Instead you need to manually configure these as a custom App (for Slack) or a custom Bot (on your own Azure instance).


As always when we make a chatbot here's our key takeaways for Botpress.

Plus symbol Everything you need to run an on-premise, secure chatbot
Plus symbol Great documentation, community, debugging tools
Plus symbol The 'studio' while not sporting the slickest UI, is very robust and easy enough to understand
Plus symbol Webchat module easy to embed and customize
Plus symbol Free

Minus symbol Only for developers as there are no plug-and-play integrations with other applications
Minus symbol You need to host it yourself (on-premise or with a hosting provider)
Minus symbolNo Single Sign On for business applications built-in, so showing personalized lists, tasks, tickets, etc. will need even more scripting
Minus symbolSetting up external channels is not as easy as with other platforms

Overall using Botpress is quite pleasant, there are no blindspots in their functionality and the platform is quite lively, if a little geared towards developers. 👍

However, as you can see, for the specific purpose of building an internal chatbot, there are a few features we're missing: Just imagine you had a user that wanted to ask for their leave allowance through Slack, and Botpress would fall flat on its face. 🤷‍♀️

Article by: Henry Amm

I’m the Senior Director for the Digital Assistant Platform. Prevously gained 6 years of experience as an Intranet consultant. Fluent in German.

Join the discussion

This field is required.
This field is required.
This field is required.

0 responses

Be the first to leave a comment!