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

# Connection modes

> Bot with token versus personal Telegram account: when to use each, rules, and what each mode allows.

<Tip>
  Choosing a mode is like picking a **badge-wearing agent (bot)** or **your own voice (account)**: the bot is the recommended path; a personal account is an exception with more responsibility.
</Tip>

## Bot or personal account?

Each Telegram instance on Notifique uses **one** of two modes. You cannot switch on the same line, if you need to change, **create a new one**.

|                     | **Bot (`BOT`)**                                      | **Personal account (`USER`)**          |
| ------------------- | ---------------------------------------------------- | -------------------------------------- |
| What it is          | Bot created via [@BotFather](https://t.me/BotFather) | Session of your human Telegram account |
| Credential          | **Token** (`123456:ABC…`)                            | **QR** or **session string**           |
| Best for            | Production, support, notifications                   | Legacy or cases a bot cannot cover     |
| Status after create | **ACTIVE** (valid token)                             | **PENDING** until login                |
| Chat identity       | `@mybot`                                             | Your profile / number                  |
| Pairing webhooks    | No                                                   | `telegram.instance.*`                  |

### When to use a bot

* Support, OTP, confirmations, and explicit automation
* Flows aligned with the documented **Bot API**
* You want customers to talk to **@mybot**, not a person

### When to use a personal account

* A bot **does not fit** the use case (legacy flow, acting as a person in a specific chat)
* You accept **terms** (`acceptUserTerms: true`) and the risk of ToS violations if you abuse it

<Warning>
  Automating a user account for spam or mass DMs violates **Telegram Terms** and can get the account banned. Prefer a **bot** whenever possible.
</Warning>

***

## Golden bot rule: the user speaks first

On the **Bot API**, Telegram blocks cold DMs from the bot to users who never interacted.

1. The recipient opens the bot and sends **`/start`** (or taps Start).
2. Notifique records the chat (webhook + `GET /v1/telegram/chats` list).
3. Then you send with `chatId` or `@username` in `to`.

Sending before that may fail with invalid chat or block errors, expected Telegram behavior.

<Info>
  Groups and channels have different rules (bot may need to be admin or member). For 1-to-1 DM, treat **`/start`** as part of your product onboarding.
</Info>

***

## Bot mode in detail

**How to connect**

1. Create the bot in [@BotFather](https://t.me/BotFather) and copy the token.
2. `POST /v1/telegram/instances` with `mode: "BOT"` and `botToken`.
3. Notifique validates the token and configures the bot webhook.
4. Status **ACTIVE**, you can send (to users who already started a chat).

**What bots do well**

* Predictable inbound (`telegram.received`)
* Chat list (`GET /v1/telegram/chats`)
* Location sends (`type: location`)
* Clear identity for end users

**Limitations**

* Cannot cold-start a chat without `/start`
* Features limited to Bot API surface
* Not your personal account

***

## Personal account mode in detail

**How to connect**

1. `POST /v1/telegram/instances` with `mode: "USER"` and `acceptUserTerms: true`.
2. The response includes the QR in **`connection`** (like unofficial WhatsApp), show `base64` or open `loginUrl`.
3. Optional: `generateShareableLink: true` on create, or `POST .../connect-page/enable` later, to share `hostedUrl` with someone else.
4. QR expired? `GET /v1/telegram/instances/:id/qr` or webhook `telegram.instance.qrcode`.
5. **Alternative:** `POST .../session` with `sessionString` (useful with **2FA**).
6. Retrieve or invalidate the link: `GET/POST .../connect-page` (status, enable, rotate-secret, disable).

<Info>
  Integrating API-only (no browser on your server)? Use `generateShareableLink: true` on `POST /v1/telegram/instances` or enable later with `POST .../connect-page/enable`. Details in [Quick Start](/en/telegram-api/como-funciona/quick-start).
</Info>

**Cautions**

* 2FA password login via QR may **not** work, use manual session.
* **409** when requesting QR: another login flow already open (e.g. dashboard SSE).
* While **PENDING**, sending does not work.

<Note>
  A personal account is like lending your identity to the system. Use only when a bot does not fit.
</Note>

***

## Full comparison

| Feature                        | Bot | Personal account |
| ------------------------------ | :-: | :--------------: |
| Send text                      |  ✅  |         ✅        |
| Media via HTTPS URL            |  ✅  |         ✅        |
| Location on send               |  ✅  |        ⚠️        |
| Edit / delete message          |  ✅  |         ✅        |
| Schedule / cancel              |  ✅  |         ✅        |
| `GET /v1/telegram/chats`       |  ✅  |        ⚠️        |
| Inbound + `telegram.received`  |  ✅  |         ✅        |
| `telegram.instance.*` webhooks |  ❌  |         ✅        |
| Active on create               |  ✅  |         ❌        |
| First contact without `/start` |  ❌  |       ⚠️\*       |

\* More freedom does not replace opt-in and ToS.

***

## Webhooks by mode

| Type                                  | Bot | Personal account |
| ------------------------------------- | --- | ---------------- |
| `telegram.sent`, `telegram.failed`, … | ✅   | ✅                |
| `telegram.received`                   | ✅   | ✅                |
| `telegram.instance.connecting`        | ❌   | ✅                |
| `telegram.instance.qrcode`            | ❌   | ✅                |
| `telegram.instance.connected`         | ❌   | ✅                |
| `telegram.instance.login_error`       | ❌   | ✅                |

List and payloads: [Webhook events](/en/telegram-api/como-funciona/eventos-do-webhooks).

***

## Next steps

* [Quick Start](/en/telegram-api/como-funciona/quick-start): **Bot** and **Personal account** tabs
* [Introduction](/en/telegram-api/como-funciona/introducao): channel overview
* [API Key scopes](/en/telegram-api/como-funciona/escopos-api-key)