CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-node-telegram-bot-api

Node.js wrapper for the official Telegram Bot API with polling and webhook support, comprehensive message handling, media operations, and bot management features.

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

media-files.mddocs/

Media and File Operations

Comprehensive media handling including photos, videos, audio, documents, stickers, and voice messages with upload, download, and streaming capabilities.

Capabilities

Photo Operations

Methods for sending and handling photo messages with various format support.

/**
 * Send photo to chat
 * @param {number|string} chatId - Chat identifier
 * @param {string|Buffer|stream.Readable} photo - Photo to send
 * @param {object} [options] - Additional options
 * @param {object} [fileOptions] - File upload options
 * @returns {Promise<Message>}
 */
sendPhoto(chatId, photo, options, fileOptions): Promise<Message>;

Usage Example:

// Send photo from file path
await bot.sendPhoto(chatId, './photo.jpg', {
  caption: 'Beautiful sunset 🌅',
  parse_mode: 'HTML'
});

// Send photo from URL
await bot.sendPhoto(chatId, 'https://example.com/photo.jpg', {
  caption: 'Photo from URL'
});

// Send photo from Buffer
const fs = require('fs');
const photoBuffer = fs.readFileSync('./photo.jpg');
await bot.sendPhoto(chatId, photoBuffer, {
  caption: 'Photo from buffer',
  reply_to_message_id: messageId
});

// Send photo with custom filename
await bot.sendPhoto(chatId, fs.createReadStream('./photo.jpg'), {
  caption: 'Custom filename photo'
}, {
  filename: 'custom-name.jpg',
  contentType: 'image/jpeg'
});

// Send photo with spoiler
await bot.sendPhoto(chatId, './photo.jpg', {
  has_spoiler: true,
  caption: 'Spoiler photo - click to reveal'
});

Video Operations

Methods for sending video content including regular videos and animations.

/**
 * Send video to chat
 * @param {number|string} chatId - Chat identifier
 * @param {string|Buffer|stream.Readable} video - Video to send
 * @param {object} [options] - Additional options
 * @param {object} [fileOptions] - File upload options
 * @returns {Promise<Message>}
 */
sendVideo(chatId, video, options, fileOptions): Promise<Message>;

/**
 * Send animation (GIF or H.264/MPEG-4 AVC) to chat
 * @param {number|string} chatId - Chat identifier
 * @param {string|Buffer|stream.Readable} animation - Animation to send
 * @param {object} [options] - Additional options
 * @param {object} [fileOptions] - File upload options
 * @returns {Promise<Message>}
 */
sendAnimation(chatId, animation, options, fileOptions): Promise<Message>;

/**
 * Send video note (circular video message) to chat
 * @param {number|string} chatId - Chat identifier
 * @param {string|Buffer|stream.Readable} videoNote - Video note to send
 * @param {object} [options] - Additional options
 * @param {object} [fileOptions] - File upload options
 * @returns {Promise<Message>}
 */
sendVideoNote(chatId, videoNote, options, fileOptions): Promise<Message>;

Usage Example:

// Send video with duration and dimensions
await bot.sendVideo(chatId, './video.mp4', {
  duration: 60,
  width: 1920,
  height: 1080,
  caption: 'Sample video',
  supports_streaming: true
});

// Send animation/GIF
await bot.sendAnimation(chatId, './animation.gif', {
  duration: 5,
  width: 320,
  height: 240,
  caption: 'Funny animation 😄'
});

// Send video note (round video)
await bot.sendVideoNote(chatId, './video-note.mp4', {
  duration: 10,
  length: 240  // diameter of video circle
});

// Send video with thumbnail
await bot.sendVideo(chatId, './video.mp4', {
  thumbnail: './thumbnail.jpg',
  caption: 'Video with custom thumbnail'
});

Audio Operations

Methods for sending audio files and voice messages.

/**
 * Send audio file to chat
 * @param {number|string} chatId - Chat identifier
 * @param {string|Buffer|stream.Readable} audio - Audio to send
 * @param {object} [options] - Additional options
 * @param {object} [fileOptions] - File upload options
 * @returns {Promise<Message>}
 */
sendAudio(chatId, audio, options, fileOptions): Promise<Message>;

/**
 * Send voice message to chat
 * @param {number|string} chatId - Chat identifier
 * @param {string|Buffer|stream.Readable} voice - Voice to send
 * @param {object} [options] - Additional options
 * @param {object} [fileOptions] - File upload options
 * @returns {Promise<Message>}
 */
sendVoice(chatId, voice, options, fileOptions): Promise<Message>;

Usage Example:

// Send audio file with metadata
await bot.sendAudio(chatId, './song.mp3', {
  duration: 180,
  performer: 'Artist Name',
  title: 'Song Title',
  caption: 'Great song! 🎵'
});

// Send voice message
await bot.sendVoice(chatId, './voice-note.ogg', {
  duration: 15,
  caption: 'Voice message'
});

// Send audio with thumbnail
await bot.sendAudio(chatId, './song.mp3', {
  thumbnail: './album-cover.jpg',
  performer: 'Artist',
  title: 'Song'
});

