Opening Botpress Studio for the first time feels great for about ninety seconds. Then the blank canvas wins, and you start dragging boxes around hoping something coherent appears. The fix isn’t more features. It’s picking one small job, scripting it on paper, and building it in a specific order. That’s what this guide does, using a real example you can copy almost line for line.
The bot we’re going to build
Northbound Coffee is a fictional subscription roastery with 4,000 subscribers and two support staff drowning in the same three questions: where is my order, can I change the grind, and how do I skip a delivery. That’s the entire scope. No billing changes. No refunds. Anything outside those three routes goes straight to a human.
Scope matters more than cleverness here. A bot that handles three things reliably beats a bot that half-handles fifteen, and you’ll ship it before lunch.
Step 1: Get the CLI running on your machine
You don’t have to build in the cloud editor, and most experienced teams don’t. Install Node 18 or newer, then pull down the Botpress CLI:
- npm install -g @botpress/cli to get the command line tool
- bp login with a personal access token from your workspace
- bp init inside an empty folder to scaffold a bot project
- bp deploy when you’re ready to push it live
Everything lives as files in a folder, which means Git history, code review, and no more clicking through a UI to find out who changed the welcome message in March. If you’re weighing up platforms, this file-based workflow is a big part of why developers are choosing this open-source chatbot builder over closed alternatives.
Step 2: Write the conversation before you touch the editor
Open a text file and type the exchange out as a transcript. Real wording, real user language, typos included.
User: hey where’s my order
Bot: Happy to check. What’s your order number? It starts with NB-
User: nb-40218
Bot: That one shipped Tuesday and is out for delivery today. Want me to do anything else with it?
User: actually can you change it to espresso grind
Bot: Done. Grind updated to espresso for this shipment. You’ll get a confirmation email within a few minutes.
Notice what the script reveals: you need one piece of information (order number), one API call, one confirmation, and an off-ramp. That’s four nodes. Most people who skip this step build eleven.
Step 3: Turn the script into a flow
Create an order-status flow and rebuild the transcript as nodes. Start with the trigger, then a Capture Information card for the order number with a validation rule like NB-[0-9]{5}. When validation fails, loop back with a friendlier message rather than dead-ending.
Next comes an Execute Code card that calls your order API, stores the response in a variable, and writes the formatted status. Then a Choice card with three buttons: change the grind, skip the next delivery, talk to a human.
Cards you’ll reach for constantly
- Say for plain messages and variable interpolation
- Capture Information when you need structured input
- Choice for anything with two or three obvious paths
- Execute Code for API calls, math, and data cleanup
- Knowledge Base answer for questions you didn’t script
Name every node as you go. Six months from now, node-47 tells you nothing, while capture-order-number-retry-2 tells you exactly where to look when something breaks.
Step 4: Teach it the questions you didn’t script
You will never guess every phrasing. The knowledge base covers that gap. Upload your shipping policy, returns page, roast schedule, and the twelve support emails your team keeps rewriting. Turn on web search if your help centre is public.
The important detail is testing paraphrases, not the source text. If your document says subscription hold and your customer types can I pause it for a month, you want the bot to connect those. Query the knowledge base with five different phrasings of each policy and read the answers it generates. Anything vague or wrong gets rewritten in the source document, not patched in the bot.
Step 5: Break your own bot on purpose
Run the emulator and be a hostile user for ten minutes. Try all of these:
- An order number with lowercase letters and a missing digit
- A question about refunds, which you deliberately didn’t build
- Three messages in one turn: hi, I need to change my order, it’s late
- A reply of just ok or ? when the bot asks for input
- The human handoff, twice in a row, to check nothing crashes on the second pass
Watch for raw variable names leaking into replies. An undefined appearing mid-sentence is the fastest way to lose a customer’s trust, and it almost always means an API call failed silently and nothing caught it.
Step 6: Deploy it, then decide where it lives
One bp deploy gets you a hosted bot with logging and analytics attached. If your legal team needs order data to stay inside your own network, the open-source route lets you self-host so your data never leaves your infrastructure — same flows, your servers, your rules. Pick based on your compliance reality rather than convenience, because migrating later is annoying.
Connect the channels you actually use. For Northbound, that’s the website widget plus WhatsApp. Skip the rest until someone asks.
Step 7: Read the transcripts a week later
Analytics dashboards are fine, but transcripts teach you more. Look at three numbers first: how many conversations finished without a human, how many hit the fallback, and where people dropped off mid-flow.
For Northbound, the first week showed 61 percent containment, with most handoffs happening right after the grind change. The bot was confirming the change before the API responded, so users clicked away before seeing the success message. A two-second delay card and a clearer confirmation fixed it. That’s a five-minute change worth roughly forty handoffs a week.
Mistakes that cost people a weekend
- Building thirty intents when a knowledge base and three flows would do
- Hardcoding API keys inside flow code instead of using environment secrets
- Forgetting a confirmation step before destructive actions like cancellations
- Writing error messages that say invalid input instead of showing an example
- Skipping the human handoff because ‘the bot should handle it’
The last one matters most. A bot that escalates cleanly at the right moment feels smarter than one that traps people in a loop, even if its underlying model is weaker.
Where to get unstuck
You will hit something undocumented, usually around authentication or a channel-specific webhook. The Botpress community is where most of those answers already exist, often from someone who solved the exact problem last month. Search before you post, then post with your flow logs attached.
Start with the coffee-order bot. Ship it to ten real users this week, watch what breaks, and let that shape the second version. The bot you learn to build in an afternoon will be more useful than the elaborate one you spend a month designing and never finish.