MANUAL

What is the Telegram Channel?

The Telegram channel connects a Telegram bot with Fararoni, allowing users to interact with your AI assistant through the Telegram application.

Architecture

+----------------+     +-----------------+     +----------------+     +----------------+
|   User         | --> |  Telegram API   | --> |   Sidecar TG   | --> |   Fararoni     |
|   Telegram     |     |  (Bot Father)   |     |   (:3001)      |     |   Gateway      |
+----------------+     +-----------------+     +----------------+     |   (:7071)      |
                                                                      +----------------+
                                                                             |
                                                                             v
                                                                      +----------------+
                                                                      |  LLM Agents    |
                                                                      +----------------+

Telegram Advantages

WhatsApp Comparison

Required Software

• Node.js 18 or higher
• npm (comes with Node.js)
• Fararoni Core installed
• Java 25+ with --enable-preview

Accounts

• Telegram account (on your phone or desktop)

Ports

# Verify Node.js (must be 18+)
node --version

# Verify npm
npm --version

# Verify Java
java --version

Channel Encryption (Encryption Key)

Bot tokens are stored encrypted in the local database.

# Production
export FARARONI_CHANNELS_ENCRYPTION_KEY="$(openssl rand -base64 32)"

# Local development (no extra config needed)
export FARARONI_DEV_MODE=true

Step 3.1: Open BotFather

1. Open Telegram on your phone or desktop
2. Search for @BotFather
3. Select the user with the blue verification badge
4. Start a conversation (click "Start")

Step 3.2: Create New Bot

Send the command: /newbot

BotFather will ask for the display name (e.g.: Fararoni Assistant) and then the username (e.g.: my_assistant_bot).

IMPORTANT: The username MUST end in bot and must be unique across Telegram.

Step 3.3: Get the Token

BotFather will give you a message with your token:

Use this token to access the HTTP API:
1234567890:ABCdefGHIjklMNOpqrSTUvwxYZ

COPY AND SAVE THIS TOKEN — You'll need it to start the Sidecar.

IMPORTANT: The token is secret. NEVER share it publicly or push it to git.

Recover Existing Token

Send /mybots to @BotFather, select your bot and click API Token.

Regenerate Compromised Token

Send /revoke to @BotFather, select your bot. The previous one will stop working immediately.

cd /path/to/fararoni/fararoni-sidecar-tg
npm install

This will install: telegraf, express, axios, dotenv

Verify modules.yml

Location: ~/.fararoni/config/modules.yml

channels:
  telegram:
    enabled: true
    trust_level: SECURE_ENCRYPTED
    egress_url: "http://localhost:3001/send"
    capabilities:
      - text
    timeout_ms: 5000
    retry_count: 3

Verify REST Gateway

gateway:
  rest:
    enabled: true
    port: 7071

Quick Summary

Terminal 1: java --enable-preview -jar fararoni-core-1.0.0.jar --server
Terminal 2: export TELEGRAM_TOKEN="your_token" && npm start
Telegram:   Search your bot and send a message

Start Order (IMPORTANT)

1. Fararoni Core (Gateway)  <-- FIRST (port 7071)
2. Sidecar Telegram         <-- SECOND (port 3001)

Terminal 1: Start Fararoni Core

cd fararoni-core/target
java --enable-preview -jar fararoni-core-1.0.0.jar --server

Wait until you see:

[MODULE-REGISTRY] Loaded module: OmniChannelGatewayModule
[INGRESS] RestIngressServer listening on port 7071
[READY] Fararoni Core ready

Terminal 2: Start Telegram Sidecar

cd fararoni-sidecar-tg
export TELEGRAM_TOKEN="1234567890:ABCdefGHIjklMNOpqrSTUvwxYZ"
npm start

Wait until you see:

[INFO]  [HTTP] Egress Server on port 3001
[INFO]  [TELEGRAM] Bot connected: @your_bot_username
[INFO]  [READY] Sidecar ready to receive messages

Alternative: Use .env File

cd fararoni-sidecar-tg
cp .env.example .env
nano .env