Document Operations

Methods for sending various document types and files.

/**
 * Send document to chat
 * @param {number|string} chatId - Chat identifier
 * @param {string|Buffer|stream.Readable} doc - Document to send
 * @param {object} [options] - Additional options
 * @param {object} [fileOptions] - File upload options
 * @returns {Promise<Message>}
 */
sendDocument(chatId, doc, options, fileOptions): Promise<Message>;

Usage Example:

// Send document
await bot.sendDocument(chatId, './document.pdf', {
  caption: 'Important document 📄',
  parse_mode: 'HTML'
});

// Send document as file attachment (not thumbnail)
await bot.sendDocument(chatId, './spreadsheet.xlsx', {
  disable_content_type_detection: true,
  caption: 'Financial report'
});

// Send document with custom thumbnail
await bot.sendDocument(chatId, './presentation.pptx', {
  thumbnail: './presentation-thumb.jpg',
  caption: 'Quarterly presentation'
});

Sticker Operations

Methods for sending stickers and managing sticker sets.

/**
 * Send sticker to chat
 * @param {number|string} chatId - Chat identifier
 * @param {string|Buffer|stream.Readable} sticker - Sticker to send
 * @param {object} [options] - Additional options
 * @param {object} [fileOptions] - File upload options
 * @returns {Promise<Message>}
 */
sendSticker(chatId, sticker, options, fileOptions): Promise<Message>;

/**
 * Get sticker set information
 * @param {string} name - Sticker set name
 * @param {object} [options] - Additional options
 * @returns {Promise<StickerSet>}
 */
getStickerSet(name, options): Promise<StickerSet>;

/**
 * Get custom emoji stickers
 * @param {string[]} customEmojiIds - Array of custom emoji identifiers
 * @param {object} [options] - Additional options
 * @returns {Promise<Sticker[]>}
 */
getCustomEmojiStickers(customEmojiIds, options): Promise<Sticker[]>;

Usage Example:

// Send sticker by file_id
await bot.sendSticker(chatId, 'CAACAgIAAxkBAAIC...');

// Send sticker from file
await bot.sendSticker(chatId, './sticker.webp');

// Get sticker set information
const stickerSet = await bot.getStickerSet('animals_by_bot');
console.log(`Sticker set "${stickerSet.title}" has ${stickerSet.stickers.length} stickers`);

// Get custom emoji stickers
const customEmojis = await bot.getCustomEmojiStickers([
  '5789...',
  '5790...'
]);

Media Groups

Method for sending multiple media items as an album.

/**
 * Send group of photos/videos as album
 * @param {number|string} chatId - Chat identifier
 * @param {object[]} media - Array of media objects
 * @param {object} [options] - Additional options
 * @returns {Promise<Message[]>}
 */
sendMediaGroup(chatId, media, options): Promise<Message[]>;

Usage Example:

// Send photo album
const photoAlbum = [
  {
    type: 'photo',
    media: './photo1.jpg',
    caption: 'First photo'
  },
  {
    type: 'photo',
    media: './photo2.jpg',
    caption: 'Second photo'
  },
  {
    type: 'photo',
    media: './photo3.jpg'
  }
];

const messages = await bot.sendMediaGroup(chatId, photoAlbum);
console.log(`Sent album with ${messages.length} photos`);

// Send mixed media album
const mixedAlbum = [
  {
    type: 'photo',
    media: './photo.jpg',
    caption: 'Photo in album'
  },
  {
    type: 'video',
    media: './video.mp4',
    caption: 'Video in album'
  }
];

await bot.sendMediaGroup(chatId, mixedAlbum, {
  disable_notification: true
});

File Download and Access

Methods for accessing, downloading, and streaming files from Telegram servers.

/**
 * Get file information
 * @param {string} fileId - File identifier
 * @param {object} [options] - Additional options
 * @returns {Promise<File>}
 */
getFile(fileId, options): Promise<File>;

/**
 * Get download link for file (valid for 1 hour)
 * @param {string} fileId - File identifier
 * @param {object} [options] - Additional options
 * @returns {Promise<string>}
 */
getFileLink(fileId, options): Promise<string>;

/**
 * Get readable stream for file
 * @param {string} fileId - File identifier
 * @param {object} [options] - Additional options
 * @returns {stream.Readable}
 */
getFileStream(fileId, options): stream.Readable;

/**
 * Download file to specified directory
 * @param {string} fileId - File identifier
 * @param {string} downloadDir - Directory to download to
 * @param {object} [options] - Additional options
 * @returns {Promise<string>} Downloaded file path
 */
downloadFile(fileId, downloadDir, options): Promise<string>;

Usage Example:

// Handle document message and download
bot.on('document', async (msg) => {
  const document = msg.document;
  
  // Get file information
  const file = await bot.getFile(document.file_id);
  console.log(`File size: ${file.file_size} bytes`);
  console.log(`File path: ${file.file_path}`);
  
  // Get download link
  const fileLink = await bot.getFileLink(document.file_id);
  console.log(`Download link: ${fileLink}`);
  
  // Download file
  const downloadPath = await bot.downloadFile(document.file_id, './downloads/');
  console.log(`File downloaded to: ${downloadPath}`);
  
  // Stream file
  const fileStream = bot.getFileStream(document.file_id);
  fileStream.pipe(require('fs').createWriteStream(`./stream-${document.file_name}`));
});

