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

# Inicio rápido

> De cero a tu primer envío de Telegram: elige bot o cuenta personal y sigue los pasos.

<Tip>
  Esta guía lo lleva desde **la cuenta hasta el primer envío**. Elija **bot** para producción o **cuenta personal** solo cuando un bot no encaje.
</Tip>

## En breve

* **Bot:** [@BotFather](https://t.me/BotFather) token, instancia **ACTIVA** inmediatamente, el usuario debe haber enviado **`/start`** primero
* **Cuenta personal:** crea la instancia, **escanea el QR** (o comparte el enlace) hasta que el estado sea **ACTIVO**
* Ambos modos utilizan la **misma API de envío**; solo la conexión difiere

¿No estás seguro de cuál elegir? Ver [Modos de conexión](/es/telegram-api/como-funciona/modos-de-conexao).

## Antes de empezar

* Una **clave API** (`sk_live_...` o `sk_test_...` para sandbox)
* Instancia y envío de alcances en la clave, [Scopes](/es/telegram-api/como-funciona/escopos-api-key)
* Reemplace `sk_live_xxxxx` y `https://api.notifique.dev` en los ejemplos.

<Note>
  Just getting started? Use `sk_test_...` and check [Sandbox](/es/guides/sandbox/index).
</Note>

***

<Tabs>
  <Tab title="Bot">
    <Info>
      En Telegram, el **usuario debe hablar primero con el bot** (`/start`). Sin eso, los envíos suelen fallar, política de Bot API.
    </Info>

    ### 1. Conecta el bot

    Tres caminos, elige el que mejor se adapte a tu integración:

    #### 1A, a través del tablero

    1. Telegram → Nueva instancia → **Bot**
    2. Pegue el [@BotFather](https://t.me/BotFather) **token**
    3. Cuando el estado es **activo**, tenga en cuenta el **ID de instancia** y `@botUsername`.

    #### 1B, vía API con token

    Respuesta esperada: **200** con estado **ACTIVO**:

    Invalid token → `TELEGRAM_BOT_TOKEN_INVALID`. Save the **`id`**.

    <Info>
      `webhookUrl` es **informativo**. Notifique ya registra este punto final con la API Bot de Telegram, **no** necesita alojar ni configurar nada con esa URL. Es para auditoría y depuración (donde Telegram entrega actualizaciones).
    </Info>

    ### 2. Ask the user to start the bot

    Share `https://t.me/YOUR_BOT` and ask them to tap **Start** (`/start`).

    List users who already started:

    Utilice `chatId` o `@username` de la respuesta en `to`.

    ### 3. Envía un mensaje de texto

    `to` es una **matriz** (hasta **100** destinatarios). Puedes usar `@username` si el chat ya existe.

    Respuesta esperada: **202**:
  </Tab>

  <Tab title="Personal account">
    <Warning>
      Utilice una cuenta personal **sólo** cuando un bot no encaje. La automatización masiva de DM viola los términos de Telegram. Se requiere `acceptUserTerms: true`.
    </Warning>

    ### 1. Create instance and connect

    Four paths, pick what fits your integration:

    #### 1A, Via dashboard

    1. Telegram → New instance → **Account (USER)**
    2. Accept the displayed **terms of use**
    3. Scan the **QR** in the Telegram app or open the login link
    4. When status is **active**, note the **instance id**

    #### 1B, Via API with QR in your UI

    Creates the connection and returns the QR in `connection`, same idea as unofficial WhatsApp:

    Expected response: **200** with **PENDING** status and QR in `connection`:

    Utilice `connection.base64` para mostrar el **QR** en su interfaz de usuario o abra `connection.loginUrl` en la aplicación Telegram.

    #### 1C, vía API con enlace para que el cliente lo escanee

    Pase `generateShareableLink: true` para obtener también un enlace alojado, útil cuando la persona que escanea no está en su pantalla:

    Respuesta esperada: **200** con QR **y** enlace para compartir:

    Send `shareableLink.hostedUrl` to the customer. When they finish login, status becomes **active**.

    <Warning>
      Cualquiera que tenga el enlace puede autenticar la sesión en esta instancia. Después de su uso, gire el secreto con `POST /v1/telegram/instances/:instanceId/connect-page/rotate-secret`.
    </Warning>

    #### 1D, Via API with session string

    Useful with **2FA** or when interactive QR does not work, create the USER instance first, then:

    Instance becomes **ACTIVE**. **409** if QR is already running in parallel: `TELEGRAM_QR_LOGIN_IN_PROGRESS`.

    <Info>
      Resumen: **panel** para la ruta más sencilla; **API con QR** para incrustar el código en tu UI; **`generateShareableLink: true`** cuando alguien más necesita escanear; **sesión** cuando QR no funciona.
    </Info>

    ### 2. Refresh the QR (if it expires)

    QR codes expire quickly. Request a new one **without creating a new instance**:

    Mientras prepara (`CONNECTING`):

    QR ready (`WAITING_QR`):

    También puedes recibir un nuevo QR a través de [webhook](/es/telegram-api/como-funciona/eventos-do-webhooks) (`telegram.instance.qrcode`).

    ### 3. Recupera el enlace para compartir más tarde

    ¿Perdiste el `hostedUrl` de crear? Consultar o habilitar nuevamente, mismo patrón que WhatsApp:

    **Verificar estado** (Las URL solo aparecen si el secreto todavía está disponible en el servidor):

    **Enable or regenerate** (returns `shareableLink`):

    Expected response: **200** with `hostedUrl` and `embedUrl`.

    **Invalidate old links** (if the link leaked or the customer already connected):

    **Desactivar la página pública:**

    ### 4. Send a text message

    With an **ACTIVE** instance:

    Expected response: **202** (same shape as the Bot tab).
  </Tab>
</Tabs>

***

## After your first send

* **List sent:** `GET /v1/telegram/messages`
* **Cancel** in queue: `POST /v1/telegram/messages/:id/cancel` (`telegram.cancelled` webhook)
* **Inbound:** `GET /v1/telegram/messages/inbound`, configure in Settings → Received messages
* **Webhooks:** `telegram.sent`, `telegram.received`, `telegram.failed`, do **not** use `message.*` (WhatsApp). Guide: [Webhook events](/es/telegram-api/como-funciona/eventos-do-webhooks)

## Todos los tipos de envío

En la referencia de la API (pestaña Telegram), abra **Enviar mensaje en Telegram** y elija un ejemplo en el playground: Texto, Imagen, Vídeo, Audio, Documento, Ubicación, Plantilla, Programada.

## Próximos pasos

* [Introduction](/es/telegram-api/como-funciona/introducao)
* [Connection modes](/es/telegram-api/como-funciona/modos-de-conexao)
* [Scopes](/es/telegram-api/como-funciona/escopos-api-key)