Getting Started

This guide walks you through setting up Arattix, authenticating, and building your first bot.

Prerequisites

• Node.js version 14 or higher
• An Arattai account with the mobile app installed
• A terminal that supports QR code display (most modern terminals do)

Installation

Or install from source:

git clone https://github.com/SafwanGanz/Arattix.git
cd Arattix
npm install

Docker Installation

Run Arattix bots in Docker containers for easy deployment:

Using Docker directly

# Clone and build
git clone https://github.com/SafwanGanz/Arattix.git
cd Arattix
docker build -t arattix-bot .

# Run with mounted volumes for persistence
docker run -v $(pwd)/cookies.json:/app/cookies.json \
           -v $(pwd)/downloads:/app/downloads \
           arattix-bot

Using Docker Compose

# Production environment
docker-compose up arattix-bot

# Development with hot reload
docker-compose --profile dev up arattix-dev

Your First Bot

Create a file called bot.js:

const { ArattixBot } = require('arattix');

async function main() {
  // 1. Create the client
  const arattix = new ArattixBot({ isShowQr: true });

  // 2. Authenticate — scan the QR code with your Arattai app
  const bot = await arattix.loginWithQr();

  // 3. Set up CSRF token (required before API calls)
  await bot.setupCsrf();

  console.log('✅ Bot is ready!');

  // 4. Fetch your chats
  const chats = await bot.fetchChats({ limit: 10 });

  for (const [chatId, chat] of Object.entries(chats)) {
    console.log(`📋 ${chat.title} (${chatId})`);
  }

  // 5. Send a message to the first chat
  const firstChat = Object.values(chats)[0];
  if (firstChat) {
    await bot.sender.sendMessage('Hello from Arattix! 🤖', {
      chat: firstChat
    });
    console.log('✉️ Message sent!');
  }
}

main().catch(console.error);

Run it:

Polling for Messages

Arattix uses a polling approach to detect new messages. The V2 messages API returns live, uncached data with zero delay.

const POLL_INTERVAL = 3000; // 3 seconds
const lastSeen = {};

async function pollMessages(bot, chatId) {
  const messages = await bot.fetchMessages(chatId, { limit: 10 });

  for (const msg of messages) {
    // Skip messages we've already seen
    if (lastSeen[chatId] && msg.id <= lastSeen[chatId]) continue;

    // Process new message
    const text = msg.content?.text;
    if (text) {
      console.log(`[${msg.sender?.name}] ${text}`);

      // Reply to /ping
      if (text.startsWith('/ping')) {
        await bot.sender.sendMessage('🏓 Pong!', {
          chatId,
          dname: 'Bot'
        });
      }
    }
  }

  // Track last seen message
  if (messages.length > 0) {
    lastSeen[chatId] = messages[messages.length - 1].id;
  }
}

// Poll every 3 seconds
setInterval(() => pollMessages(bot, chatId), POLL_INTERVAL);

Working with Media

Detecting Media Messages

const { Bot, MediaInfo } = require('arattix');

const messages = await bot.fetchMessages(chatId, { limit: 20 });

for (const msg of messages) {
  // Method 1: Using Bot static methods
  if (Bot.isMediaMessage(msg)) {
    const info = Bot.getMediaInfo(msg);
    console.log(`${info.fileName} — ${info.mimeType} — ${info.size} bytes`);
  }

  // Method 2: Using MediaInfo class
  const media = MediaInfo.from(msg);
  if (media) {
    console.log(media.toString());
    // "🖼️ photo.jpg (image/jpeg, 190.7KB)"
  }
}

Downloading Media

const fs = require('fs');

// Download to buffer
const { data, contentType } = await bot.downloadMedia(fileId, chatId);
fs.writeFileSync(`./downloads/${fileName}`, data);

// Or download directly to file
await bot.downloadMediaToFile(fileId, chatId, './downloads/photo.jpg');

// Download thumbnail only
const thumb = await bot.downloadMedia(fileId, chatId, { thumbnail: true });

Sending Media

// Send file from disk
await bot.sender.sendImage('./photo.jpg', 'Nice photo!', { chatId });
await bot.sender.sendDocument('./report.pdf', 'Monthly report', { chatId });

// Send buffer (e.g. forwarding downloaded media)
const { data } = await bot.downloadMedia(fileId, chatId);
await bot.sender.sendBuffer(data, 'forwarded.jpg', {
  chatId: otherChatId,
  caption: 'Check this out!'
});

Session Management

Sessions are automatically managed. After the first QR scan, cookies are saved to cookies.json. On subsequent runs, the saved session is tested and reused if valid.

First run:
  1. No cookies.json found
  2. QR code displayed → scan with app
  3. Cookies saved to cookies.json
  4. Bot is ready

Subsequent runs:
  1. cookies.json found
  2. Session tested — still valid ✓
  3. Bot is ready (no QR needed)

Using a Proxy

const arattix = new ArattixBot({
  isShowQr: true,
  proxy: 'http://127.0.0.1:8080'
});

// All requests will go through the proxy
const bot = await arattix.loginWithQr();

Next Steps

• Check out the Examples for complete bot implementations
• See Bot for all available methods
• Learn about MediaInfo for media handling
• Browse Defaults for all API constants