> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notifique.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Modos de conexión
> Bot con token versus cuenta personal de Telegram: cuándo usar cada uno, reglas y qué permite cada modo.
Elegir un modo es como elegir un **agente con insignia (bot)** o **tu propia voz (cuenta)**: el bot es la ruta recomendada; una cuenta personal es una excepción con más responsabilidad.
## ¿Bot o cuenta personal?
Cada instancia de Telegram en Notifique utiliza **uno** de dos modos. No puedes cambiar en la misma línea; si necesitas cambiar, **crea una nueva**.
| | **Bot (`BOT`)** | **Cuenta personal (`USER`)** |
| -------------------------- | --------------------------------------------------- | -------------------------------------- |
| Qué es | Bot creado vía [@BotFather](https://t.me/BotFather) | Sesión de su cuenta humana de Telegram |
| Credencial | **Token** (`123456:ABC…`) | **QR** o **cadena de sesión** |
| Mejor para | Producción, soporte, notificaciones | Legado o casos que un bot no cubre |
| Estado tras crear | **ACTIVE** (token válido) | **PENDING** hasta el login |
| Identidad en el chat | `@mybot` | Su perfil / número |
| Webhooks de emparejamiento | No | `telegram.instance.*` |
### Cuándo usar un bot
* Soporte, OTP, confirmaciones y automatización explícita
* Flujos alineados con la **Bot API** documentada
* Quiere que los clientes hablen con **@mybot**, no con una persona
### Cuándo usar una cuenta personal
* Un bot **no encaja** en el caso de uso (flujo heredado, actuar como persona en un chat específico)
* Acepta **términos** (`acceptUserTerms: true`) y el riesgo de infracciones de los ToS si abusa
Automatizar una cuenta de usuario para spam o mensajes directos masivos viola los **Términos de Telegram** y puede provocar que la cuenta sea prohibida. Prefiera un **bot** siempre que sea posible.
***
## Regla de oro del bot: el usuario habla primero
En la **API del bot**, Telegram bloquea los mensajes directos fríos del bot a usuarios que nunca interactuaron.
1. El destinatario abre el bot y envía **`/start`** (o toca Iniciar).
2. Notifique registra el chat (webhook + lista `GET /v1/telegram/chats`).
3. Luego envías con `chatId` o `@username` en `to`.
El envío anterior puede fallar con chat no válido o errores de bloqueo; comportamiento esperado de Telegram.
Los grupos y canales tienen reglas diferentes (es posible que el bot deba ser administrador o miembro). Para DM 1 a 1, trate **`/start`** como parte de la incorporación de su producto.
***
## Modo bot en detalle
**Cómo conectarse**
1. Cree el bot en [@BotFather](https://t.me/BotFather) y copie el token.
2. `POST /v1/telegram/instances` con `mode: "BOT"` y `botToken`.
3. Notifique valida el token y configura el webhook del bot.
4. Estado **ACTIVE**, puede enviar (a usuarios que ya iniciaron un chat).
**En qué destacan los bots**
* Entrante predecible (`telegram.received`)
* Lista de chats (`GET /v1/telegram/chats`)
* Envíos de ubicación (`type: location`)
* Identidad clara para los usuarios finales
**Limitaciones**
* No se puede iniciar un chat en frío sin `/start`
* Funciones limitadas a la superficie de Bot API
* No es su cuenta personal
***
## Modo de cuenta personal en detalle
**Cómo conectarse**
1. `POST /v1/telegram/instances` con `mode: "USER"` y `acceptUserTerms: true`.
2. La respuesta incluye el QR en **`connection`** (como WhatsApp no oficial); muestre `base64` o abra `loginUrl`.
3. Opcional: `generateShareableLink: true` al crear, o `POST .../connect-page/enable` después, para compartir `hostedUrl` con otra persona.
4. ¿QR caducado? `GET /v1/telegram/instances/:id/qr` o webhook `telegram.instance.qrcode`.
5. **Alternativa:** `POST .../session` con `sessionString` (útil con **2FA**).
6. Recuperar o invalidar el enlace: `GET/POST .../connect-page` (status, enable, rotate-secret, disable).
¿Integrar solo API (sin navegador en su servidor)? Utilice `generateShareableLink: true` en `POST /v1/telegram/instances` o habilítelo más tarde con `POST .../connect-page/enable`. Detalles en [Inicio rápido](/es/telegram-api/como-funciona/quick-start).
**Precauciones**
* El inicio de sesión con contraseña 2FA vía QR puede **no** funcionar; use sesión manual.
* **409** al solicitar QR: otro flujo de inicio de sesión ya está abierto (por ejemplo, panel SSE).
* Mientras esté **PENDING**, el envío no funciona.
Una cuenta personal es como prestar su identidad al sistema. Úsela solo cuando un bot no encaje.
***
## Comparación completa
| Función | Bot | Cuenta personal |
| ------------------------------ | :-: | :-------------: |
| Enviar texto | ✅ | ✅ |
| Medios vía URL HTTPS | ✅ | ✅ |
| Ubicación al enviar | ✅ | ⚠️ |
| Editar / eliminar mensaje | ✅ | ✅ |
| Programar / cancelar | ✅ | ✅ |
| `GET /v1/telegram/chats` | ✅ | ⚠️ |
| Entrante + `telegram.received` | ✅ | ✅ |
| Webhooks `telegram.instance.*` | ❌ | ✅ |
| Activo al crear | ✅ | ❌ |
| Primer contacto sin `/start` | ❌ | ⚠️\* |
\* Más libertad no reemplaza la suscripción voluntaria ni los ToS.
***
## Webhooks por modo
| Tipo | Bot | Cuenta personal |
| ------------------------------------- | --- | --------------- |
| `telegram.sent`, `telegram.failed`, … | ✅ | ✅ |
| `telegram.received` | ✅ | ✅ |
| `telegram.instance.connecting` | ❌ | ✅ |
| `telegram.instance.qrcode` | ❌ | ✅ |
| `telegram.instance.connected` | ❌ | ✅ |
| `telegram.instance.login_error` | ❌ | ✅ |
Lista y cargas útiles: [Eventos de webhook](/es/telegram-api/como-funciona/eventos-do-webhooks).
***
## Próximos pasos
* [Inicio rápido](/es/telegram-api/como-funciona/quick-start): pestañas **Bot** y **Cuenta personal**
* [Introducción](/es/telegram-api/como-funciona/introducao): descripción general del canal
* [Ámbitos de clave API](/es/telegram-api/como-funciona/escopos-api-key)