Getting Started

Learn how to build your first project with Jovo v4, the framework that lets you create powerful conversational apps that work across voice and chat platforms like Alexa, Google Assistant, Facebook Messenger, the web, and more.

Introduction

With Jovo v4, we've completely redesigned how Jovo apps are built. Over the last year, we translated everything we learned from 4 years Jovo into a completely new framework.

If you're used to Jovo v3, you will see that there are a few differences which make the framework more powerful, extensible, and fun to use. Many of the underlying concepts stay the same, though. This guide is supposed to help you get started with a new Jovo project.

Here are a few of the key concepts of Jovo v4:

  • Components: A component can be seen as the equivalent of a state in Jovo v3. A Jovo app usually consists of multiple components. Each component has its own file that may contain multiple handlers.
  • Handlers: A handler responds to a certain type of request (for example, an intent) and contains the app logic. A handler can delegate to other components and return output.
  • Output: Using the $send() method, you can return structured output that is then translated into a native platform response.

In this guide, we will take a look at first steps with Jovo by installing a new project, and then go from there with next steps.

First Steps with Jovo

In this section, we will install the Jovo CLI, create a new project, understand the Jovo v4 project structure, and then test the app in the Jovo Debugger.

Install the CLI

You can install the new Jovo CLI like this:

$ npm install -g @jovotech/cli

After successful installation, you should be able to see the Jovo CLI menu by typing the following into your command line:

$ jovo

Create a new Project

After installing the Jovo CLI, you can install the template (TypeScript or JavaScript) using the new command:

$ jovo new <directory>

This will download the template into a new <directory> folder and install all necessary dependencies.

By using the "select features manually" option, you can choose which platforms you want to build Jovo apps for.

A Look at the Project Structure

Change your working directory into your newly created project and open it in the code editor of your choice.

$ cd <directory>

The Jovo v4 template includes the following key folders and files:

Here are all the files and folders inside src:

  • app.ts: This file contains the default Jovo app configuration. Plugins and other configurations are added here.
  • app.dev.ts: This file contains the app configuration for local development (dev stage). Learn more about staging here.
  • components: This folder contains all components. In this example, a GlobalComponent and a LoveHatePizzaComponent.
  • output: This folder contains all output classes, which offer a modular way to return structured output. This example includes a YesNoOutput class that is used by the START handler of the LoveHatePizzaComponent.

If we take a look at the GlobalComponent, we can find a LAUNCH handler that is executed for users who open the app:

LAUNCH() {
  return this.$redirect(LoveHatePizzaComponent);
}

It redirects to the LoveHatePizzaComponent. This means that the START handler of that component will be executed:

START() {
  return this.$send(YesNoOutput, { message: 'Do you like Pizza?' });
}

START uses an output class YesNoOutput to ask the user if they like pizza. This output is then returned to the user. If they respond with "yes", the lovesPizza handler get triggered, for "no" the hatesPizza handler:

@Intents('YesIntent')
lovesPizza() {
  return this.$send({ message: 'Yes! I love pizza, too.' });
}

@Intents('NoIntent')
hatesPizza() {
  return this.$send({ message: `That's OK! Not everyone likes pizza.` });
}

Run the Local Development Server

You can test the app code by running the local development server from the project directory:

$ jovo run

You can now open the Jovo Debugger with the . key.

You can then use the request buttons or type input to test the flow of the app.

Next Steps

Here are a few things you can do to extend the app:

  • Add more intents and entities to the Jovo Model.
  • Add handlers for these intents to the existing components.
  • Create new components.
  • Learn more about routing to understand when which components and handlers are executed.
  • Learn more about Jovo properties and how to use them.