// Handle photo and get largest size
bot.on('photo', async (msg) => {
  const photos = msg.photo;
  const largestPhoto = photos[photos.length - 1]; // Last photo is largest
  
  const filePath = await bot.downloadFile(largestPhoto.file_id, './photos/');
  console.log(`Downloaded photo: ${filePath}`);
});

User Profile Photos

Method for retrieving user profile photos.

/**
 * Get user's profile photos
 * @param {number} userId - User identifier
 * @param {object} [options] - Additional options
 * @returns {Promise<UserProfilePhotos>}
 */
getUserProfilePhotos(userId, options): Promise<UserProfilePhotos>;

Usage Example:

// Get user profile photos
const userPhotos = await bot.getUserProfilePhotos(userId, {
  offset: 0,
  limit: 10
});

console.log(`User has ${userPhotos.total_count} profile photos`);

// Download first profile photo
if (userPhotos.photos.length > 0) {
  const firstPhoto = userPhotos.photos[0];
  const largestSize = firstPhoto[firstPhoto.length - 1];
  
  const photoPath = await bot.downloadFile(largestSize.file_id, './profiles/');
  console.log(`Downloaded profile photo: ${photoPath}`);
}

Types

interface File {
  file_id: string;
  file_unique_id: string;
  file_size?: number;
  file_path?: string;
}

interface PhotoSize {
  file_id: string;
  file_unique_id: string;
  width: number;
  height: number;
  file_size?: number;
}

interface Audio {
  file_id: string;
  file_unique_id: string;
  duration: number;
  performer?: string;
  title?: string;
  file_name?: string;
  mime_type?: string;
  file_size?: number;
  thumbnail?: PhotoSize;
}

interface Document {
  file_id: string;
  file_unique_id: string;
  thumbnail?: PhotoSize;
  file_name?: string;
  mime_type?: string;
  file_size?: number;
}

interface Video {
  file_id: string;
  file_unique_id: string;
  width: number;
  height: number;
  duration: number;
  thumbnail?: PhotoSize;
  file_name?: string;
  mime_type?: string;
  file_size?: number;
}

interface Animation {
  file_id: string;
  file_unique_id: string;
  width: number;
  height: number;
  duration: number;
  thumbnail?: PhotoSize;
  file_name?: string;
  mime_type?: string;
  file_size?: number;
}

interface Voice {
  file_id: string;
  file_unique_id: string;
  duration: number;
  mime_type?: string;
  file_size?: number;
}

interface VideoNote {
  file_id: string;
  file_unique_id: string;
  length: number;
  duration: number;
  thumbnail?: PhotoSize;
  file_size?: number;
}

interface Sticker {
  file_id: string;
  file_unique_id: string;
  type: 'regular' | 'mask' | 'custom_emoji';
  width: number;
  height: number;
  is_animated: boolean;
  is_video: boolean;
  thumbnail?: PhotoSize;
  emoji?: string;
  set_name?: string;
  premium_animation?: File;
  mask_position?: MaskPosition;
  custom_emoji_id?: string;
  needs_repainting?: boolean;
  file_size?: number;
}

interface StickerSet {
  name: string;
  title: string;
  sticker_type: 'regular' | 'mask' | 'custom_emoji';
  is_animated: boolean;
  is_video: boolean;
  stickers: Sticker[];
  thumbnail?: PhotoSize;
}

interface UserProfilePhotos {
  total_count: number;
  photos: PhotoSize[][];
}

interface InputMedia {
  type: 'photo' | 'video' | 'animation' | 'audio' | 'document';
  media: string;
  caption?: string;
  parse_mode?: 'HTML' | 'Markdown' | 'MarkdownV2';
  caption_entities?: MessageEntity[];
}

interface InputMediaPhoto extends InputMedia {
  type: 'photo';
  has_spoiler?: boolean;
}

interface InputMediaVideo extends InputMedia {
  type: 'video';
  thumbnail?: string;
  width?: number;
  height?: number;
  duration?: number;
  supports_streaming?: boolean;
  has_spoiler?: boolean;
}

interface InputMediaAnimation extends InputMedia {
  type: 'animation';
  thumbnail?: string;
  width?: number;
  height?: number;
  duration?: number;
  has_spoiler?: boolean;
}

interface InputMediaAudio extends InputMedia {
  type: 'audio';
  thumbnail?: string;
  duration?: number;
  performer?: string;
  title?: string;
}

interface InputMediaDocument extends InputMedia {
  type: 'document';
  thumbnail?: string;
  disable_content_type_detection?: boolean;
}

docs

advanced-features.md

bot-settings.md

bot-setup.md

chat-management.md

index.md

interactive-features.md

media-files.md

message-handling.md

messaging.md

tile.json