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

# Telegram

> Use Telegram chats and groups as mobile collaboration spaces for local AI agents.

# Telegram

Telegram is a lightweight way to delegate work to local AI agents from your phone, a group, or a forum topic.

## What you get

* Send tasks to a local AI agent from a DM, group, or forum.
* Keep work local while you control it from anywhere.

## Set up the bot

1. In Telegram, open [@BotFather](https://t.me/BotFather), send `/newbot`, and choose a display name plus a username ending in `bot`. Copy the token.
2. In the Avibe wizard, choose **Telegram**, paste the token, and **Validate**. (If your region blocks Telegram, set a proxy URL in the same step before validating — see below.)
3. Back in **@BotFather**, set the switches that decide how the bot behaves in groups:
   * **`/setprivacy` → Disable** — so the bot sees normal group messages, not only mentions. *This is the #1 setup miss.*
   * **`/setjoingroups` → Enable** — if you'll use it in groups or forums.
   * **`/setcommands`** — publish `start`, `settings`, `new`, `resume`.

## Bind, then discover chats

Telegram has no "list every chat" API, so Avibe discovers chats from inbound messages. On first run, in order:

1. Finish setup and start the service.
2. Copy the bind command from the final summary screen.
3. DM the bot `bind <code>` to become the first admin, then send `/start` to confirm.
4. To use a group or forum, add the bot there, send one message, then **refresh the Telegram chat list** in group settings and enable it. Forum auto-topics need admin / topic-management rights.

## Group defaults

The wizard exposes two Telegram defaults: **require explicit targeting in groups** (respond only to commands, mentions, or replies — good for busy groups) and **forum auto-topic mode** (a top-level message opens a new topic; needs admin / topic rights).

## Smoke test

```text theme={null}
Say hello and tell me which project directory you can see.
```

If the bot does not answer, run:

```bash theme={null}
vibe doctor
```

## Outbound proxy

If Telegram is blocked in your region, set `proxy_url` — easiest in the wizard's Proxy field before validating, or on the Telegram config block in the Web UI. HTTP/HTTPS and any `socks*://` scheme (`socks4`, `socks4a`, `socks5`, `socks5h`) are supported. Saving only persists the change; run `vibe restart --delay-seconds 60` to apply it. Note: Avibe does **not** fall back to a direct connection if the proxy is down — fix or remove `proxy_url` to recover.

## Common issues

| Symptom                        | Check                                                                 |
| ------------------------------ | --------------------------------------------------------------------- |
| Group messages ignored         | `/setprivacy` is set to **Disable**                                   |
| Bot works in DM but not groups | `/setjoingroups` is **Enable**                                        |
| Chat not listed                | Send a message there first, then refresh discovered chats             |
| Agent missing                  | Selected backend CLI is installed and visible on PATH                 |
| Telegram unreachable from host | `proxy_url` on Telegram config; check firewall and TLS errors in logs |