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 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)

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

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

# 1. @BotFather crée le bot, noter le TOKEN
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)
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:
#    (édite le fichier puis push)
cd /Users/gabrielradureau/Work/Vibe/telegram-gateway
# ajouter sous "bots:" :
#   monbot:
#     handler: echo
git add chart/values.yaml
git commit -m "bots: add $SLUG"
git push

# 4. Forcer le rollout pour que le pod relise la ConfigMap (le checksum
#    annotation s'en charge en théorie, mais on s'assure)
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
export BOT_${ENV_SLUG}_TOKEN="$TOKEN"
export BOT_${ENV_SLUG}_SECRET="$SECRET"
make setwebhook SLUG="$SLUG" BASE_URL=https://tg.arcodange.fr

# 6. Test : envoie un message au bot, attends < 2s pour l'echo

Limite Phase 1 : tous les bots ont le handler echo. Pas encore de routage vers une logique métier différente par bot.

---

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)