​
1. Install The Botpress CLI

To get started, first install the Botpress CLI globally on your machine. You can do this by running the following command in your terminal:

npm install -g @botpress/cli
All the following examples use npm, but feel free to use the package manager of your choice like yarn or pnpm.

You can check that your installation was successful by running the following command:

bp --help

​
2. Log in to Botpress

Next, log in to your Botpress account using the Botpress CLI. You can do this by running the following command in your terminal:

bp login

This command will prompt you for a personal access token. You can create a new token by going to the Dashboard and navigating to the Personal Access Tokens page.

​
3. Initialize a New Bot

Next, create a new bot using the Botpress CLI. This will set up a new directory with the necessary files and structure for your bot.

bp init --type "bot" --name "my-bot" --template "empty"

​
4. Install Dependencies and Build

Once the bot is initialized, navigate to the bot directory and install the dependencies:

cd ./my-bot
npm i
bp build

​
5. Browse the Bot Files

You can now open the bot in VS Code or another code editor of your choice:

code .

Here’s a brief overview of the files and folders you’ll find in the bot directory:

  • bot.definition.ts: Contains the bot definition. It exports a data structure that describes your bot—what it can do, and how it can be used. This includes the bot’s actions, events. The definition also allows declaring your bot integration dependencies. Keep reading this documentation to learn about all the concepts you can define in this file.

  • src/index.ts: Contains the bot implementation. It exports a data structure that implements what was defined in the bot definition. Keep reading this documentation to learn about the available callbacks and handlers you can implement.

  • .botpress/: Contains the bot output, generated by the build command. It includes typings to help you implement your bot, and bundled JavaScript used to execute it. You can explore its contents, but avoid importing from nested files or folders, as its structure may change. Everything meant to be imported is available from the root of this folder.

  • package.json, tsconfig.json: As with any Node.js TypeScript project, these files contain your package’s metadata and dependencies, and the TypeScript configuration. The tsconfig.json file is preconfigured to offer the best experience with the Botpress SDK. Run npm run check:type to check for typing errors.

​
6. Install the Chat Integration

The Chat integration allows you to chat with your bot using HTTP requests. See the Chat Integration page for more information.

To install in your bot-as-code, run the following command:

bp add chat@latest

Then navigate to the bot.definition.ts file and add the following code:

import { BotDefinition } from "@botpress/sdk";
import chat from "./bp_modules/chat";

export default new BotDefinition({}).addIntegration(chat, {
  enabled: true,
  configuration: {},
});

To refresh typings available in your bot implementation, run the following command:

bp gen

​
7. Implement a message handlers

Let’s add some content to the bot. Open the src/index.ts file and add the following code:

bot.on.message("*", async (props) => {
  const {
    conversation: { id: conversationId },
    ctx: { botId: userId },
  } = props;

  if (props.message.type !== "text") {
    await props.client.createMessage({
      conversationId,
      userId,
      tags: {},
      type: "text",
      payload: {
        text: "Sorry, I can only respond to text messages.",
      },
    });
    return;
  }

  await props.client.createMessage({
    conversationId,
    userId,
    tags: {},
    type: "text",
    payload: {
      text: `You said: ${props.message.payload.text}`,
    },
  });
});

This bot will respond to any message sent to it. It will echo back the text message sent by the user. If the user sends a non-text message, like an image, the bot will respond with a message saying it can only respond to text messages.

​
8. Deploy the Bot

Once you’ve made the necessary changes to your bot, you can deploy it to Botpress Cloud. Run the following command:

bp deploy --create-new-bot

You’ll be prompted for some information and confirmations. The --create-new-bot flag will create a new bot in your workspace. If you want to deploy to an existing bot, you can omit this flag. The CLI will prompt you for the bot in which you want to deploy.

After deploying, go to the Dashboard. You should see your bot listed there.

​
9. Chat with your bot

Now you can chat with your bot using the CLI. Run the following command:

bp chat

This command will prompt you for the bot you want to chat with. Select the bot you just deployed, and start chatting with it. Press the escape key to exit the chat.