El plugin de Telegram convierte mensajes de texto y notas de voz recibidos en un bot en tareas cascarón. Opera vía webhook: Telegram envía un POST al endpoint de Joe por cada actualización.

Endpoint del webhook

Configuración paso a paso

1. Crear el bot en Telegram con BotFather

   /newbot
   # Sigue las instrucciones, BotFather te entrega:
   # Token: 1234567890:ABCDefghIJKlmnOPQrsTUVwxyz

2. Registrar el PluginConfig en Joe

   from apps.common.models import PluginConfig
   
   config = PluginConfig(
       usuario=user,
       servicio="telegram",
       identificador="@joe_bot",
       metadatos={"webhook_secret": "mi_secret_seguro_aleatorio"},
   )
   config.set_token("1234567890:ABCDefghIJKlmnOPQrsTUVwxyz")
   config.save()
   # Anota el ID generado: config.pk → ej. 3

3. Registrar el webhook en Telegram

   # Reemplaza TOKEN, URL y SECRET
   curl -X POST \
     "https://api.telegram.org/bot<TOKEN>/setWebhook" \
     -H "Content-Type: application/json" \
     -d '{
       "url": "https://joe.pedroospino.net/plugins/telegram/webhook/3/",
       "secret_token": "mi_secret_seguro_aleatorio"
     }'
   
   # Respuesta esperada:
   # {"ok": true, "result": true, "description": "Webhook was set"}

4. Verificar el webhook

   curl "https://api.telegram.org/bot<TOKEN>/getWebhookInfo"

Flujo de un mensaje entrante

1. Telegram envía POST al webhook con el update JSON.
2. Joe valida el header X-Telegram-Bot-Api-Secret-Token contra el webhook_secret almacenado.
3. Se deserializa el payload (TelegramUpdate).
4. Si es texto: se crea una tarea con tipo=telegram y el texto como título.
5. Si es voz: se crea una tarea con tipo=telegram_voice y pendiente_stt=True en metadatos.
6. Joe responde {"ok": true} con HTTP 200 (evita reintentos de Telegram).
7. El bot envía un mensaje de confirmación al chat: "✅ Recibido. Encolando... [CODIGO]"

Campos en metadatos_extra de la tarea

Campos del PluginConfig para Telegram