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

# Introdução

> Envie notificações, códigos e atendimento no Telegram pelo painel ou API, com bot ou conta pessoal, e acompanhe entrega e respostas.

<Tip>
  Telegram é o **canal direto no app**: avisos rápidos, bots de suporte e conversas sem depender de SMS ou WhatsApp.
</Tip>

## O que é Telegram na Notifique?

É o jeito de **falar com seus clientes no Telegram** sem montar infraestrutura do zero. Você conecta um **bot** (o caminho mais comum) ou, em casos específicos, uma **conta pessoal**, e passa a:

* **Enviar** texto, mídia por URL HTTPS e localização (conforme o modo)
* **Receber** mensagens no bot ou na conta e reagir com automação
* **Acompanhar** fila, status e falhas pela API ou [webhooks](/telegram-api/como-funciona/eventos-do-webhooks)
* **Editar ou apagar** mensagens já enviadas, quando o Telegram permitir

Pense no bot como um atendente com nome `@meubot`: previsível, documentado e ideal para produção.

<Note>
  O [Telegram Gateway](https://core.telegram.org/gateway) (SMS com código da Meta) é **outro produto**. Esta documentação é só para **mensagens dentro do app Telegram**.
</Note>

## Bot ou conta pessoal?

Cada instância é **ou bot ou conta**. Não dá para trocar o modo na mesma linha, se mudar de ideia, crie uma nova.

|                | **Bot (`BOT`)**                                               | **Conta pessoal (`USER`)**                                 |
| -------------- | ------------------------------------------------------------- | ---------------------------------------------------------- |
| O que é        | Bot oficial com token do [@BotFather](https://t.me/BotFather) | Sessão da **sua conta** humana (QR ou string)              |
| Indicado para  | Atendimento, notificações, automação                          | Casos em que o bot **não resolve**                         |
| Fica ativo     | Na hora, com token válido                                     | Depois do login (`PENDING` → `ACTIVE`)                     |
| Identidade     | `@meubot`                                                     | Seu perfil / número                                        |
| Risco e termos | Caminho **recomendado** (Bot API)                             | Exige `acceptUserTerms`; uso abusivo viola ToS do Telegram |

Comparativo completo e quando migrar: [Modos de conexão](/telegram-api/como-funciona/modos-de-conexao).

## Regras que todo integrador precisa saber

### No modo bot (o mais comum)

O Telegram **não deixa o bot puxar conversa do nada**. Em quase todos os casos:

1. O **usuário precisa falar primeiro**, abrir o bot e enviar `/start` (ou tocar em “Iniciar”).
2. Só depois o bot pode **responder e enviar** mensagens naquele chat.
3. Use `GET /v1/telegram/chats` para achar `chatId` e `@username` de quem já iniciou.

Isso não é limitação do Notifique: é política anti-spam da **Bot API** do Telegram.

### No modo conta pessoal

Você age com a **identidade da conta**. Automatizar DM em massa ou spam pode violar os **Termos de Serviço** do Telegram. Use só quando o bot não resolver e com responsabilidade. Login com **2FA** pode exigir **string de sessão** em vez de QR.

<Warning>
  Eventos de webhook no Telegram começam com **`telegram.*`**. No WhatsApp, é **`message.*`**. Se usar os dois canais, separe os handlers.
</Warning>

## Como conectar

1. **Crie uma instância** no painel ou API (bot com token ou conta com `acceptUserTerms`)
2. No **bot**, status fica **ACTIVE** na hora; na **conta**, a resposta já traz o **QR em `connection`**, ou use `generateShareableLink: true` para enviar o link a outra pessoa
3. **Envie** com `instanceId`, destino (`chatId` ou `@usuario`) e tipo de conteúdo

Passo a passo: [Quick Start](/telegram-api/como-funciona/quick-start) (abas **Bot** e **Conta pessoal**).

<Info>
  Cada **API Key** pertence a **um** workspace. Na v1 **não envie** `x-workspace-id`.
</Info>

## Comparativo: o que cada modo faz

| Funcionalidade                                     | Bot | Conta pessoal |
| -------------------------------------------------- | :-: | :-----------: |
| Enviar texto                                       |  ✅  |       ✅       |
| Enviar imagem, áudio, vídeo, documento (URL HTTPS) |  ✅  |       ✅       |
| Enviar localização                                 |  ✅  |       ⚠️      |
| Receber mensagens (inbound)                        |  ✅  |       ✅       |
| Listar chats do bot                                |  ✅  |       ⚠️      |
| Editar / apagar mensagem enviada                   |  ✅  |       ✅       |
| Agendar e cancelar envio                           |  ✅  |       ✅       |
| Webhooks de login (QR)                             |  ❌  |       ✅       |
| Primeiro contato sem o usuário iniciar             |  ❌  |      ⚠️\*     |
| Testar no sandbox                                  |  ✅  |       ✅       |

\* Conta pessoal tem mais liberdade, mas **não** é licença para spam. Respeite ToS e opt-in.

## Ciclo da mensagem

Depois do `POST`, a mensagem passa por `QUEUED` ou `SCHEDULED`, depois `SENT` ou `FAILED`. Engajamento (`READ`, `RESPONDED`, etc.) pode chegar depois via webhook. `SENT` significa que o Telegram aceitou, **não** que a pessoa leu.

OTP e alertas urgentes podem usar `"options": { "priority": "high" }`. Não abuse em campanha em massa.

## Depois de conectar

* **Envie** pelo painel ou `POST /v1/telegram/messages`
* **Liste chats** e inbound para montar atendimento
* **Configure** [webhooks](/telegram-api/como-funciona/eventos-do-webhooks) (`telegram.sent`, `telegram.received`, …)
* **Restrinja** a chave com `instanceIds` e escopos mínimos

## Próximos passos

* [Quick Start](/telegram-api/como-funciona/quick-start): bot ou conta pessoal
* [Modos de conexão](/telegram-api/como-funciona/modos-de-conexao): comparativo e regras
* [Escopos da API Key](/telegram-api/como-funciona/escopos-api-key): permissões
* [Eventos dos webhooks](/telegram-api/como-funciona/eventos-do-webhooks): o que chega na sua URL