Botpress Insights - AI-Powered Conversation Analysis

A comprehensive Node.js tool for exporting and analyzing Botpress conversation data using Claude AI. This project helps you extract valuable insights from your chatbot conversations, identify knowledge gaps, and improve your bot's performance.

🚀 Features

• Automated Data Export: Export conversations from the last 7 days with complete message and log data
• AI-Powered Analysis: Use Claude AI to analyze conversation patterns and extract insights
• Comprehensive Reporting: Generate detailed reports covering topics, knowledge gaps, performance, and user experience
• Flexible Filtering: Filter conversations by channel, integration, log level, and more
• Beautiful Output: Colorized, formatted reports with structured recommendations
• Programmatic API: Use as a library in your own applications

📋 What It Does

This tool performs a complete analysis workflow:

1. Data Export: Fetches all conversations from the last week from your Botpress workspace
2. Data Bundling: For each conversation, it collects:
   • Complete conversation metadata
   • All messages (user and bot)
   • All runtime logs and system events
3. AI Analysis: Uses Claude AI to analyze the data and extract insights in four key areas:
   • Topics of Interest: What users are asking about most
   • Knowledge Gaps: Areas where your bot needs improvement
   • System Performance: Technical issues and reliability concerns
   • User Experience: Content effectiveness and interaction patterns
4. Report Generation: Creates structured, actionable reports with recommendations

🛠️ Installation

1. Clone the repository:

   git clone <repository-url>
   cd insights

2. Install dependencies:

   npm install

3. Set up environment variables: Create a .env file in the project root with your credentials:

   # Botpress API Configuration
   BOTPRESS_TOKEN=your_botpress_token
   BOTPRESS_BOT_ID=your_bot_id
   BOTPRESS_WORKSPACE_ID=your_workspace_id
   BOTPRESS_API_BASE_URL=https://api.botpress.cloud
   
   # Claude AI Configuration
   ANTHROPIC_API_KEY=your_anthropic_api_key
   CLAUDE_MODEL=claude-sonnet-4-0

4. Get your API keys:

   • Botpress: Get your token, bot ID, and workspace ID from your Botpress dashboard
   • Anthropic: Get your API key from Anthropic Console

🚀 Quick Start

Basic Usage

1. Export conversations:

   npm run export

2. Analyze the data:

   npm run analyze

3. View formatted results:

   npm run format-analysis data/your-analysis-file.json

Advanced Usage

Export with Filters

# Filter by channel
npm run export -- --channel webchat

# Filter by integration
npm run export -- --integration webchat

# Filter logs by level
npm run export -- --log-level error

# Custom filename
npm run export -- --filename weekly-errors.json

Analysis Options

# Analyze specific file
npm run analyze -- --file data/my-export.json

# Show summary in console
npm run analyze -- --summary

# Custom analysis filename
npm run analyze -- --filename weekly-insights.json

Preview Data

# Preview how data will be reconstructed for analysis
npm run preview

📊 Available Commands

Command	Description
npm run export	Export last week's conversations with complete data
npm run analyze	Analyze exported data with Claude AI
npm run preview	Preview data reconstruction before analysis
npm run format-analysis	Format analysis results with colors and structure
npm run help	Show export command help
npm run help-analyze	Show analysis command help

🔧 Programmatic Usage

You can also use this tool as a library in your own applications:

import { BotpressDataService, DataAnalysisService } from './src/index.js';

// Export data
const dataService = new BotpressDataService();
const exportResult = await dataService.exportLastWeekData({
  conversationFilters: { channel: 'webchat' },
  logOptions: { level: 'error' }
});

// Analyze with Claude
const analysisService = new DataAnalysisService();
const analysisResult = await analysisService.analyzeExport(exportResult.filePath);

// Access results
console.log('Export summary:', exportResult.summary);
console.log('AI insights:', analysisResult.analysis);

📁 Project Structure

insights/
├── src/
│   ├── services/
│   │   ├── botpressDataService.js    # Data export and bundling
│   │   └── dataAnalysisService.js    # Claude AI analysis
│   ├── utils/
│   │   └── BotpressClient.js         # Botpress API client
│   ├── scripts/
│   │   ├── export.js                 # Export CLI script
│   │   ├── analyze.js                # Analysis CLI script
│   │   ├── preview.js                # Data preview script
│   │   └── formatAnalysis.js         # Report formatting script
│   └── index.js                      # Main entry point
├── data/                             # Exported data and analysis results
├── package.json
└── README.md

📈 Analysis Output

The tool generates comprehensive analysis reports covering:

1. Topics of Interest

• Most frequently discussed topics
• User intent patterns
• Content effectiveness metrics

2. Knowledge Gaps

• Questions the bot couldn't answer
• Areas needing additional training data
• Missing conversation flows

3. System Performance & Reliability

• Error rates and patterns
• Performance bottlenecks
• Technical issues and recommendations

4. User Experience Signals

• Conversation flow effectiveness
• User satisfaction indicators
• Content quality assessment

Each analysis includes:

• Priority levels (High/Medium/Low) for recommendations
• Supporting evidence from actual conversations
• Actionable recommendations with specific next steps
• Token usage and cost estimates

🔍 Data Export Format

Exported data includes:

{
  "metadata": {
    "exportedAt": "2025-08-29T15:57:50.969Z",
    "timeRange": { "startDate": "...", "endDate": "..." },
    "totalConversations": 20,
    "processingTimeMs": 5103,
    "version": "1.0.0"
  },
  "conversations": [
    {
      "conversation": { /* conversation metadata */ },
      "messages": [ /* all messages */ ],
      "logs": [ /* all runtime logs */ ],
      "metadata": { /* bundling info */ },
      "stats": { /* conversation statistics */ }
    }
  ],
  "summary": { /* overall statistics */ }
}

⚙️ Configuration

Environment Variables

Variable	Description	Required
BOTPRESS_TOKEN	Your Botpress API token	Yes
BOTPRESS_BOT_ID	Your bot ID	Yes
BOTPRESS_WORKSPACE_ID	Your workspace ID	Yes
BOTPRESS_API_BASE_URL	Botpress API base URL	No (defaults to https://api.botpress.cloud)
ANTHROPIC_API_KEY	Your Anthropic API key	Yes (for analysis)
CLAUDE_MODEL	Claude model to use	No (defaults to claude-sonnet-4-0)

Export Options

const options = {
  conversationFilters: {
    channel: 'webchat',           // Filter by channel
    integrationName: 'webchat'    // Filter by integration
  },
  logOptions: {
    level: 'error'                // Filter logs by level
  },
  messageOptions: {
    // Additional message filtering options
  }
};

🚨 Troubleshooting

Common Issues

1. Authentication Errors:

   • Verify your Botpress credentials are correct
   • Check that your token has the necessary permissions

2. No Conversations Found:

   • Ensure you have conversations in the last 7 days
   • Check your date filters and timezone settings

3. Analysis Fails:

   • Verify your Anthropic API key is valid
   • Check that you have sufficient API credits
   • Ensure the export file is not corrupted

4. Memory Issues:

   • For large datasets, consider filtering by date range
   • Monitor your system memory usage during export

Getting Help

• Check the help commands: npm run help and npm run help-analyze
• Review the console output for detailed error messages
• Ensure all required environment variables are set

📝 License

ISC License

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📚 Additional Resources

• Botpress Documentation
• Botpress API Reference
• Anthropic Claude API
• Node.js Documentation

---

Note: This tool is designed for Botpress Cloud workspaces. For self-hosted Botpress instances, you may need to adjust the API endpoints and authentication methods.