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

# Introduction

> Send notifications, codes, and support on Telegram from the dashboard or API, with a bot or personal account, and track delivery and replies.

<Tip>
  Telegram is the **in-app direct channel**: fast alerts, support bots, and conversations without relying on SMS or WhatsApp.
</Tip>

## What is Telegram on Notifique?

It's how you **talk to customers on Telegram** without building infrastructure from scratch. You connect a **bot** (the most common path) or, in specific cases, a **personal account**, and then you can:

* **Send** text, media via HTTPS URL, and location (depending on mode)
* **Receive** messages on the bot or account and react with automation
* **Track** queue, status, and failures via API or [webhooks](/en/telegram-api/como-funciona/eventos-do-webhooks)
* **Edit or delete** sent messages when Telegram allows it

Think of the bot as a support agent named `@mybot`: predictable, documented, and ideal for production.

<Note>
  [Telegram Gateway](https://core.telegram.org/gateway) (Meta SMS codes) is a **different product**. This documentation covers **in-app Telegram messages** only.
</Note>

## Bot or personal account?

Each instance is **either a bot or an account**. You cannot switch mode on the same line, if you change your mind, create a new one.

|                | **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 |

Full comparison: [Connection modes](/en/telegram-api/como-funciona/modos-de-conexao).

## Rules every integrator should know

### In bot mode (most common)

Telegram **does not let the bot cold-DM users**. In almost all cases:

1. The **user must speak first**, open the bot and send `/start` (or tap “Start”).
2. Only then can the bot **reply and send** in that chat.
3. Use `GET /v1/telegram/chats` to find `chatId` and `@username` for users who already started.

This is not a Notifique limitation: it is **Bot API** anti-spam policy.

### In personal account mode

You act with the **account identity**. Automating mass DMs or spam can violate Telegram **Terms of Service**. Use only when a bot does not fit, and responsibly. **2FA** login may require a **session string** instead of QR.

<Warning>
  Telegram webhook events start with **`telegram.*`**. On WhatsApp, it is **`message.*`**. If you use both channels, keep handlers separate.
</Warning>

## How to connect

1. **Create an instance** in the dashboard or API (bot with token or account with `acceptUserTerms`)
2. For a **bot**, status is **ACTIVE** right away; for an **account**, the response already includes the **QR in `connection`**, or use `generateShareableLink: true` to send the link to someone else
3. **Send** with `instanceId`, destination (`chatId` or `@username`), and content type

Step by step: [Quick Start](/en/telegram-api/como-funciona/quick-start) (**Bot** and **Personal account** tabs).

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

## Comparison: what each mode can do

| 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                                |  ✅  |         ✅        |

\* Personal accounts have more freedom, but that is **not** permission to spam. Respect ToS and opt-in.

## Message lifecycle

After `POST`, the message goes through `QUEUED` or `SCHEDULED`, then `SENT` or `FAILED`. Engagement (`READ`, `RESPONDED`, etc.) may arrive later via webhook. `SENT` means Telegram accepted it, **not** that the person read it.

OTP and urgent alerts can use `"options": { "priority": "high" }`. Do not overuse on mass campaigns.

## After you connect

* **Send** from the dashboard or `POST /v1/telegram/messages`
* **List chats** and inbound to build support flows
* **Set up** [webhooks](/en/telegram-api/como-funciona/eventos-do-webhooks) (`telegram.sent`, `telegram.received`, …)
* **Restrict** the key with `instanceIds` and minimal scopes

## Next steps

* [Quick Start](/en/telegram-api/como-funciona/quick-start): bot or personal account
* [Connection modes](/en/telegram-api/como-funciona/modos-de-conexao): comparison and rules
* [API Key scopes](/en/telegram-api/como-funciona/escopos-api-key): permissions
* [Webhook events](/en/telegram-api/como-funciona/eventos-do-webhooks): what hits your URL