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

# Bot de Telegram

> Recibe leads y gestiona propuestas directamente desde Telegram con la integración nativa de bot de Quikly.

La integración del bot de Telegram te permite recibir consultas de clientes, ejecutar discovery con IA y crear propuestas sin salir de Telegram. Cuando un lead le escribe a tu bot, Quikly crea una sesión de lead y te guía a través del flujo de propuesta.

## Configurar el bot de Telegram

<Steps>
  <Step title="Crea un bot con BotFather">
    Abre Telegram y escríbele a [@BotFather](https://t.me/BotFather). Envía `/newbot`, sigue las instrucciones y copia el **token del bot** que te da.
  </Step>

  <Step title="Conecta el bot a Quikly">
    En la app de Quikly, ve a **Configuración → Integraciones → Telegram**. Pega tu token del bot y guarda.
  </Step>

  <Step title="El webhook se configura automáticamente">
    Quikly registra un webhook con Telegram para que tu bot reciba mensajes. No necesitas configurar la URL del webhook manualmente.
  </Step>

  <Step title="Prueba el bot">
    Abre tu bot en Telegram y envía un mensaje. Deberías ver una respuesta del agente de Quikly confirmando la conexión.
  </Step>
</Steps>

## Cómo funciona

Cuando un cliente le escribe a tu bot de Telegram:

1. Quikly crea una **sesión de lead** vinculada al chat ID de Telegram
2. El agente de IA ejecuta **discovery técnico** — preguntando sobre el proyecto, stack, cronograma y presupuesto
3. Una vez que se reúne suficiente información, recibes una notificación para **revisar el lead**
4. Puedes iniciar **Agent Mode** desde la sesión de lead para generar una propuesta completa
5. Cuando la propuesta está lista, comparte el enlace de vuelta al cliente vía Telegram

## Capacidades del bot

| Funcionalidad           | Descripción                                                     |
| ----------------------- | --------------------------------------------------------------- |
| Recepción de leads      | Recibe consultas de proyectos de clientes                       |
| Discovery con IA        | Hace preguntas calificadoras sobre el proyecto                  |
| Sesiones de lead        | Rastrea el estado de la conversación y datos recopilados        |
| Notificaciones          | Te alerta cuando llega un nuevo lead o un cliente responde      |
| Multi-bot (plan Agency) | Conecta hasta 3 bots separados para diferentes marcas o equipos |

## Disponibilidad por plan

| Plan         | Bots de Telegram |
| ------------ | ---------------- |
| Starter      | No disponible    |
| Professional | 1 bot            |
| Agency       | Hasta 3 bots     |
| Lifetime     | 1 bot            |

## Solución de problemas

<AccordionGroup>
  <Accordion title="El bot no responde a los mensajes">
    **Verifica la URL del webhook.** Ve a **Configuración → Integraciones → Telegram** y confirma que el webhook está registrado. Puedes hacer clic en **Re-registrar Webhook** para reiniciarlo.

    Si recientemente cambiaste de entorno o modificaste la URL del backend, el webhook puede estar apuntando a una dirección antigua.
  </Accordion>

  <Accordion title="El bot responde con errores o mensajes genéricos">
    **Verifica que tu clave de API esté activa.** La integración de Telegram usa tu clave de API de Quikly internamente. Si la clave fue revocada o expiró, el bot no puede comunicarse con la API de Quikly.

    Ve a **Configuración → Claves de API** y verifica que tengas al menos una clave activa.
  </Accordion>

  <Accordion title="El webhook devuelve errores 404 o 500">
    Esto típicamente significa que el endpoint del webhook del backend de Quikly no es accesible:

    * Confirma que el backend está corriendo y es accesible en la URL configurada
    * Verifica que la ruta `/api/webhooks/telegram` no esté bloqueada por un firewall o reverse proxy
    * Revisa los logs del backend para detalles del error
  </Accordion>

  <Accordion title="Los mensajes llegan al usuario incorrecto">
    Cada bot de Telegram está vinculado a una cuenta de Quikly. Si múltiples miembros del equipo necesitan bots, usa el **plan Agency** que soporta hasta 3 bots, cada uno vinculado a un miembro del equipo o marca diferente.

    Verifica que el token del bot en Configuración coincida con el bot que estás probando.
  </Accordion>

  <Accordion title="El bot funciona localmente pero no en producción">
    Los webhooks de Telegram requieren una **URL HTTPS accesible públicamente**. `localhost` o IPs privadas no funcionan.

    Si estás probando localmente, usa una herramienta de tunneling como [ngrok](https://ngrok.com) para exponer tu servidor local, luego actualiza la URL del webhook en la configuración de Quikly.
  </Accordion>

  <Accordion title="Sesiones de lead duplicadas para el mismo chat">
    Quikly de-duplica sesiones de lead por `channel + channel_id`. Si ya existe una sesión para un chat ID de Telegram y su estado no es `completed` o `provider_rejected`, los nuevos mensajes continúan la sesión existente.

    Si ves duplicados, verifica si las sesiones anteriores fueron marcadas como completadas — los nuevos mensajes después de completar crean una nueva sesión.
  </Accordion>
</AccordionGroup>