> ## 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 conexão

> Bot com token versus conta pessoal no Telegram: quando usar cada um, regras e o que cada modo permite.

<Tip>
  Escolher o modo é como escolher **atendente com crachá (bot)** ou **sua própria voz (conta)**: o bot é o caminho recomendado; a conta pessoal é exceção com mais responsabilidade.
</Tip>

## Bot ou conta pessoal?

Cada instância Telegram no Notifique usa **um** dos dois modos. Não dá para alternar na mesma linha: se precisar mudar, **crie uma nova**.

|                        | **Bot (`BOT`)**                                    | **Conta pessoal (`USER`)**              |
| ---------------------- | -------------------------------------------------- | --------------------------------------- |
| O que é                | Bot criado no [@BotFather](https://t.me/BotFather) | Sessão da sua conta humana no Telegram  |
| Credencial             | **Token** (`123456:ABC…`)                          | **QR** ou **string de sessão**          |
| Indicado para          | Produção, atendimento, notificações                | Legado ou caso em que o bot não resolve |
| Status após criar      | **ACTIVE** (token válido)                          | **PENDING** até login                   |
| Identidade no chat     | `@meubot`                                          | Seu perfil / número                     |
| Webhooks de pareamento | Não                                                | `telegram.instance.*`                   |

### Quando usar o bot

* Atendimento, OTP, confirmações e automações explícitas
* Fluxo alinhado à **Bot API** (documentada e estável)
* Você quer que o cliente fale com **@meubot**, não com uma pessoa

### Quando usar conta pessoal

* O bot **não atende** o caso de uso (fluxo legado, atuar como pessoa em chat específico)
* Você aceita os **termos** (`acceptUserTerms: true`) e o risco de violar ToS se abusar

<Warning>
  Automatizar conta de usuário para spam ou DM em massa viola os **Termos do Telegram** e pode resultar em banimento. Prefira **bot** sempre que possível.
</Warning>

***

## Regra de ouro do bot: o usuário fala primeiro

Na **Bot API**, o Telegram bloqueia mensagem “fria” do bot para quem nunca interagiu.

1. O destinatário abre o bot e envia **`/start`** (ou toca em Iniciar).
2. O Notifique registra o chat (webhook + lista em `GET /v1/telegram/chats`).
3. Aí sim você envia com `chatId` ou `@username` em `to`.

Se tentar enviar antes, a API pode falhar com erro de chat inválido ou bloqueio, comportamento esperado do Telegram.

<Info>
  Em grupos e canais as regras variam (bot precisa ser admin ou membro). Para DM 1 a 1, trate **`/start`** como parte do onboarding do seu produto.
</Info>

***

## Modo bot em detalhe

**Como conectar**

1. Crie o bot no [@BotFather](https://t.me/BotFather) e copie o token.
2. `POST /v1/telegram/instances` com `mode: "BOT"` e `botToken`.
3. O Notifique valida o token e configura o webhook do bot.
4. Status **ACTIVE**, pode enviar (para quem já iniciou conversa).

**O que o bot faz bem**

* Inbound previsível (`telegram.received`)
* Lista de chats (`GET /v1/telegram/chats`)
* Localização (`type: location`) no envio
* Identidade clara para o usuário final

**Limitações**

* Não “puxa” conversa sem `/start`
* Recursos limitados ao que a Bot API expõe
* Não é sua conta pessoal

***

## Modo conta pessoal em detalhe

**Como conectar**

1. `POST /v1/telegram/instances` com `mode: "USER"` e `acceptUserTerms: true`.
2. A resposta traz o QR em **`connection`** (como no WhatsApp não oficial), exiba `base64` ou abra `loginUrl`.
3. Opcional: `generateShareableLink: true` na criação, ou `POST .../connect-page/enable` depois, para repassar `hostedUrl` a outra pessoa.
4. QR expirou? `GET /v1/telegram/instances/:id/qr` ou webhook `telegram.instance.qrcode`.
5. **Alternativa:** `POST .../session` com `sessionString` (útil com **2FA**).
6. Recupere ou invalide o link: `GET/POST .../connect-page` (status, enable, rotate-secret, disable).

<Info>
  Integrando só pela API (sem browser no servidor)? Use `generateShareableLink: true` em `POST /v1/telegram/instances` ou habilite depois com `POST .../connect-page/enable`. Detalhes no [Quick Start](/telegram-api/como-funciona/quick-start).
</Info>

**Cuidados**

* Login com senha 2FA no QR pode **não** funcionar, use sessão manual.
* **409** ao pedir QR: outro fluxo de login já aberto (ex.: painel com SSE).
* Enquanto **PENDING**, envio não funciona.

<Note>
  Conta pessoal é como emprestar sua identidade ao sistema. Use só quando o bot não resolver.
</Note>

***

## Comparativo completo

| Funcionalidade                 | Bot | Conta pessoal |
| ------------------------------ | :-: | :-----------: |
| Enviar texto                   |  ✅  |       ✅       |
| Mídia por URL HTTPS            |  ✅  |       ✅       |
| Localização no envio           |  ✅  |       ⚠️      |
| Editar / apagar mensagem       |  ✅  |       ✅       |
| Agendar / cancelar             |  ✅  |       ✅       |
| `GET /v1/telegram/chats`       |  ✅  |       ⚠️      |
| Inbound + `telegram.received`  |  ✅  |       ✅       |
| Webhooks `telegram.instance.*` |  ❌  |       ✅       |
| Ativo na criação               |  ✅  |       ❌       |
| Primeiro contato sem `/start`  |  ❌  |      ⚠️\*     |

\* Mais liberdade não substitui opt-in e ToS.

***

## Webhooks por modo

| Tipo                                  | Bot | Conta pessoal |
| ------------------------------------- | --- | ------------- |
| `telegram.sent`, `telegram.failed`, … | ✅   | ✅             |
| `telegram.received`                   | ✅   | ✅             |
| `telegram.instance.connecting`        | ❌   | ✅             |
| `telegram.instance.qrcode`            | ❌   | ✅             |
| `telegram.instance.connected`         | ❌   | ✅             |
| `telegram.instance.login_error`       | ❌   | ✅             |

Lista e payloads: [Eventos dos webhooks](/telegram-api/como-funciona/eventos-do-webhooks).

***

## Próximos passos

* [Quick Start](/telegram-api/como-funciona/quick-start): abas **Bot** e **Conta pessoal**
* [Introdução](/telegram-api/como-funciona/introducao): visão geral do canal
* [Escopos da API Key](/telegram-api/como-funciona/escopos-api-key)