Botpress Migration Guide

Migrating chatbots from Botpress to General Bots.

Overview

Botpress is an open-source chatbot platform with visual flow builder and NLU. General Bots provides a simpler approach using LLM-based understanding and BASIC scripting, with integrated productivity features and native multi-channel support.

Why Migrate

Concept Mapping

Flow Migration

Botpress Flow Structure

# Botpress flow (simplified)
nodes:
  - id: entry
    type: standard
    next: ask_name
  - id: ask_name
    type: say_something
    content: "What's your name?"
    next: capture_name
  - id: capture_name
    type: listen
    slot: name
    next: greet
  - id: greet
    type: say_something
    content: "Hello {{name}}!"

General Bots Equivalent

' Simple and readable
TALK "What's your name?"
HEAR name AS NAME
TALK "Hello " + name + "!"

Migration Examples

Simple Welcome Flow

Botpress:

• Entry node → Say “Welcome” → Listen for intent → Route to sub-flow

General Bots:

USE KB "help-docs"

SET CONTEXT "You are a friendly assistant for Acme Corp."

TALK "Welcome! How can I help you today?"
HEAR question
answer = LLM question
TALK answer

Lead Capture Flow

Botpress:

Entry → Ask Name → Capture Slot → Ask Email → Capture Slot → 
Ask Company → Capture Slot → Save to CRM → Thank You

General Bots:

' lead-capture.bas
TALK "I'd love to learn more about you!"

TALK "What's your name?"
HEAR name AS NAME

TALK "And your work email?"
HEAR email AS EMAIL

TALK "What company are you with?"
HEAR company

' Save directly - no external action needed
INSERT "leads", #{
    name: name,
    email: email,
    company: company,
    source: "chatbot",
    created_at: NOW()
}

' Score the lead
score = SCORE LEAD #{name: name, email: email, company: company}

IF score.status = "hot" THEN
    SEND MAIL TO "sales@company.com" SUBJECT "Hot Lead" BODY "New lead: " + name + " from " + company
END IF

TALK "Thanks, " + name + "! Someone from our team will be in touch soon."

FAQ Bot with Fallback

Botpress:

• NLU intent matching
• Knowledge base query
• Fallback to human

General Bots:

USE KB "faq"
USE KB "product-docs"

SET CONTEXT "Answer customer questions helpfully. If you cannot answer confidently, offer to connect with a human."

TALK "What can I help you with?"
HEAR question

answer = LLM question

' Check if confident answer
IF CONTAINS(LOWER(answer), "i don't") OR CONTAINS(LOWER(answer), "not sure") THEN
    TALK "I'm not certain about that. Would you like to speak with someone?"
    HEAR wants_human AS BOOLEAN
    IF wants_human THEN
        CREATE TASK "Customer inquiry: " + question
        SEND MAIL TO "support@company.com" SUBJECT "Chat Handoff" BODY question
        TALK "I've notified our team. Someone will reach out shortly."
    END IF
ELSE
    TALK answer
END IF

Multi-Step Booking Flow

Botpress:

Select Service → Choose Date → Choose Time → Confirm → Book
(Multiple nodes with slot filling)

General Bots:

TALK "Let's book your appointment."

TALK "What service do you need?"
HEAR service AS "Consultation", "Checkup", "Follow-up", "Emergency"

TALK "What date works for you?"
HEAR appt_date AS DATE

TALK "What time?"
HEAR appt_time AS HOUR

' Check availability
available = GET "https://calendar.api/available?date=" + appt_date + "&time=" + appt_time

IF available THEN
    BOOK service AT appt_date + " " + appt_time
    TALK "Your " + service + " is confirmed for " + FORMAT(appt_date, "MMMM d") + " at " + appt_time
ELSE
    TALK "That slot isn't available. Would " + available.next + " work instead?"
END IF

NLU Migration

Botpress Intents

# Botpress intent definition
intents:
  - name: order_status
    utterances:
      - where is my order
      - track my order
      - order status
      - what happened to my order

General Bots Approach

No intent definition needed. The LLM understands naturally:

USE KB "order-help"
SET CONTEXT "Help customers with their orders."

