/telegram-chat-parser

Module to import and easily navigate Telegram JSON chat exports

Primary LanguageTypeScript

Telegram Chat Parser

NodeJS module to convert exported Telegram JSON chat data into an object for easier traversal and manipulation.

Installation

npm install telegram-chat-parser

Demo

TypeScript:

  import { TelegramChat } from 'telegram-chat-parser';

  // configure options (optional)
  const options:ChatOptions = {
    includeStickersAsEmoji: true,
  };

  // Load chat
  const json = fs.readFileSync('./tests/data/saved.json', { encoding: 'utf8', flag: 'r' });
  const chat = new TelegramChat(json, options);

  // Get all messages
  const allMessages = chat.messages;

  // without services messages
  const realMessages = chat.messages.filter((msg:TelegramMessage) => msg.isMessage);

  // Get all users referred to in any way
  const allUsersFound = chat.users;

  // Get all users that participated (had a "from" or "actor" with them in it)
  const whoDidSomething = chat.participants;

  // get a regular text message that is a reply to something else
  const reply = chat.messages.find((msg) => msg.contentType === ContentType.Text && msg.replyTo);
  if (reply === undefined) {
    throw new Error("Couldn't find message");
  }
  const message = reply.replyTo;
  const text = message?.text();

Definitions

TelegramChat

{
    // Unique identifier from Telegram for this chat
    id: number;

    // name of the chat / name of the user the chat is with
    name: String;
    
    // type of chat (see below)
    type: ChatType;

    // shortcuts to check type
    isBot: boolean;
    isPublic: boolean;
    isGroup: boolean;
    isPublicSupergroup: boolean;
    isPrivateGroup: boolean;
    isChannel: boolean;

    // All messages in chat
    messages: TelegramMessage[];

    // All users referenced in chat (may not include id)
    users: TelegramUser[];  

    // All users that paricipated in the chat (found in "from" or "actor")
    // Should always have id
    participants: TelegramUser[];

    // Options for converting data
    Defaults: ChatOptions;
}

ChatOptions

Default values for TelegramChat are shown.

ImportMessageOptions & {
  ignoreService:boolean, //default: false,
  mergeMissingUserIdIntoName:boolean, // default: true,
}

ChatType

enum ChatType {
  BotChat = 'bot_chat',
  PrivateGroup = 'private_group',
  PublicSupergroup = 'public_supergroup',
  PersonalChat = 'personal_chat',
  SavedMessages = 'saved_messages',
  PrivateChannel = 'private_channel',
  PublicChannel = 'public_channel',
}

TelegramMessage

See for more detailed descriptions.

{
    // Unique chat identifier
    id: number;

    // Message type (service or message)
    type: 'message' | 'service';

    // Message type based on content
    contentType: ContentType;

    // Moment object holding date
    dateMoment: Moment;

    // ...returned as a Date object
    date: Date;

    // all available data for this user converted into a TelegramUser object
    from: TelegramUser;

    // message text converted into a string instead of string|object[]
    text(options?:MessageOptions): String;

}

ImportMessageOptions

{
    // when type is sticker, should the corresponding emoji be added to the text
    includeStickersAsEmoji?: boolean,
}

ContentType

enum ContentType {
  Text = 'text',
  Image = 'image',
  Audio = 'audio',
  Video = 'video_file',
  File = 'file',
  Animation = 'animation',
  Button = 'button',
  Keyboard = 'keyboard',
  VoiceMessage = 'voice_message',
  Sticker = 'sticker',
  Poll = 'poll',
}

TelegramUser

{
    id: number;
    name: String;
    participated: boolean; // did the user participate in the chat
}

Useful Links

Telegram uses a variety of schema to define this data, but does not seem to have released a schema for an export. If you are confused about some of the data found in the export, you may find out more in the following links:

Telegram Bot schema

Telegram Message definition

Telegram Chat definition

Telegram User definition