Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/botpress/botpress/llms.txt

Use this file to discover all available pages before exploring further.

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 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

Botpress requires Node.js 18.0.0 or higher. Check your version:
node --version
If needed, upgrade Node.js from nodejs.org.
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
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.
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
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