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

# Quick Start

> From zero to your first Telegram send: choose bot or personal account and follow the steps.

<Tip>
  This guide takes you from **account to first send**. Pick **bot** for production, or **personal account** only when a bot does not fit.
</Tip>

## In brief

* **Bot:** [@BotFather](https://t.me/BotFather) token, instance **ACTIVE** immediately, the user must have sent **`/start`** first
* **Personal account:** create the instance, **scan the QR** (or share the link) until status is **ACTIVE**
* Both modes use the **same send API**; only the connection differs

Not sure which to pick? See [Connection modes](/en/telegram-api/como-funciona/modos-de-conexao).

## Before you start

* An **API key** (`sk_live_...` or `sk_test_...` for sandbox)
* Instance and send scopes on the key, [Scopes](/en/telegram-api/como-funciona/escopos-api-key)
* Replace `sk_live_xxxxx` and `https://api.notifique.dev` in examples

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

***

<Tabs>
  <Tab title="Bot">
    <Info>
      On Telegram, the **user must talk to the bot first** (`/start`). Without that, sends often fail, Bot API policy.
    </Info>

    ### 1. Connect the bot

    Three paths, pick what fits your integration:

    #### 1A, Via dashboard

    1. Telegram → New instance → **Bot**
    2. Paste the [@BotFather](https://t.me/BotFather) **token**
    3. When status is **active**, note the **instance id** and `@botUsername`

    #### 1B, Via API with token

    ```http theme={null}
    POST /v1/telegram/instances
    Content-Type: application/json
    Authorization: Bearer sk_live_xxxxx
    ```

    ```json theme={null}
    {
      "name": "My support bot",
      "mode": "BOT",
      "botToken": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
    }
    ```

    Expected response: **200** with **ACTIVE** status:

    ```json theme={null}
    {
      "success": true,
      "data": {
        "id": "clxx_inst_bot",
        "name": "My support bot",
        "status": "ACTIVE",
        "mode": "BOT",
        "botUsername": "@mybot",
        "webhookUrl": "https://api.notifique.dev/webhooks/telegram/clxx_inst_bot"
      }
    }
    ```

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

    <Info>
      `webhookUrl` is **informational**. Notifique already registers this endpoint with Telegram’s Bot API, you do **not** need to host or configure anything with that URL. It is for audit and debugging (where Telegram delivers updates).
    </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:

    ```http theme={null}
    GET /v1/telegram/chats?instanceId=clxx_inst&page=1&limit=20
    Authorization: Bearer sk_live_xxxxx
    ```

    Use `chatId` or `@username` from the response in `to`.

    ### 3. Send a text message

    ```http theme={null}
    POST /v1/telegram/messages
    Content-Type: application/json
    Authorization: Bearer sk_live_xxxxx
    ```

    ```json theme={null}
    {
      "instanceId": "clxx_inst_bot",
      "to": ["123456789"],
      "type": "text",
      "payload": { "message": "Hello! Test from Notifique." }
    }
    ```

    `to` is an **array** (up to **100** recipients). You can use `@username` if the chat already exists.

    Expected response: **202**:

    ```json theme={null}
    {
      "success": true,
      "data": {
        "messageIds": ["cltg1..."],
        "telegramIds": ["cltg1..."],
        "status": "QUEUED",
        "count": 1
      }
    }
    ```

    ### Send with template

    ```json theme={null}
    {
      "instanceId": "clxx_inst_bot",
      "to": ["123456789"],
      "type": "template",
      "payload": {
        "templateId": "TEMPLATE_ID",
        "variables": { "code": "482910" }
      }
    }
    ```

    See [template-api](/en/template-api/como-funciona/variaveis-disponiveis-e-crud).
  </Tab>

  <Tab title="Personal account">
    <Warning>
      Use a personal account **only** when a bot does not fit. Mass DM automation violates Telegram Terms. `acceptUserTerms: true` is required.
    </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:

    ```http theme={null}
    POST /v1/telegram/instances
    Content-Type: application/json
    Authorization: Bearer sk_live_xxxxx
    ```

    ```json theme={null}
    {
      "name": "Support account",
      "mode": "USER",
      "acceptUserTerms": true
    }
    ```

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

    ```json theme={null}
    {
      "success": true,
      "data": {
        "id": "clxx_inst_user",
        "name": "Support account",
        "status": "PENDING",
        "mode": "USER",
        "connection": {
          "status": "WAITING_QR",
          "loginUrl": "tg://login?token=...",
          "expiresSeconds": 30,
          "base64": "data:image/png;base64,..."
        },
        "code": "TELEGRAM_USER_PENDING_SESSION"
      }
    }
    ```

    Use `connection.base64` to show the **QR** in your UI or open `connection.loginUrl` in the Telegram app.

    #### 1C, Via API with link for the customer to scan

    Pass `generateShareableLink: true` to also get a hosted link, useful when the person scanning is not on your screen:

    ```http theme={null}
    POST /v1/telegram/instances
    Content-Type: application/json
    Authorization: Bearer sk_live_xxxxx
    ```

    ```json theme={null}
    {
      "name": "Support account",
      "mode": "USER",
      "acceptUserTerms": true,
      "generateShareableLink": true
    }
    ```

    Expected response: **200** with QR **and** shareable link:

    ```json theme={null}
    {
      "success": true,
      "data": {
        "id": "clxx_inst_user",
        "name": "Support account",
        "status": "PENDING",
        "mode": "USER",
        "connection": {
          "status": "WAITING_QR",
          "loginUrl": "tg://login?token=...",
          "expiresSeconds": 30,
          "base64": "data:image/png;base64,..."
        },
        "shareableLink": {
          "hostedUrl": "https://api.notifique.dev/w/instance-connect/...?token=...",
          "embedUrl": "https://api.notifique.dev/w/embed/instance-connect/...?token=...",
          "publicId": "..."
        },
        "code": "TELEGRAM_USER_PENDING_SESSION"
      }
    }
    ```

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

    <Warning>
      Anyone with the link can authenticate the session on this instance. After use, rotate the secret with `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:

    ```http theme={null}
    POST /v1/telegram/instances/clxx_inst_user/session
    Content-Type: application/json
    Authorization: Bearer sk_live_xxxxx
    ```

    ```json theme={null}
    {
      "sessionString": "YOUR_SESSION_STRING"
    }
    ```

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

    <Info>
      Summary: **dashboard** for the simplest path; **API with QR** to embed the code in your UI; **`generateShareableLink: true`** when someone else needs to scan; **session** when QR does not work.
    </Info>

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

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

    ```http theme={null}
    GET /v1/telegram/instances/clxx_inst_user/qr
    Authorization: Bearer sk_live_xxxxx
    ```

    While preparing (`CONNECTING`):

    ```json theme={null}
    {
      "success": true,
      "data": {
        "status": "CONNECTING",
        "loginUrl": null,
        "expiresSeconds": 0,
        "base64": null
      }
    }
    ```

    QR ready (`WAITING_QR`):

    ```json theme={null}
    {
      "success": true,
      "data": {
        "status": "WAITING_QR",
        "loginUrl": "tg://login?token=...",
        "expiresSeconds": 30,
        "base64": "data:image/png;base64,..."
      }
    }
    ```

    You can also receive a new QR via [webhook](/en/telegram-api/como-funciona/eventos-do-webhooks) (`telegram.instance.qrcode`).

    ### 3. Retrieve the shareable link later

    Lost the `hostedUrl` from create? Query or enable again, same pattern as WhatsApp:

    **Check status** (URLs only appear if the secret is still available on the server):

    ```http theme={null}
    GET /v1/telegram/instances/clxx_inst_user/connect-page
    Authorization: Bearer sk_live_xxxxx
    ```

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

    ```http theme={null}
    POST /v1/telegram/instances/clxx_inst_user/connect-page/enable
    Content-Type: application/json
    Authorization: Bearer sk_live_xxxxx
    ```

    ```json theme={null}
    {}
    ```

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

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

    ```http theme={null}
    POST /v1/telegram/instances/clxx_inst_user/connect-page/rotate-secret
    Authorization: Bearer sk_live_xxxxx
    ```

    **Disable the public page:**

    ```http theme={null}
    POST /v1/telegram/instances/clxx_inst_user/connect-page/disable
    Authorization: Bearer sk_live_xxxxx
    ```

    ### 4. Send a text message

    With an **ACTIVE** instance:

    ```http theme={null}
    POST /v1/telegram/messages
    Content-Type: application/json
    Authorization: Bearer sk_live_xxxxx
    ```

    ```json theme={null}
    {
      "instanceId": "clxx_inst_user",
      "to": ["123456789"],
      "type": "text",
      "payload": { "message": "Hello from the connected account." }
    }
    ```

    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](/en/telegram-api/como-funciona/eventos-do-webhooks)

## All send types

In the API reference (Telegram tab), open **Send Telegram message** and pick an example in the playground: Text, Image, Video, Audio, Document, Location, Template, Scheduled.

## Next steps

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