Skip to main content

Installation and Quick Start

In this guide we'll show you how to get up and running quickly. Read our Welcome page first if you just want to know what Botonic is about.

Let's get started!

Step 1 – Install the Botonic CLI

Open a terminal and run this command to install the CLI:

npm install -g @botonic/cli
  • NodeJS version >= 10 required
  • Mac/Linux users might need to run commands with sudo or run the installation with sudo npm i -g @botonic/cli --unsafe-perm=true --allow-root. Refer to npm for more information.
Don't want to install?

You can use botonic with npx @botonic/cli <command>

Step 2 – Create a Bot

Create a new Botonic project based on the "blank" template by running:

botonic new myBot blank

This command will scaffold a new Botonic project in myBot folder and install its dependencies.

  • It might take 2-3 minutes to complete
  • You can run this command without the last argument to see the list of all templates available: botonic new myBot

Step 3 – Run Your Bot

Now everything is ready to run your bot:

  1. Start the local development server:
cd myBot
botonic serve

Windows users might need to use the alternative npm run start

  1. Open http://localhost:8080/ in your web browser. You'll see the Botonic logo at the bottom-right corner, click on it to open the chat interface and start talking.

You'll notice that the bot doesn't understand anything you say, that's fine. In Botonic there are two main concepts that need to be defined in order to add functionality to your bot: routes and actions. If those are not defined, any user input will fallback to the "404" route that responds "I don't understand you" by default.


You can leave the botonic serve process running while you edit the code, the browser will auto-refresh the page when it detects changes in the source files.

Step 4 – Add a new route and action

  1. Edit the file src/routes.js with your favourite editor and add a new route:
import React from 'react'
import { Text, Reply } from '@botonic/react'

export const routes = [
path: 'initial',
text: /hi/i,
action: () => (
<Text>Hello! Nice to meet you ;)</Text>
How can I help you?
<Reply payload='search'>Search product</Reply>
<Reply payload='track'>Track my order</Reply>
  1. Go back to the browser and try typing "Hi there!":

The route we just defined indicates that any input text matching the regex /hi/i will be responded by the text "Hello! Nice to meet you ;)", defined in the action attribute.

Actions are just React components that can run random JS code (fetching data from APIs, etc) and return components supported by messaging channels, like Text or Reply

  • Routes are not limited only to regex, you can also use functions, intents trained by NLU models and more.
  • For simplicity sake we've defined everything in the same file, but typically actions live in their own file under src/actions.

Where to go from here

Cool, now you have a bot prototype working on your local browser. What can you do next: