# Connect Telegram to Al Moasis

Connect a Telegram bot to your Muassis in under 60 seconds.

> **Note for the curious:** OpenClaw lists Telegram in its dashboard mockups
> but never actually implemented it. Muassis is the first AI gateway with
> a real Telegram Bot API integration — long-polling, multi-tenant,
> auto-reconnect, ambient group reactions.

## What you need

- A Telegram account (any phone)
- 60 seconds in the Telegram app
- Muassis running (`muassis start`)

## Step 1 — Get a bot token from BotFather

1. Open Telegram, search for **`@BotFather`** (the official Telegram bot for creating bots — verified blue check).
2. Send `/start` to BotFather.
3. Send `/newbot`.
4. **Choose a name** for your bot (e.g., "محل أحمد للأقمشة assistant"). This is what users see.
5. **Choose a username** ending with `bot` (e.g., `ahmad_fabrics_bot`). Must be unique on Telegram. Try `<businessname>_muassis_bot` if your first try is taken.
6. BotFather replies with a token that looks like:
   ```
   123456789:ABCdefGhIJKlmnopQRSTuvwxyz_0123456789
   ```
7. **Copy the token.** Treat it like a password — anyone with it can post as your bot.

While you're with BotFather (optional but recommended):
- `/setdescription` → write what your bot does (1 sentence)
- `/setabouttext` → "Powered by Al Moasis · مساعد عمل ذكي"
- `/setuserpic` → upload a logo (you can ask Muassis to generate one)

## Step 2 — Give the token to Muassis

Three ways, pick whichever feels easiest:

### Option A — Paste it in chat (recommended)
Open the dashboard at `http://127.0.0.1:3000/dashboard/`, go to the chat tab, and paste the token in a message:

```
هذا توكن البوت: 123456789:ABCdefGhIJKlmnopQRSTuvwxyz_0123456789
```
or in English:
```
my telegram bot token: 123456789:ABCdef...
```

Muassis will detect it, validate it via `getMe`, store it (encrypted at rest), and start listening.

### Option B — `muassis env set` from the terminal
```bash
muassis env set MUASSIS_TELEGRAM_BOT_TOKEN "123456789:ABCdef..."
muassis start    # restart the gateway to pick it up
```

### Option C — POST to the API (for power users)
```bash
TOKEN=$(curl -s http://127.0.0.1:3000/api/auth/local-token | jq -r .data.token)
curl -X POST http://127.0.0.1:3000/api/channels/telegram/connect \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"token":"123456789:ABCdef..."}'
```

## Step 3 — Verify the connection

```bash
muassis status
```
or check the dashboard: a green dot next to the Telegram channel + your bot's `@username` displayed.

API check:
```bash
curl http://127.0.0.1:3000/api/channels/telegram/status -H "Authorization: Bearer $TOKEN"
# expect: { "data": { "status": "connected", "bot_username": "ahmad_fabrics_bot", ... } }
```

## Step 4 — Test it

1. In Telegram, search for the bot's @username you chose in Step 1.5.
2. Tap the bot, hit **Start**.
3. Bot replies with the welcome message.
4. Send any message — Muassis responds in your dialect.

## What works

| Feature | Status |
|---|---|
| Direct messages to the bot | ✅ |
| Group messages (when bot is mentioned with @username) | ✅ |
| Group messages without mention | ✅ ambient reaction (✅/👀/🤔) |
| Photos / files | ⏳ text only in v1.1, media coming v1.2 |
| Voice messages | ⏳ planned |
| `/start` command | ✅ greets in Arabic |
| Inline keyboards | ⏳ planned |

## What if it doesn't work?

### Error: "Invalid bot token — get a new one from @BotFather"
Token is wrong. Causes:
- Typo (a missing colon, swapped chars)
- Bot was deleted from BotFather (`/mybots` → check)
- Token was rotated (`/revoke` resets it; you need the new one)

Get a fresh token: `@BotFather` → `/mybots` → choose the bot → **API Token**.

### Status stays `connecting` forever
Network blocked? Test:
```bash
curl https://api.telegram.org/bot123456789:ABCdef.../getMe
# expect: { "ok": true, "result": { ... } }
```

If that fails too, your network blocks `api.telegram.org` (some Saudi corporate networks do, rare). Workaround: VPN to a non-blocked region, or use a residential connection.

### Bot doesn't reply
Three checks:
1. `muassis status` shows green?
2. Allowlist gate isn't blocking the sender. By default `inbound_access` is `ask` for unknown senders → look for an escalation card on the dashboard.
3. NIM key works (`muassis env show` shows `NVIDIA_API_KEY` set, OR the bundled key is decoded).

### Anti-pattern: don't share the token publicly
- ❌ Don't paste the token in a public Telegram group
- ❌ Don't commit it to GitHub
- ❌ Don't put it in a screenshot
- ✅ Stored encrypted at rest in Muassis (in `identity_facts.api.<name>.token` with `TENANT_ENCRYPTION_KEY`)

If you suspect leakage: `@BotFather` → `/revoke` → choose your bot. Old token dies, new one generates. Re-paste in Muassis.

## Multi-tenant / multi-bot

Run more than one Telegram bot from one Muassis? Yes:
- Each business (tenant) has its own `channel.telegram_bot_token` identity fact.
- Sessions keyed by `tenantId`, so they're isolated.
- For a single tenant running TWO bots (sales bot + support bot), per-account isolation is on the v1.2 roadmap. Today, run each on a separate Muassis install or use distinct tenants.

## Removing the connection

```bash
# Pause (keeps token for re-enable)
curl -X POST http://127.0.0.1:3000/api/channels/telegram/disconnect \
  -H "Authorization: Bearer $TOKEN"

# Permanently remove the token from storage
muassis env unset MUASSIS_TELEGRAM_BOT_TOKEN
# Or via the per-tenant fact:
curl -X DELETE http://127.0.0.1:3000/api/autonomy/identity/channel.telegram_bot_token \
  -H "Authorization: Bearer $TOKEN"
```

To delete the bot entirely: `@BotFather` → `/deletebot` → confirm.

## Useful BotFather commands (quick reference)

| Command | Purpose |
|---|---|
| `/newbot` | Create a new bot |
| `/mybots` | List + manage your bots |
| `/setname` | Change display name |
| `/setdescription` | Set the bot's description |
| `/setabouttext` | Set the "about" text shown on profile |
| `/setuserpic` | Upload bot avatar |
| `/setcommands` | Set the slash-command menu (e.g. `/start`, `/help`, `/orders`) |
| `/revoke` | Generate a new token (old one dies) |
| `/deletebot` | Permanently delete the bot |
| `/setjoingroups` | Allow / disallow groups |
| `/setprivacy` | Bot reads all messages OR only mentions/commands (default) |

For Muassis: keep `/setprivacy` at the **default** (only sees commands + mentions in groups) so Muassis doesn't accidentally process every group message — that's how the ambient-reaction-vs-full-reply distinction works.

---

**Took longer than 60 seconds?** Email support@taseesai.com with what step blocked you and we'll fix the docs.
