Class: Bot

Authenticated bot instance returned by ArattixBot.loginWithQr(). Provides methods for fetching chats, reading messages, downloading media, and accessing the MessageSender.

Source: src/Socket/bot.js

Constructor

new Bot(session)

constructor(session: AxiosInstance)

Creates a Bot with the given authenticated axios session. Normally you don't construct this directly — use ArattixBot.loginWithQr() instead.

session: AxiosInstance — Axios instance with cookie jar support.

Properties

session property

AxiosInstance

The authenticated axios session with cookie jar.

chats property

Array

Cached chat list. Initially empty [].

sender getter

get sender(): MessageSender

Returns a MessageSender instance bound to this session.

CSRF Setup

setupCsrf() async

setupCsrf(): Promise<void>

Call this once after login before using other API methods. Fetches the CT_CSRF_TOKEN cookie and sets the X-ZCSRF-TOKEN header on the session.

const bot = await arattix.loginWithQr();
await bot.setupCsrf(); // Required before API calls

Chat Methods

fetchChats(options?) async

fetchChats({ pinned?, limit? }): Promise<Object.<string, Chat>>

Fetch the chat list and return parsed Chat objects keyed by chat ID.

options.pinned: boolean — Fetch pinned chats only. Default: false
options.limit: number — Maximum number of chats. Default: 20
Returns: Promise<Object<string, Chat>> — Map of chatId → Chat

fetchChatsRaw(options?) async

fetchChatsRaw({ limit? }): Promise<Object>

Fetch the raw (unparsed) chat API response. Useful for debugging or accessing fields not in the Chat model.

options.limit: number — Default: 20

fetchChatsLive(options?) async

fetchChatsLive({ limit? }): Promise<Object.<string, Chat>>

Fetch chats using a fresh session, bypassing server-side session caching. Guarantees up-to-date data.

fetchChatsLiveRaw(options?) async

fetchChatsLiveRaw({ limit? }): Promise<Object>

Fresh session + raw response combined.

fetchChatDetails(chatId, options?) async

fetchChatDetails(chatId: string, { limit? }): Promise<Object | null>

Fetch detailed info for a specific chat. Returns null on error.

chatId: string — The chat ID to look up.
options.limit: number — Default: 50

// Get parsed chats
const chats = await bot.fetchChats({ limit: 10 });
for (const [id, chat] of Object.entries(chats)) {
  console.log(`${chat.title} — ${id}`);
}

// Get raw API data
const raw = await bot.fetchChatsRaw();
console.log(raw.data.chats.length);

// Live (fresh session, no cache)
const live = await bot.fetchChatsLive({ limit: 5 });

Message Methods

fetchMessages(chatId, options?) async

fetchMessages(chatId: string, { limit? }): Promise<Array>

Fetch messages for a specific chat using the V2 API. Returns live, uncached data, sorted oldest-first. Each message object includes id, type, content, sender, and time.

chatId: string — The chat ID.
options.limit: number — Max messages to fetch. Default: 20
Returns: Promise<Array> — Array of v2 message objects.

const messages = await bot.fetchMessages(chatId, { limit: 50 });
for (const msg of messages) {
  console.log(`[${msg.sender?.name}] ${msg.content?.text || '(media)'}`);
}

Media Methods

downloadMedia(fileId, chatId, options?) async

downloadMedia(fileId, chatId, { thumbnail? }): Promise<{ data: Buffer, contentType: string, fileName: string | null }>

Download a media file as a Buffer. Tries the primary UDS download endpoint first, then falls back to the v1 attachments endpoint.

fileId: string — The file ID from message.content.file.id
chatId: string — The chat ID the file belongs to.
options.thumbnail: boolean — Download thumbnail instead. Default: false

downloadMediaToFile(fileId, chatId, outputPath, options?) async

downloadMediaToFile(fileId, chatId, outputPath, { thumbnail? }): Promise<{ path: string, contentType: string, size: number }>

Download media and save it directly to a file on disk.

outputPath: string — File path to save to.

getMediaUrl(fileId, chatId, options?) method

getMediaUrl(fileId, chatId, { thumbnail? }): string

Get the download URL for a media file without downloading it. Useful for passing to external tools or streaming.

// Download to buffer
const { data, contentType } = await bot.downloadMedia(fileId, chatId);
console.log(`Downloaded ${data.length} bytes (${contentType})`);

// Save to disk
const result = await bot.downloadMediaToFile(fileId, chatId, './photo.jpg');
console.log(`Saved to ${result.path} (${result.size} bytes)`);

// Get URL only
const url = bot.getMediaUrl(fileId, chatId);
console.log(url);

Static Methods

Bot.isMediaMessage(msg) static

static isMediaMessage(msg: object): boolean

Check if a V2 message contains media (type "file" with a file object).

Bot.getMediaInfo(msg) static

static getMediaInfo(msg: object): object | null

Extract structured media info from a V2 file message. Returns an object with fileId, fileName, mimeType, size, isImage, isAudio, isVideo, isDocument, thumbnail, and dimensions. Returns null if the message is not a media message.

for (const msg of messages) {
  if (Bot.isMediaMessage(msg)) {
    const info = Bot.getMediaInfo(msg);
    console.log(`📁 ${info.fileName} (${info.mimeType})`);
    console.log(`   Size: ${info.size} bytes`);
    console.log(`   Type: image=${info.isImage} audio=${info.isAudio}`);

    // Download it
    const { data } = await bot.downloadMedia(info.fileId, chatId);
  }
}