Crisp Conversation Exporter

A modern, feature-rich Node.js tool for extracting and exporting Crisp chat conversations with support for bulk extraction, configuration files, and multiple output formats.

✨ Features

• 🎯 Extract specific conversations by session ID with high precision
• 📦 Bulk processing with built-in rate limiting and error handling
• ⚙️ Configuration-based extraction - set up once, run anywhere
• 🖥️ Command-line interface with intuitive options and help
• 📝 Multiple message types - text, files, forms, events, private notes
• 🔄 Interactive mode as fallback when configuration is incomplete
• 📊 Rich metadata - conversation details, participants, timestamps
• 🎨 Human-readable exports with Unicode emojis and clear formatting
• 🏗️ Built on official API - uses crisp-api v9.10.0
• 💻 TypeScript support - built-in type definitions
• 🧪 Well tested - comprehensive test suite with mocking

🚀 Quick Start

Installation

# Install globally for CLI usage
npm install -g crisp-conversation-exporter

# Or install locally in your project
npm install crisp-conversation-exporter

CLI Usage

# Quick start - uses config file
crisp-export

# Interactive mode
crisp-export --interactive

# Use production config
crisp-export --config production.json

# Override specific settings
crisp-export --website "your-website-id" --output "./my-exports"

Programmatic Usage

const ConversationExtractor = require('crisp-conversation-exporter');

const extractor = new ConversationExtractor('your-api-id', 'your-api-key');

// Extract a single conversation
const result = await extractor.extractSession('website-id', 'session-id');
console.log(result.conversation);

// Extract multiple conversations
const sessions = ['session-1', 'session-2', 'session-3'];
const results = await extractor.exportSessionsToFiles('website-id', sessions, {
  outputDir: './exports',
  includeMetadata: true,
  includePrivateNotes: false,
});

📖 Table of Contents

• Installation
• Configuration
• Usage Examples
• API Reference
• CLI Options
• Export Format
• Contributing
• License

🔧 Installation

Prerequisites

• Node.js v16.0.0 or higher
• npm v8.0.0 or higher
• Crisp account with API access

Global Installation (Recommended for CLI)

npm install -g crisp-conversation-exporter

After global installation, you can use the crisp-export command from anywhere.

Local Installation

# For use in a project
npm install crisp-conversation-exporter

# For development
npm install --save-dev crisp-conversation-exporter

From Source

git clone https://github.com/your-username/crisp-conversation-exporter.git
cd crisp-conversation-exporter
npm install
npm link  # Makes crisp-export available globally

⚙️ Configuration

API Credentials

Get your credentials from Crisp Dashboard:

1. Go to Settings → Account → API Keys
2. Create a Plugin-tier API key with these scopes:
   • website:conversation:sessions (read)
   • website:conversation:messages (read)

Configuration Files

The tool supports multiple configuration files:

• config/development.json - Default for development
• config/production.json - Production configuration
• config/example.json - Template with examples

Basic Configuration

{
  "CRISP_IDENTIFIER": "your-api-identifier",
  "CRISP_KEY": "your-api-key",

  "extraction": {
    "websiteId": "8c842203-7ed8-4e29-a608-7cf78a7d2fcc",
    "sessionIds": ["session_abc123", "session_def456", "session_ghi789"],
    "outputDir": "./exports",
    "options": {
      "includeMetadata": true,
      "includePrivateNotes": false,
      "dateFormat": "iso"
    }
  }
}

Environment Variables

# Alternative to config files
export CRISP_IDENTIFIER="your-api-identifier"
export CRISP_KEY="your-api-key"

Finding IDs

Website ID

Found in your Crisp dashboard URL:

https://app.crisp.chat/website/{website-id}/

Session IDs

Found in conversation URLs:

https://app.crisp.chat/website/{website-id}/conversation/{session-id}

💡 Usage Examples

1. Configuration-Based (Recommended)

Set up your config/development.json:

{
  "CRISP_IDENTIFIER": "your-api-id",
  "CRISP_KEY": "your-api-key",
  "extraction": {
    "websiteId": "website-123",
    "sessionIds": ["session-1", "session-2"],
    "outputDir": "./exports"
  }
}

Run extraction:

crisp-export

2. Interactive Mode

crisp-export --interactive

The tool will prompt for:

• API credentials (if not in config)
• Website ID
• Session IDs
• Export options

3. Command Line Overrides

# Use different config file
crisp-export --config production.json

# Override website ID
crisp-export --website "different-website-id"

# Custom output directory
crisp-export --output "./custom-exports"

# Combine options
crisp-export --config prod.json --output "./backup" --website "site-123"

4. Programmatic Usage

Basic Extraction

const ConversationExtractor = require('crisp-conversation-exporter');

async function extractConversations() {
  const extractor = new ConversationExtractor('your-api-identifier', 'your-api-key');

  try {
    // Extract single session
    const result = await extractor.extractSession('website-id', 'session-id');

    console.log(`Extracted ${result.messageCount} messages`);
    console.log(result.conversation);
  } catch (error) {
    console.error('Extraction failed:', error.message);
  }
}

extractConversations();

Bulk Extraction

const ConversationExtractor = require('crisp-conversation-exporter');

async function bulkExtract() {
  const extractor = new ConversationExtractor(process.env.CRISP_IDENTIFIER, process.env.CRISP_KEY);

  const sessionIds = ['session_abc123', 'session_def456', 'session_ghi789'];

  const results = await extractor.exportSessionsToFiles('your-website-id', sessionIds, {
    outputDir: './exports',
    includeMetadata: true,
    includePrivateNotes: true,
  });

  console.log(`Successfully exported ${results.filter(r => r.success).length} conversations`);
}

