telegram-gateway/HOWTO_ADD_BOT.md

# Ajouter un nouveau bot

Trois cas selon ce que tu veux faire.

---

## Cas 1 — Envoi seul (Cowork → Telegram, pas d'interaction)

**Le gateway n'est pas nécessaire.** Une session Cowork qui envoie juste des notifications appelle directement la Bot API.

Setup une fois (humain) :
1. @BotFather → `/newbot` → noter le token
2. Trouver ton chat_id via [@userinfobot](https://t.me/userinfobot) ou en messageant le bot et en regardant `getUpdates`

Prompt à donner à la session Cowork :

```
Tu peux envoyer une notification Telegram via :

  curl -sS -X POST "https://api.telegram.org/bot$BOT_TOKEN/sendMessage" \
       -H 'Content-Type: application/json' \
       -d '{"chat_id":<CHAT_ID>,"text":"<message>"}'

Variables :
  BOT_TOKEN=<token-botfather>     # à fournir en env ou en clair
  CHAT_ID=<ton-chat-id-numerique>

Pas besoin du gateway pour de l'envoi pur. Préfère cette voie quand
la session n'a rien à recevoir en retour.
```

---

## Cas 2 — Bot echo simple via le gateway (Phase 1, gated par auth)

Utile pour valider la chaîne, créer un canal de log conversationnel, etc.

> **Auth (Phase 1.5, ADR [20260509](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/docs/adr/20260509-telegram-gateway-auth.md))** : par défaut, **`requireAuth: true`** s'applique → tout user qui DM ce bot doit d'abord ouvrir une session via `/auth <code>` chez `@arcodange_factory_bot`. Voir [`AUTH.md`](AUTH.md). Pour rendre un bot public, ajouter explicitement `requireAuth: false`.

Steps (humain ou session Claude avec accès au cluster + au repo) :

1. **@BotFather crée le bot**, noter le TOKEN.

   ```bash
   TOKEN='1234:AAA...'
   SLUG='monbot'                                    # kebab-case, [a-z0-9-]+
   ENV_SLUG=$(echo "$SLUG" | tr 'a-z-' 'A-Z_')      # ex: monbot → MONBOT
   SECRET=$(openssl rand -hex 32)
   ```

2. **Patcher le Secret cluster** (ajoute les 2 clés sans toucher aux existantes) :

   ```bash
   kubectl -n telegram-gateway patch secret telegram-gateway-bots --type=json -p="[
     {\"op\":\"add\",\"path\":\"/data/BOT_${ENV_SLUG}_TOKEN\",\"value\":\"$(echo -n "$TOKEN" | base64)\"},
     {\"op\":\"add\",\"path\":\"/data/BOT_${ENV_SLUG}_SECRET\",\"value\":\"$(echo -n "$SECRET" | base64)\"}
   ]"
   ```

3. **Déclarer le bot** dans `chart/values.yaml` sous `bots:` :

   ```yaml
   bots:
     monbot:
       handler: echo
       # requireAuth: true  (implicite — défaut sécurisé)
   ```

   Pour un bot public (notifications status, etc.), opt-out explicite :

   ```yaml
   bots:
     statusbot:
       handler: echo
       requireAuth: false
   ```

4. **Push + rollout** :

   ```bash
   cd /Users/gabrielradureau/Work/Vibe/telegram-gateway
   git add chart/values.yaml
   git commit -m "bots: add $SLUG"
   git push
   kubectl -n telegram-gateway rollout restart deploy/telegram-gateway
   kubectl -n telegram-gateway rollout status  deploy/telegram-gateway
   ```

5. **Enregistrer le webhook côté Telegram** :

   ```bash
   export BOT_${ENV_SLUG}_TOKEN="$TOKEN"
   export BOT_${ENV_SLUG}_SECRET="$SECRET"
   make setwebhook SLUG="$SLUG" BASE_URL=https://tg.arcodange.fr
   ```

6. **Test** :
   - Si `requireAuth` est laissé à true : envoie un message → réponse `🔒 /auth chez @arcodange_factory_bot` ; fais `/auth <code>` chez factory ; renvoie un message → echo en < 2 s.
   - Si `requireAuth: false` : echo direct en < 2 s.

**Limite Phase 1** : tous les bots ont le handler `echo` ou `auth`. Pas encore de routage vers une logique métier différente par bot — voir Cas 3.

---

## Cas 3 — Bot interactif piloté par un agent (Phase 3, pas encore livré)

Cible : utilisateur DM le bot → gateway déclenche un wrapper shell (ex. `claude --print`, `mistral-vibe`, ou un script Python qui appelle Ollama) → la réponse est renvoyée via Telegram.

Pour l'instant **non supporté** côté gateway. Phases requises :
- Phase 2 (queue Postgres + handler `http`) → permet à un service in-cluster d'être le handler
- Phase 3 (handlers async `shell` / `script` / `ollama` + retry pour Macbook endormi)

Quand Phase 3 sera up, le ajout d'un tel bot sera : steps Cas 2 + handler `shell`/`script`/`ollama` au lieu d'`echo`, plus la commande/script à exécuter.

Plan complet : `~/.claude/plans/pour-les-notifications-on-inherited-seal.md`.

---

## Récap : quel cas choisir ?

| Besoin | Cas | Gateway impliqué ? |
|---|---|---|
| Notifs sortantes one-way (Cowork → user) | Cas 1 | non, Bot API directe |
| Bot qui répond toujours pareil (echo, ack, ping) | Cas 2 | oui (Phase 1) |
| Bot conversationnel piloté par agent (Claude / Mistral / Ollama / script) | Cas 3 | oui (Phase 3, futur) |
| Bot qui forwarde au backend d'une app cluster (webapp, etc.) | Cas 3 | oui (Phase 2, futur) |