TALK "How can I help with your order?"
HEAR question

' LLM understands "where is my order", "track order", etc.
' without explicit training
answer = LLM question

Entity Extraction

Botpress:

entities:
  - name: order_number
    type: pattern
    pattern: "ORD-[0-9]{6}"

General Bots:

TALK "What's your order number?"
HEAR order_number

' Or with validation pattern
IF NOT MATCH(order_number, "ORD-[0-9]{6}") THEN
    TALK "Please enter a valid order number (e.g., ORD-123456)"
    HEAR order_number
END IF

Actions Migration

Botpress Custom Actions

// Botpress action
const checkOrderStatus = async (orderId) => {
  const response = await axios.get(`/api/orders/${orderId}`);
  return response.data.status;
};

General Bots

' Direct API call - no separate action file
order = GET "https://api.company.com/orders/" + order_id
TALK "Your order status is: " + order.status

Hooks Migration

Botpress Hooks

// before_incoming_middleware hook
bp.events.on('before_incoming_middleware', async (event) => {
  // Custom logic
});

General Bots Triggers

' Event-driven triggers
ON "message:received"
    ' Log all messages
    INSERT "message_log", #{
        content: params.content,
        user: params.user_id,
        timestamp: NOW()
    }
END ON

ON "session:started"
    ' Track new sessions
    INSERT "sessions", #{
        id: params.session_id,
        started: NOW()
    }
END ON

Content Types

Botpress Content

// Botpress content types
{
  type: 'builtin_card',
  title: 'Product',
  image: 'product.jpg',
  actions: [{ title: 'Buy', action: 'buy' }]
}

General Bots

' Text
TALK "Hello!"

' Image
TALK IMAGE "/products/featured.jpg"

' File
TALK FILE "/docs/brochure.pdf"

' Suggestions
ADD SUGGESTION "View Products"
ADD SUGGESTION "Contact Sales"
ADD SUGGESTION "Get Help"
TALK "What would you like to do?"

Knowledge Base Migration

Botpress Q&A

Limited to question-answer pairs.

General Bots RAG

Full document support:

my-bot.gbkb/
├── products/
│   ├── catalog.pdf
│   ├── specs.xlsx
│   └── pricing.md
├── support/
│   ├── faq.md
│   └── troubleshooting.md
└── company/
    ├── about.md
    └── policies.pdf

USE KB "products"
USE KB "support"
USE KB "company"

answer = LLM customer_question

Channel Migration

Botpress Channels

Requires separate connector configuration for each channel.

General Bots

Native multi-channel with same code:

' Works everywhere: Web, WhatsApp, Teams, Slack, Telegram, SMS
TALK "How can I help?"
HEAR question
answer = LLM question
TALK answer

Database and State

Botpress State

// Botpress user state
event.state.user.name = 'John';
event.state.session.orderId = '12345';

General Bots

' Session/conversation memory
SET BOT MEMORY "customer_name", name
SET BOT MEMORY "current_order", order_id

' Retrieve
name = GET BOT MEMORY "customer_name"

' Persistent storage
INSERT "customers", #{name: name, email: email}
customer = FIND "customers", "email = '" + email + "'"

What You Gain

Simpler Development: BASIC scripts are more readable than visual flows with scattered code.

No NLU Training: LLM understands variations without explicit intent training.

Native AI: Full LLM integration without plugins.

Productivity Suite: Built-in email, calendar, files, and tasks.

Unified Platform: Chat, automation, and productivity in one system.

True Multi-Channel: Same code works everywhere without channel-specific configuration.

Migration Checklist

Pre-Migration

• Export Botpress flows and content
• Document intents and entities
• List custom actions
• Export Q&A/knowledge base
• Note channel configurations

Migration

• Set up General Bots environment
• Create BASIC scripts for main flows
• Build knowledge base structure
• Implement entity validation
• Configure channels
• Test all flows

Post-Migration

• Compare conversation quality
• Verify integrations
• Train team
• Redirect channel endpoints
• Decommission Botpress

See Also

• Dialog Basics - Script fundamentals
• HEAR Keyword - Input validation
• Knowledge Base - RAG configuration
• Platform Comparison - Full comparison