TELEGRAM_TOKEN=1234567890:ABCdefGHIjklMNOpqrSTUvwxYZ
SIDECAR_PORT=3001
GATEWAY_URL=http://localhost:7071/gateway/v1/inbound
DEBUG=false

Gateway Health Check

curl http://localhost:7071/gateway/v1/health
# {"status": "healthy", "module": "gateway-rest-omnichannel"}

Sidecar Health Check

curl http://localhost:3001/health

{
  "status": "healthy",
  "service": "fararoni-sidecar-tg",
  "channel": "telegram",
  "port": 3001,
  "bot": {
    "id": 1234567890,
    "username": "your_bot_username"
  }
}

End-to-End Test

1. Open Telegram
2. Search your bot: @your_bot_username
3. Start conversation (click "Start" or send /start)
4. Send: Hello, what can you do?
5. You should receive a response from the Fararoni assistant

Verify Logs

[INFO]  [INGRESS] 123456789 -> "Hello, what can you do?" (HTTP 202)
[INFO]  [EGRESS] 123456789 <- "Hello! I'm Fararoni, your assistant..."

Group Filter

By default, the sidecar ONLY responds to private chats (1:1).

Enable Specific Groups

const ALLOWED_GROUPS = ['-123456789', '-987654321'];

if (chat.type !== 'private' && !ALLOWED_GROUPS.includes(chat.id.toString())) {
    return;
}

Protect the Token

• NEVER push the token to git
• Use environment variables or .env file
• The .env file should be in .gitignore

Access Control

Option A: Public Bot — Anyone can chat (default behavior).

Option B: Restrict Users — Get your User ID with @userinfobot and configure:

const ALLOWED_USERS = [
    '123456789',
    '987654321',
];

if (ALLOWED_USERS.length > 0 && !ALLOWED_USERS.includes(senderId.toString())) {
    return;
}

Bot doesn't respond

# Verify Gateway
curl http://localhost:7071/gateway/v1/health

# Verify Sidecar
curl http://localhost:3001/health

If you see 401 Unauthorized in logs, the token is invalid. Regenerate with /token in @BotFather.

Error "ECONNREFUSED"

Cause: Gateway not running.

java --enable-preview -jar fararoni-core-1.0.0.jar --server

Error "409 Conflict"

Cause: Another process is using the same bot. Close any other sidecar instance.

Bot responds in groups

Verify index.js has the filter:

if (chat.type !== 'private') {
    return;
}

# Gateway health
curl http://localhost:7071/gateway/v1/health

# Sidecar health
curl http://localhost:3001/health

# Detailed status
curl http://localhost:3001/status

# Real-time logs
tail -f ~/.fararoni/logs/fararoni.log | grep -E "(OmniChannel|TELEGRAM)"

# Stop services
pkill -f "fararoni-core"
pkill -f "fararoni-sidecar-tg"

BotFather Commands

/token          - View current token
/setname        - Change bot name
/setdescription - Change description
/revoke         - Regenerate token

Implementation Checklist

REQUIREMENTS
[ ] Node.js 18+ installed
[ ] Fararoni Core installed
[ ] Java 25+ with --enable-preview

TELEGRAM
[ ] Bot created in @BotFather
[ ] Token saved securely

INSTALLATION
[ ] npm install executed
[ ] .env created with TELEGRAM_TOKEN
[ ] modules.yml has telegram.enabled: true

GETTING STARTED
[ ] Gateway running on port 7071
[ ] Sidecar running on port 3001
[ ] Health checks OK

TESTING
[ ] Message sent from Telegram
[ ] Response received from assistant

Advanced Configuration

# Change sidecar port
export SIDECAR_PORT=3002
npm start

Update modules.yml:

channels:
  telegram:
    egress_url: "http://localhost:3002/send"

Multiple Bots

channels:
  telegram_sales:
    enabled: true
    egress_url: "http://localhost:3001/send"

  telegram_support:
    enabled: true
    egress_url: "http://localhost:3002/send"

Author: Fararoni Team | Version: 1.0