Quickstart

Build your first Botpress bot in under 5 minutes with this hands-on guide

Get your first Botpress bot up and running in minutes. This guide takes you from installation to deployment with real working code.

Prerequisites

Before you begin, make sure you have:

• Node.js 18.0.0 or higher installed on your machine
• A Botpress Cloud account (sign up at app.botpress.cloud)
• Your Personal Access Token from Botpress Cloud

Find your Personal Access Token in the Botpress Cloud dashboard under your profile settings.

Install the Botpress CLI

1. Install the CLI globally

   Choose your preferred package manager:

   npm

   npm install -g @botpress/cli
   
2. Verify installation

   Confirm the CLI is installed correctly:

   bp --version
   

   You should see the version number displayed.

3. Authenticate with Botpress Cloud

   Log in to connect your CLI to your Botpress workspace:

   bp login
   

   When prompted:

   1. Enter your Personal Access Token
   2. Select your workspace from the list

   The CLI caches your credentials locally, so you only need to log in once per machine.

Create your first bot

1. Initialize a new bot project

   Create a new bot using the interactive CLI:

   bp init
   

   When prompted:

   • Project type: Select bot
   • Template: Choose empty-bot (default)
   • Name: Enter a name like my-first-bot

   This creates a new directory with your bot’s scaffolding.

2. Navigate to your bot directory

   cd my-first-bot
   
3. Understand the project structure

   Your bot contains two key files:

   bot.definition.ts - Defines your bot’s configuration:

   bot.definition.ts

   import { BotDefinition } from '@botpress/sdk'
   
   export default new BotDefinition({
     actions: {
       sayHello: {
         title: 'Say Hello',
         description: 'Says hello to the caller',
         input: {
           schema: z.object({ 
             name: z.string().optional() 
           }),
         },
         output: {
           schema: z.object({ 
             message: z.string() 
           }),
         },
       },
     },
   })
   

   src/index.ts - Your bot’s implementation:

   src/index.ts

   import * as bp from '.botpress'
   
   const bot = new bp.Bot({
     actions: {},
   })
   
   export default bot
   

Add bot functionality

Let’s make your bot respond to messages with a friendly greeting.

1. Add a message handler

   Edit src/index.ts to handle incoming messages:

   src/index.ts

   import * as bp from '.botpress'
   
   const bot = new bp.Bot({
     actions: {
       sayHello: async ({ input }) => {
         const name = input?.name || 'World'
         return { message: `Hello, ${name}!` }
       },
     },
   })
   
   // Listen for all incoming text messages
   bot.on.message('*', async ({ message, client, ctx }) => {
     // Call the sayHello action
     const { message: greeting } = await bot.actionHandlers.sayHello({ 
       input: {}, 
       client, 
       ctx 
     })
   
     // Send a response back to the user
     await client.createMessage({
       conversationId: message.conversationId,
       userId: ctx.botId,
       tags: {},
       type: 'text',
       payload: {
         text: greeting,
       },
     })
   })
   
   export default bot
   

   The bot.on.message('*', ...) handler listens for all incoming messages. You can also listen for specific message types like bot.on.message('text', ...).

Test your bot locally

1. Start the development server

   Run your bot in development mode:

   bp dev
   

   This command:

   • Builds your bot
   • Starts a local development server
   • Creates a tunnel to Botpress Cloud
   • Deploys a dev version of your bot
   • Watches for file changes and auto-reloads

   The bp dev command is experimental and subject to breaking changes. Always check the output for any errors.

2. Test in Botpress Cloud

   Once the dev server is running, you’ll see output like:

   Dev Bot deployed with id "abc123..." at "https://..."
   

   1. Open the Botpress Cloud dashboard
   2. Navigate to your dev bot (marked with a dev badge)
   3. Open the Emulator or Web Chat
   4. Send a message - your bot will respond with “Hello, World!”
3. Make changes and watch them reload

   The dev server automatically reloads when you save changes:

   1. Edit src/index.ts to customize the greeting
   2. Save the file
   3. The bot rebuilds automatically
   4. Test your changes in the emulator

   Press Ctrl+C in your terminal to stop the dev server.

Deploy to production

1. Deploy your bot

   When you’re ready to deploy to production:

   bp deploy
   

   This command:

   • Builds your bot for production
   • Prompts for confirmation
   • Deploys to Botpress Cloud
   • Returns a bot ID

   The first time you run bp deploy, it creates a new bot. Subsequent deploys update the existing bot.

2. Verify deployment

   After deployment, you’ll see:

   Bot deployed with id "xyz789..."
   

   Your bot is now live and ready to connect to channels like Telegram, Slack, WhatsApp, and more.

Troubleshooting

Error: Node version not supported

Botpress requires Node.js 18.0.0 or higher. Check your version:

node --version

If needed, upgrade Node.js from nodejs.org.

Error: Could not authenticate

This usually means your Personal Access Token is invalid or expired:

1. Generate a new token in Botpress Cloud
2. Run bp login again
3. Enter the new token

Dev server won't start

Common causes:

• Port already in use: The default port (8075) might be occupied. Specify a different port:

  bp dev --port 8080
  

• Build errors: Check the terminal output for TypeScript errors and fix them before running bp dev.

Changes not reflecting in the emulator

Try these steps:

1. Wait a few seconds after saving - the rebuild takes time
2. Refresh the Botpress Cloud dashboard
3. Clear your browser cache
4. Restart the dev server with Ctrl+C then bp dev

Deployment fails

Ensure you’re logged in and have the correct permissions:

bp login
bp deploy

Check that your bot.definition.ts has no validation errors.

Next steps

Add integrations

Learn how to add pre-built integrations like Slack, OpenAI, and more to your bot

Build bots

Learn about bot configuration, handlers, and advanced features

Integration hub

Browse 67+ pre-built integrations available for your bots

SDK reference

Explore the full TypeScript SDK API documentation