> ## 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.

# Introducción

> Envíe notificaciones, códigos y soporte en Telegram desde el panel o API, con un bot o una cuenta personal, y realice un seguimiento de la entrega y las respuestas.

<Tip>
  Telegram es el **canal directo en la aplicación**: alertas rápidas, bots de soporte y conversaciones sin depender de SMS o WhatsApp.
</Tip>

## ¿Qué es Telegram en Notifique?

Así es como **hablas con los clientes en Telegram** sin construir una infraestructura desde cero. Conectas un **bot** (la ruta más común) o, en casos específicos, una **cuenta personal**, y luego podrás:

* **Enviar** texto, medios a través de URL HTTPS y ubicación (según el modo)
* **Recibir** mensajes en el bot o la cuenta y reaccionar con automatización
* **Seguimiento** de colas, estados y fallas a través de API o [webhooks](/es/telegram-api/como-funciona/eventos-do-webhooks)
* **Editar o eliminar** mensajes enviados cuando Telegram lo permita

Piense en el bot como un agente de soporte llamado `@mybot`: predecible, documentado e ideal para producción.

<Note>
  [Telegram Gateway](https://core.telegram.org/gateway) (códigos Meta SMS) es un **producto diferente**. Esta documentación cubre **mensajes de Telegram dentro de la aplicación** únicamente.
</Note>

## ¿Bot o cuenta personal?

Cada instancia es **un bot o una cuenta**. No puedes cambiar de modo en la misma línea, si cambias de opinión, crea una nueva.

|                | **Bot (`BOT`)**                                                | **Personal account (`USER`)**                                 |
| -------------- | -------------------------------------------------------------- | ------------------------------------------------------------- |
| What it is     | Official bot with a [@BotFather](https://t.me/BotFather) token | **Your human account** session (QR or string)                 |
| Best for       | Support, notifications, automation                             | Cases where a bot **does not fit**                            |
| Becomes active | Immediately with a valid token                                 | After login (`PENDING` → `ACTIVE`)                            |
| Identity       | `@mybot`                                                       | Your profile / number                                         |
| Risk and terms | **Recommended** path (Bot API)                                 | Requires `acceptUserTerms`; abusive use violates Telegram ToS |

Comparativa completa: [Modos de conexión](/es/telegram-api/como-funciona/modos-de-conexao).

## Reglas que todo integrador debe conocer

### En modo bot (más común)

Telegram **no permite que el bot envíe mensajes directos en frío**. En casi todos los casos:

1. El **usuario debe hablar primero**, abrir el bot y enviar `/start` (o tocar “Iniciar”).
2. Solo entonces el bot podrá **responder y enviar** en ese chat.
3. Utilice `GET /v1/telegram/chats` para encontrar `chatId` y `@username` para usuarios que ya comenzaron.

Esta no es una limitación de Notifique: es una política antispam de **Bot API**.

### En modo cuenta personal

Actúas con la **identidad de cuenta**. La automatización de mensajes directos masivos o spam puede violar los **Términos de servicio** de Telegram. Úselo sólo cuando un bot no encaje y de manera responsable. **El inicio de sesión 2FA** puede requerir una **cadena de sesión** en lugar de QR.

<Warning>
  Los eventos de webhook de Telegram comienzan con **`telegram.*`**. En WhatsApp es **`message.*`**. Si utiliza ambos canales, mantenga a los controladores separados.
</Warning>

## Cómo conectarse

1. **Crea una instancia** en el panel o API (bot con token o cuenta con `acceptUserTerms`)
2. Para un **bot**, el estado es **ACTIVO** inmediatamente; para una **cuenta**, la respuesta ya incluye el **QR en `connection`**, o usa `generateShareableLink: true` para enviar el enlace a otra persona
3. **Enviar** con `instanceId`, destino (`chatId` o `@username`) y tipo de contenido

Paso a paso: [Inicio Rápido](/es/telegram-api/como-funciona/quick-start) (pestañas **Bot** y **Cuenta personal**).

<Info>
  Each **API Key** belongs to **one** workspace. On v1 **do not send** `x-workspace-id`.
</Info>

## Comparación: qué puede hacer cada modo

| Feature                                        | Bot | Personal account |
| ---------------------------------------------- | :-: | :--------------: |
| Send text                                      |  ✅  |         ✅        |
| Send image, audio, video, document (HTTPS URL) |  ✅  |         ✅        |
| Send location                                  |  ✅  |        ⚠️        |
| Receive messages (inbound)                     |  ✅  |         ✅        |
| List bot chats                                 |  ✅  |        ⚠️        |
| Edit / delete sent message                     |  ✅  |         ✅        |
| Schedule and cancel sends                      |  ✅  |         ✅        |
| Login webhooks (QR)                            |  ❌  |         ✅        |
| First contact without user initiating          |  ❌  |       ⚠️\*       |
| Sandbox testing                                |  ✅  |         ✅        |

\* Las cuentas personales tienen más libertad, pero eso **no** es permiso para enviar spam. Respete los Términos de Servicio y regístrese.

## Ciclo de vida del mensaje

Después de `POST`, el mensaje pasa por `QUEUED` o `SCHEDULED`, luego `SENT` o `FAILED`. La interacción (`READ`, `RESPONDED`, etc.) puede llegar más tarde a través del webhook. `SENT` significa que Telegram lo aceptó, **no** que la persona lo leyó.

OTP y alertas urgentes pueden usar `"options": { "priority": "high" }`. No lo abuse en campañas masivas.

## Después de conectarte

* **Enviar** desde el tablero o `POST /v1/telegram/messages`
* **Listar chats** y entrantes para crear flujos de soporte.
* **Configurar** [webhooks](/es/telegram-api/como-funciona/eventos-do-webhooks) (`telegram.sent`, `telegram.received`, …)
* **Restringir** la clave con `instanceIds` y alcances mínimos

## Próximos pasos

* [Inicio Rápido](/es/telegram-api/como-funciona/quick-start): bot o cuenta personal
* [Modos de conexión](/es/telegram-api/como-funciona/modos-de-conexao): comparativa y reglas
* [Ámbitos de clave API](/es/telegram-api/como-funciona/escopos-api-key): permisos
* [Eventos de webhook](/es/telegram-api/como-funciona/eventos-do-webhooks): qué llega a tu URL