Botpress Chatbot Builder: How to Build a Bot in Botpress Studio

What a new Studio bot already contains

Botpress Studio is the browser-based visual builder inside Botpress, and it is included on every plan, Free included. You do not start from a blank canvas. A new bot opens with a Main Workflow that holds a Start Node, an Autonomous Node and an End Node, and that workflow runs the moment a user starts a conversation ^[1]. The Autonomous Node lets a language model decide what to say and which tools to call, and it already carries a Search Knowledge card. So a working chatbot is mostly instructions plus knowledge. Structure comes later.

The other building blocks are the ones Botpress lists as Studio's core concepts: workflows, nodes, cards, knowledge bases, tables and variables. Every bot also gets built-in Error, Timeout and Conversation End workflows next to Main. Code is optional, and the docs say you can use none at all. One sizing fact matters early. On Free you get 3 AI agents and 100 conversations, and Botpress counts emulator conversations toward that number the same as live ones. Plan your testing around it.

When Botpress Viber is the shorter road

Botpress Viber is the other no-code builder on the same plan and price list. It has no nodes, cards or visual workflows, and it needs no TypeScript or ADK project. You describe the agent to the builder agent, Vibe, test it in Preview, then publish it and embed it as webchat. Behavior sits in layers: Instructions that always apply, Playbooks for repeatable procedures, and Escalation for handoff, which is off by default. Pick Botpress Viber for a quick agent built on FAQs and tools. Pick Studio when you need fixed paths, captured data or code at specific steps.

Stage 1: start from a template or a prompt, then write the instructions

Botpress's getting-started guide sets out the opening moves: create the project from a template, set the agent's instructions and identity, add a knowledge base, then publish to get a shareable link. That link is already the live, published bot (see Stage 4). The Studio feature page adds a second door, building from a prompt. Either way, the core of the bot is the prompt. Botpress defines an AI agent as a bot that follows instructions, edited in Studio and checked in the emulator. Write them like a job description. Say who the agent serves, what it may answer and when it should pass a user to a person.

Model choice comes next. Bot Settings hold separate default models for fast, best, autonomous and RAG work, plus a fallback used when a preferred model is unavailable, and each Autonomous Node can override its response and RAG models. Do not go cheap here. Botpress recommends a high-performing model for Autonomous Nodes, roughly GPT-4.1 class, because smaller models may truncate the tool definitions. The same settings hold the inactivity timeout, from 0 (never) up to 1,440 minutes, and a node repetition limit of at most 10 passes before an error fires. You can also pick the LLMz version; Botpress recommends the latest stable one.

Stage 2: give the agent knowledge and a memory

Every new agent comes with a default Knowledge Base that is empty. Fill it with websites, documents, tables, rich text, web search or content from integrations such as Notion and Google Drive. Documents can be PDF, HTML, TXT, DOC, DOCX or Markdown, up to 50 MB each, and they lose styling and images on the way in. Because the default Autonomous Node already searches all knowledge bases, a new answer is available without extra wiring. Searching every base costs more tokens and latency than pointing at one. Our Botpress knowledge base guide covers sources, recrawls and storage.

Variables are where many first bots go quiet. By default the Autonomous Node cannot read or change a variable; you grant access per variable and tick Allow write access if it should update the value ^[2]. New variables default to Workflow scope and reset when the workflow ends. Switch one to User scope and the bot remembers it across conversations. Secrets belong in configuration variables, which are encrypted and hidden from the Autonomous Node. One trap remains. Configuration values set in Studio apply only to the emulator, and production values are set in the Dashboard.

Stage 3: add fixed paths with Standard Nodes, cards and code

The Autonomous Node never transitions out; it answers in a loop. When a step must run the same way every time, place a Standard Node. Standard Nodes run their cards in order and use no AI by default, and the two node types mix freely, for example a hard-coded greeting followed by the AI. Cards do the work. Capture Information asks for a value and switches to a dropdown above five choices; its File Upload type needs file upload enabled in the webchat settings. AI Transition sorts user text into categories without training phrases, replacing the deprecated Intent card. Query Knowledge Bases pulls an answer and citations into variables mid-workflow.

