> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fliiq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Telegram

> Send messages and run a real-time bot via Telegram

<Note>
  **Easiest channel to get started.** Telegram is the fastest way to give Fliiq its own communication channel — just create a bot via BotFather, no app passwords, no paid services.
</Note>

Fliiq gets its own Telegram bot. This isn't your personal Telegram — it's Fliiq's. You message Fliiq's bot from your Telegram app the same way you'd message any person or bot. Your Telegram talks to Fliiq's Telegram.

Fliiq integrates with Telegram in two ways: outbound messaging via `send_telegram` skill, and a real-time listener in the daemon that responds to incoming messages.

## Setup

<Steps>
  <Step title="Create Fliiq's bot">
    Message [@BotFather](https://t.me/botfather) on Telegram and use `/newbot`. BotFather gives you a token like `123456:ABC-DEF...`.
  </Step>

  <Step title="Add the bot token to .env">
    ```bash .env theme={null}
    TELEGRAM_BOT_TOKEN=123456:ABC-DEF...
    ```
  </Step>

  <Step title="Run the interactive setup">
    ```bash theme={null}
    fliiq telegram setup
    ```

    This will prompt you to send a message to your bot, then auto-detect and save your chat ID to `TELEGRAM_ALLOWED_CHAT_IDS` in your `.env`.

    **Manual alternative:** Add `TELEGRAM_ALLOWED_CHAT_IDS=<chat_id>` to `~/.fliiq/.env` directly. To find your chat ID, message the bot and check `https://api.telegram.org/bot<TOKEN>/getUpdates`. Comma-separate multiple IDs.
  </Step>
</Steps>

<Warning>
  **`TELEGRAM_ALLOWED_CHAT_IDS` is required.** When `TELEGRAM_BOT_TOKEN` is set, `TELEGRAM_ALLOWED_CHAT_IDS` must also be set. The daemon will refuse to start without it — this prevents unauthorized users from accessing your agent.
</Warning>

## Outbound: send\_telegram

Send a message from any Fliiq session:

```
"Send a Telegram message to chat 12345678 saying the build passed"
```

Works in interactive sessions, single-shot commands, and scheduled jobs.

## Real-Time Listener

When the daemon starts and `TELEGRAM_BOT_TOKEN` is set, Fliiq automatically runs a Telegram listener that:

1. **Long-polls** Telegram's `getUpdates` API for new messages
2. **Maintains a persistent session store** — each chat gets its own conversation history that survives job executions and daemon restarts. Context is never lost between interactions.
3. **Runs a headless `agent_loop()`** for each incoming message
4. **Shows a persistent typing indicator** throughout processing — stays active for long-running tasks so you always know the agent is working
5. **Splits long responses** to respect Telegram's message length limits
6. **Filters by allowed chat IDs** for security

```bash theme={null}
fliiq daemon start       # Starts daemon + Telegram listener
fliiq daemon status      # Shows "Telegram: active" if connected
```

### Using It

Once the daemon is running, message Fliiq's bot from your phone or Telegram app. The bot responds using the full Fliiq agent loop — same skills, same memory, same capabilities as the CLI. It's like texting a colleague who happens to have access to your codebase, email, and scheduled jobs.

## Forum Topics

Telegram groups can enable **Forum Topics** — a threaded mode where messages go to named topics (like Slack channels). Fliiq supports this via the `message_thread_id` parameter on `send_telegram` and `send_telegram_audio`.

To find a topic's thread ID, send a message to the topic and check `https://api.telegram.org/bot<TOKEN>/getUpdates` — look for `message_thread_id` in the update.

```
"Send a Telegram message to chat 12345678, thread 42, saying the release passed"
```

In a job, pass `message_thread_id` in the prompt or use `send_telegram` directly:

```yaml theme={null}
name: release-notifications
trigger:
  type: webhook
prompt: "Send a Telegram message to chat 12345678, thread 42, with the release summary"
skills:
  - send_telegram
delivery:
  type: telegram
  chat_id: "12345678"
```

## Per-Request Model Override

Switch models mid-conversation without restarting the daemon. Useful when you want Opus for a complex task and Sonnet for quick lookups — all in the same bot session.

```
/model opus-4.6                         # Switch to Opus for this and future messages
/model sonnet-4.5 summarize my inbox    # One-shot: use Sonnet for this message only
use the model gpt-4.1 to write a plan   # Natural language syntax also works
/model reset                            # Revert to the default model
```

Model aliases from `~/.fliiq/models.yaml` are resolved automatically. To confirm the active model, just ask: "what model are you using?"

## Usage in Jobs

```yaml theme={null}
name: daily-standup
trigger:
  type: cron
  schedule: "0 9 * * 1-5"
prompt: "Summarize my git activity from yesterday"
delivery:
  type: telegram
  chat_id: "12345678"
```