bulkExtract();

Advanced Usage with Error Handling

const ConversationExtractor = require('crisp-conversation-exporter');
const fs = require('fs').promises;

async function advancedExtraction() {
  const extractor = new ConversationExtractor('your-api-identifier', 'your-api-key');

  const sessions = ['session-1', 'session-2', 'session-3'];
  const results = [];

  for (const sessionId of sessions) {
    try {
      console.log(`Processing ${sessionId}...`);

      const result = await extractor.extractSession('website-id', sessionId, {
        includeMetadata: true,
        includePrivateNotes: false,
      });

      // Save with custom filename
      const filename = `conversation-${sessionId}-${Date.now()}.txt`;
      await fs.writeFile(filename, result.conversation);

      results.push({ sessionId, success: true, filename });

      // Rate limiting
      await extractor.delay(1000);
    } catch (error) {
      console.error(`Failed to extract ${sessionId}:`, error.message);
      results.push({ sessionId, success: false, error: error.message });
    }
  }

  return results;
}

📚 API Reference

ConversationExtractor

Constructor

new ConversationExtractor(apiIdentifier, apiKey);

• apiIdentifier (string): Your Crisp API identifier
• apiKey (string): Your Crisp API key

Methods

extractSession(websiteId, sessionId, options?)

Extract a single conversation session.

Parameters:

• websiteId (string): Crisp website ID
• sessionId (string): Conversation session ID
• options (object, optional): Export options

Returns: Promise<Object>

{
  sessionId: 'session_123',
  websiteId: 'website_456',
  messageCount: 42,
  conversation: 'formatted conversation text',
  metadata: { /* conversation metadata */ }
}

extractSessions(websiteId, sessionIds, options?)

Extract multiple conversation sessions.

Parameters:

• websiteId (string): Crisp website ID
• sessionIds (string[]): Array of session IDs
• options (object, optional): Export options

Returns: Promise<Object[]>

exportSessionsToFiles(websiteId, sessionIds, options?)

Extract sessions and save to files.

Parameters:

• websiteId (string): Crisp website ID
• sessionIds (string[]): Array of session IDs
• options (object, optional): Export options with outputDir

Returns: Promise<Object[]>

saveToFile(conversationData, outputDir?)

Save conversation data to file.

Parameters:

• conversationData (object): Result from extractSession
• outputDir (string, optional): Output directory (default: './exports')

Returns: Promise<string> - File path

Options Object

{
  includeMetadata: true,        // Include conversation metadata
  includePrivateNotes: false,   // Include private operator notes
  dateFormat: 'iso',           // Date format ('iso' | 'locale')
  outputDir: './exports'       // Output directory for files
}

🖥️ CLI Options

crisp-export [options]

| Option | Description | Example | | ----------------- | ------------------------- | -------------------------- | | --config <file> | Use specific config file | --config production.json | | --website <id> | Override website ID | --website "abc123" | | --output <dir> | Override output directory | --output "./exports" | | --interactive | Force interactive mode | --interactive | | --version | Show version number | --version | | --help | Show help message | --help |

Examples

# Basic usage
crisp-export

# Production configuration
crisp-export --config production.json

# Override settings
crisp-export --website "site-123" --output "./backup"

# Interactive mode
crisp-export --interactive

# Show help
crisp-export --help

📄 Export Format

Exported conversations include:

Metadata Section (optional)

============================================================
CONVERSATION EXPORT
============================================================
Session ID: session_abc123
Website ID: website_xyz789
Visitor: John Doe
Email: [email protected]
Status: resolved
Created: 2025-01-15 10:30:00
Updated: 2025-01-15 11:45:00
Messages: 12
============================================================

Message Section

--- 👤 VISITOR: John Doe ---
[2025-01-15 10:30:15] Hello, I need help with my order

--- 👨‍💼 OPERATOR: Support Agent ---
[2025-01-15 10:31:02] Hi John! I'd be happy to help you with your order.
[2025-01-15 10:31:15] 📎 File: invoice.pdf (https://files.crisp.chat/...)

--- 👤 VISITOR: John Doe ---
[2025-01-15 10:32:00] Perfect, thank you!

Supported Message Types

• Text messages - Regular conversation text
• File attachments - Documents, images, etc.
• Form responses - Customer form submissions
• Picker choices - Multiple choice selections
• Events - System events and notifications
• Private notes - Internal operator notes (optional)
• Audio messages - Voice recordings

🧪 Testing

Run the test suite:

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm test -- --coverage

# Run linting
npm run lint

# Format code
npm run format

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Start for Contributors

# Fork and clone the repository
git clone https://github.com/your-username/crisp-conversation-exporter.git
cd crisp-conversation-exporter

# Install dependencies
npm install

# Copy example config
cp config/example.json config/development.json

# Add your Crisp API credentials to config/development.json

# Run tests
npm test

# Run linting
npm run lint

Development Scripts

npm run dev          # Start with nodemon
npm run lint         # Fix linting issues
npm run lint:check   # Check linting
npm run format       # Format code
npm run format:check # Check formatting
npm test             # Run tests
npm run test:watch   # Run tests in watch mode

📋 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Crisp for providing the excellent customer support platform
• crisp-api - Official Crisp API package
• All contributors who help improve this project

📞 Support

• Documentation: You're reading it! 📖
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Crisp API Docs: Official API Documentation

🔄 Changelog

See CHANGELOG.md for a detailed history of changes.

Made with ❤️ for the Crisp community

If this project helped you, please consider giving it a ⭐ on GitHub!