Code takes over when cards run out. Execute Code cards run JavaScript inside a node, and AI can write that code for you. Actions are reusable TypeScript functions that only Autonomous Nodes can call, generated from a prompt or written by hand, and Hooks run custom code too. The editor ships with Axios, Lodash, Luxon, the Botpress client, Zui and Zai preinstalled. External libraries cannot be imported. Keep stored data lean as well: Botpress enforces a 128 KB limit per bot state, and an LLM call times out after 90 seconds. Exceeding the state limit logs errors and slows responses.

Studio also carries built-in helper agents that run in a fixed order. The Personality Agent rewrites every reply in the tone you describe, which saves rewriting each message card. The Policy Agent enforces business rules, such as banned words or not discussing competitors. The Translator Agent detects the user's language on the first message, and the Vision Agent reads text from incoming images and describes them. The Summary Agent condenses a conversation into a summary and transcript a human can pick up. None of them needs code. Turn on only the ones your bot needs.

Stage 4: test in the emulator, knowing what it costs

The emulator shows every step the agent runs during a chat, including knowledge base lookups and AI tasks, which makes it the place to debug instructions and variable access. Emulator conversations are not saved. They still count. Botpress's pricing FAQ counts emulator conversations toward your conversation quota the same as live ones ^[3], and the AI operations in those tests draw on your AI usage. A conversation is any exchange with at least two end-user messages in the billing month.

On Free, a long testing session eats into the 100 conversations, and Free has no top-ups or overages to extend them; at the limit, the webchat shows «Quota exceeded». On Plus, at $150 a month billed annually or $189 a month billed monthly, the quota is 250 conversations a month. Once tests and live chats reach 95% of that quota, Botpress adds a pack of 100 extra conversations automatically, at $65 per pack, billed each month the pack stays on; this auto-recharge cannot be turned off, and the pack keeps billing until you remove it in billing settings, as our Botpress pricing guide explains.

Two other test behaviors trip people up. The Share button gives you a hosted webchat that is already the production bot, so those conversations are saved and behave like live traffic. Do not hand that link around as a sandbox. And the Conversation Started trigger, used for welcome messages, does not work in the emulator, so check a greeting on a real channel. Feedback you save in the emulator goes into the preinstalled Improvement integration, which keeps it in a Feedback table the bot reads from when it applies corrections.

Stage 5: publish, keep versions, and pick a channel

Publishing is what turns channels on. Integrations such as WhatsApp or Telegram start working once they are configured and the bot is published. Every publish creates a Version automatically, and you can also save one by hand. Reverting overwrites the current bot, and Botpress cannot restore a lost or overwritten Version . That makes a manual Version before any large edit cheap insurance. Expect no shortcut if you are moving an existing chatbot. Botpress has no automated import tool, so older bots are rebuilt by hand.

For a website, webchat is built in on every plan. With a published bot, the Studio embed code goes into the head of the page's HTML, and later bot changes go live without touching the script. Sites on an older snippet need an updated one for webchat v5. Styling, white-label options and platform installs are in our Botpress website chatbot guide. WhatsApp is also on every plan, Free included; it needs a Facebook account and Meta's business verification before the bot can send, as the Botpress WhatsApp chatbot guide explains.

How far Studio takes a first-time builder

Studio gets a first chatbot answering from your own documents with little effort, because the default Autonomous Node and the empty knowledge base arrive already connected. The real work sits in three places: instructions precise enough for the model, variable access that is off until you grant it, and Standard Nodes for steps that must not improvise. Budget emulator sessions against the conversation quota, save Versions before big changes, and treat the share link as production. If that feels like more structure than your agent needs, Botpress Viber builds one from a description on the same plan.