Chatelope
Plugins

Parser Plugins

Import conversations from custom platforms

Parser Plugins

Parser plugins enable importing conversations from platforms not natively supported by Chatelope.

How Parsers Work

  1. User uploads an export file (ZIP, JSON, etc.)
  2. Plugin detects if it can handle the file
  3. Plugin parses the file format
  4. Plugin returns normalized conversation data
  5. Chatelope imports the conversations

Available Parsers

Official Parsers

Built into Chatelope:

  • ChatGPT
  • Claude
  • Gemini

Community Parsers

Install from the plugin directory:

ParserPlatformStatus
slack-parserSlackVerified
teams-parserMicrosoft TeamsVerified
discord-parserDiscordCommunity
telegram-parserTelegramCommunity

Using Parser Plugins

After Installation

Once installed, parsers appear in the import flow:

  1. Go to Import
  2. New platform appears in the list
  3. Select it and upload your export
  4. Parser handles the rest

Selecting Parsers

If multiple parsers can handle a file:

  1. Chatelope shows options
  2. Select the correct parser
  3. Proceed with import

Parser Settings

Configure parser behavior:

  1. Go to Settings > Plugins
  2. Find the parser plugin
  3. Click settings icon

Common settings:

  • Date format - How dates are parsed
  • Timezone - Default timezone for imports
  • Attachment handling - How to process files

Creating Parser Plugins

See Creating Plugins for the full SDK guide.

Quick Example

import { defineParser, ParsedConversation } from '@chatelope/plugin-sdk';

export default defineParser({
  id: 'my-platform-parser',
  name: 'My Platform',
  version: '1.0.0',

  // Check if this parser can handle the file
  detect: async (file) => {
    return file.name.endsWith('.json');
  },

  // Parse the file and return conversations
  parse: async (file): Promise<ParsedConversation[]> => {
    const content = await file.text();
    const data = JSON.parse(content);

    return data.conversations.map(conv => ({
      sourceId: conv.id,
      source: 'my-platform',
      title: conv.title,
      createdAt: new Date(conv.created),
      messages: conv.messages.map(msg => ({
        role: msg.type === 'user' ? 'user' : 'assistant',
        content: msg.text,
        timestamp: new Date(msg.time),
      })),
    }));
  },
});

Parser Interface

interface Parser {
  id: string;
  name: string;
  version: string;
  icon?: string;

  detect(file: File): Promise<boolean>;
  parse(file: File): Promise<ParsedConversation[]>;

  // Optional hooks
  onProgress?(percent: number): void;
  validateExport?(file: File): Promise<ValidationResult>;
}

Conversation Schema

interface ParsedConversation {
  sourceId: string;
  source: string;
  title: string;
  createdAt: Date;
  updatedAt?: Date;
  messages: ParsedMessage[];
  metadata?: Record<string, unknown>;
}

interface ParsedMessage {
  role: 'user' | 'assistant' | 'system';
  content: string;
  timestamp?: Date;
  attachments?: ParsedAttachment[];
}

Testing Parsers

Local Testing

Test your parser locally:

  1. Install plugin in development mode
  2. Import sample exports
  3. Verify conversation data

Sample Data

Create test exports:

import { createTestExport } from '@chatelope/plugin-sdk/testing';

const testFile = createTestExport({
  conversations: [
    { title: 'Test', messages: [...] }
  ]
});

Best Practices

  1. Handle errors gracefully - Invalid files should fail cleanly
  2. Support large files - Use streaming for big exports
  3. Preserve metadata - Keep platform-specific info
  4. Document format - Explain what exports you support
  5. Version your parser - Handle format changes over time

On this page