ChatLab Standard Format Specification v0.0.1

ChatLab defines a standardized data exchange format for chat records, supporting unified import and analysis across multiple platforms.

As long as you convert your chat records to this format, they can be parsed by ChatLab and analyzed with its full capabilities.

Note

This format specification is still in early development. Some fields and structures may change in future versions.

Overview

Supported File Formats

Format	Extension	Use Case
JSON	.json	Small to medium records (<1M messages), clear structure
JSONL	.jsonl	Large-scale records (>1M messages), streaming, constant memory

Format Comparison

Feature	JSON	JSONL
Memory Usage	Loads entire structure	Line-by-line, constant (~100MB)
File Size Limit	~1GB (depends on memory)	No practical limit
Append Writing	Requires full rewrite	✅ Direct append
Error Recovery	Single error breaks file	Can skip bad lines
Readability	⭐⭐⭐ Easy to read	⭐⭐ One record per line
Recommended For	Small/medium (<1M)	Large records (>1M)

Quick Start

Here's a minimal ChatLab format example with only required fields:

{
  "chatlab": {
    "version": "0.0.1",
    "exportedAt": 1703001600
  },
  "meta": {
    "name": "My Group Chat",
    "platform": "discord",
    "type": "group"
  },
  "members": [
    {
      "platformId": "123456",
      "accountName": "John"
    }
  ],
  "messages": [
    {
      "sender": "123456",
      "accountName": "John",
      "timestamp": 1703001600,
      "type": 0,
      "content": "Hello everyone!"
    }
  ]
}

---

JSON Format Details

File Header (chatlab)

Field	Type	Required	Description
version	string	✅	Format version, currently "0.0.1"
exportedAt	number	✅	Export time (Unix timestamp in seconds)
generator	string	-	Generator tool name
description	string	-	Description

Metadata (meta)

Field	Type	Required	Description
name	string	✅	Group or conversation name
platform	string	✅	Platform: qq / wechat / discord / whatsapp etc.
type	string	✅	Chat type: group / private
groupId	string	-	Group ID (group chat only)
groupAvatar	string	-	Group avatar (Data URL format)

Members (members)

Field	Type	Required	Description
platformId	string	✅	User unique identifier
accountName	string	✅	Account name
groupNickname	string	-	Group nickname (group only)
aliases	string[]	-	User-defined aliases
avatar	string	-	User avatar (Data URL format)

Messages (messages)

Field	Type	Required	Description
sender	string	✅	Sender's platformId
accountName	string	✅	Account name at send time
groupNickname	string	-	Group nickname at send time
timestamp	number	✅	Unix timestamp in seconds
type	number	✅	Message type (see table below)
content	string | null	✅	Content (null for non-text messages)

---

Message Type Reference

Tip

If your chat records contain other special types that need support, please submit an issue and we'll evaluate adding them.

Basic Message Types (0-19)

Value	Name	Description
0	TEXT	Text message
1	IMAGE	Image
2	VOICE	Voice message
3	VIDEO	Video
4	FILE	File
5	EMOJI	Sticker/Emoji
7	LINK	Link/Card
8	LOCATION	Location

Interactive Message Types (20-39)

Value	Name	Description
20	RED_PACKET	Red packet (gift money)
21	TRANSFER	Money transfer
22	POKE	Poke/Nudge
23	CALL	Voice/Video call
24	SHARE	Share (music, mini-program)
25	REPLY	Quote reply
26	FORWARD	Forwarded message
27	CONTACT	Contact card

System Message Types (80+)

Value	Name	Description
80	SYSTEM	System message (join/leave/etc)
81	RECALL	Recalled message
99	OTHER	Other/Unknown

Avatar Format

Avatar fields avatar and groupAvatar use Data URL format:

data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...

Supported image formats:

• image/jpeg - JPEG format (recommended, smaller size)
• image/png - PNG format
• image/gif - GIF format
• image/webp - WebP format

Suggestion

Compress avatars to 100×100 pixels or smaller when exporting to reduce file size.

Complete Examples

Group Chat Example (with optional fields)

{
  "chatlab": {
    "version": "0.0.1",
    "exportedAt": 1703001600,
    "generator": "My Converter Tool",
    "description": "2024 Tech Discussion Group Backup"
  },
  "meta": {
    "name": "Tech Discussion Group",
    "platform": "discord",
    "type": "group",
    "groupId": "38988428513",
    "groupAvatar": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
  },
  "members": [
    {
      "platformId": "abc123",
      "accountName": "John",
      "groupNickname": "Admin-John",
      "avatar": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
    },
    {
      "platformId": "def456",
      "accountName": "Alice",
      "groupNickname": "Moderator",
      "avatar": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
    }
  ],
  "messages": [
    {
      "sender": "abc123",
      "accountName": "John",
      "groupNickname": "Admin-John",
      "timestamp": 1703001600,
      "type": 0,
      "content": "Hello everyone! Welcome to the Tech Discussion Group~"
    },
    {
      "sender": "def456",
      "accountName": "Alice",
      "groupNickname": "Moderator",
      "timestamp": 1703001610,
      "type": 1,
      "content": "[Image: screenshot.jpg]"
    }
  ]
}

Private Chat Example

{
  "chatlab": {
    "version": "0.0.1",
    "exportedAt": 1703001600
  },
  "meta": {
    "name": "Chat with Mike",
    "platform": "whatsapp",
    "type": "private"
  },
  "members": [
    {
      "platformId": "123456789",
      "accountName": "Me",
      "avatar": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
    },
    {
      "platformId": "987654321",
      "accountName": "Mike",
      "avatar": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
    }
  ],
  "messages": [
    {
      "sender": "123456789",
      "accountName": "Me",
      "timestamp": 1703001600,
      "type": 0,
      "content": "Hey, are you there?"
    }
  ]
}

JSONL Streaming Format

JSONL (JSON Lines) format is suitable for very large chat records (>1M messages), avoiding memory overflow issues.

Features

• One JSON object per line
• Line type distinguished by _type field: header / member / message
• Constant memory usage (~100MB), supports GB-sized files
• Supports streaming writes, can append while exporting

Line Types

_type	Description	Required
header	File header with chatlab + meta	✅ Must be first line
member	Member information	- Optional
message	Message record	✅ At least one

Complete Example

{"_type":"header","chatlab":{"version":"0.0.1","exportedAt":1703001600},"meta":{"name":"Tech Group","platform":"discord","type":"group"}}
{"_type":"member","platformId":"123456","accountName":"John","groupNickname":"Admin"}
{"_type":"member","platformId":"789012","accountName":"Alice"}
{"_type":"message","sender":"123456","accountName":"John","groupNickname":"Admin","timestamp":1703001600,"type":0,"content":"Hello!"}
{"_type":"message","sender":"789012","accountName":"Alice","timestamp":1703001610,"type":0,"content":"Hi there!"}
{"_type":"message","sender":"123456","accountName":"John","groupNickname":"Admin","timestamp":1703001620,"type":1,"content":"[Image]"}

Parsing Rules

1. First line must be header: Contains chatlab version and meta information
2. Member lines before messages: Optional, if omitted, members are collected from messages
3. Messages in chronological order: Recommended to sort by timestamp ascending
4. Each line is self-contained: Single line parse errors can be skipped
5. Comment lines supported: Lines starting with # are skipped (for notes)

Note

• Each line must be valid JSON (no line breaks within)
• Lines separated by newline character \n

Version History

Version	Date	Changes
0.0.1	2025-12	Initial version