Quick Start

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

In brief

Bot: @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.

Before you start

An API key (sk_live_... or sk_test_... for sandbox)
Instance and send scopes on the key, Scopes
Replace sk_live_xxxxx and https://api.notifique.dev in examples

Just getting started? Use sk_test_... and check Sandbox.

Bot
Personal account

On Telegram, the user must talk to the bot first (/start). Without that, sends often fail, Bot API policy.

1. Connect the bot

Three paths, pick what fits your integration:

1A, Via dashboard

Telegram → New instance → Bot
Paste the @BotFather token
When status is active, note the instance id and @botUsername

1B, Via API with token

POST /v1/telegram/instances
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "name": "My support bot",
  "mode": "BOT",
  "botToken": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
}

Expected response: 200 with ACTIVE status:

{
  "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.

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

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:

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

POST /v1/telegram/messages
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "from": "clxx_inst_bot",
  "to": ["123456789"],
  "type": "text",
  "payload": { "message": "Hello! Test from Notifique." }
}

to is an array (up to 500 recipients). You can use @username if the chat already exists.Expected response: 202:

{
  "success": true,
  "data": {
    "messageIds": ["cltg1..."],
    "messageId": "cltg1...",
    "count": 1,
    "status": "QUEUED",
    "scheduledAt": null
  }
}

Send with template

{
  "from": "clxx_inst_bot",
  "to": ["123456789"],
  "type": "template",
  "payload": {
    "templateId": "TEMPLATE_ID",
    "variables": { "code": "482910" }
  }
}

See template-api.

Use a personal account only when a bot does not fit. Mass DM automation violates Telegram Terms. acceptUserTerms: true is required.

1. Create instance and connect

Four paths, pick what fits your integration:

1A, Via dashboard

Telegram → New instance → Account (USER)
Accept the displayed terms of use
Scan the QR in the Telegram app or open the login link
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:

POST /v1/telegram/instances
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "name": "Support account",
  "mode": "USER",
  "acceptUserTerms": true
}

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

{
  "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:

POST /v1/telegram/instances
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "name": "Support account",
  "mode": "USER",
  "acceptUserTerms": true,
  "generateShareableLink": true
}

Expected response: 200 with QR and shareable link:

{
  "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.

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.

1D, Via API with session string

Useful with 2FA or when interactive QR does not work, create the USER instance first, then:

POST /v1/telegram/instances/clxx_inst_user/session
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "sessionString": "YOUR_SESSION_STRING"
}

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

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.

2. Refresh the QR (if it expires)

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

GET /v1/telegram/instances/clxx_inst_user/qr
Authorization: Bearer sk_live_xxxxx

While preparing (CONNECTING):

{
  "success": true,
  "data": {
    "status": "CONNECTING",
    "loginUrl": null,
    "expiresSeconds": 0,
    "base64": null
  }
}

QR ready (WAITING_QR):

{
  "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 (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):

GET /v1/telegram/instances/clxx_inst_user/connect-page
Authorization: Bearer sk_live_xxxxx

Enable or regenerate (returns shareableLink):

POST /v1/telegram/instances/clxx_inst_user/connect-page/enable
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{}

Expected response: 200 with hostedUrl and embedUrl.Invalidate old links (if the link leaked or the customer already connected):

POST /v1/telegram/instances/clxx_inst_user/connect-page/rotate-secret
Authorization: Bearer sk_live_xxxxx

Disable the public page:

POST /v1/telegram/instances/clxx_inst_user/connect-page/disable
Authorization: Bearer sk_live_xxxxx

4. Send a text message

With an ACTIVE instance:

POST /v1/telegram/messages
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "from": "clxx_inst_user",
  "to": ["123456789"],
  "type": "text",
  "payload": { "message": "Hello from the connected account." }
}

Expected response: 202 (same shape as the Bot tab).

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

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.

Telegram API

Instances

Mensagens

Instâncias

In brief

Before you start

1. Connect the bot

1A, Via dashboard

1B, Via API with token

2. Ask the user to start the bot

3. Send a text message

Send with template

1. Create instance and connect

1A, Via dashboard

1B, Via API with QR in your UI

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

1D, Via API with session string

2. Refresh the QR (if it expires)

3. Retrieve the shareable link later

4. Send a text message

After your first send

All send types

Next steps

​In brief

​Before you start

​1. Connect the bot

​1A, Via dashboard

​1B, Via API with token

​2. Ask the user to start the bot

​3. Send a text message

​Send with template

​1. Create instance and connect

​1A, Via dashboard

​1B, Via API with QR in your UI

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

​1D, Via API with session string

​2. Refresh the QR (if it expires)

​3. Retrieve the shareable link later

​4. Send a text message

​After your first send

​All send types

​Next steps

In brief

Before you start

1. Connect the bot

1A, Via dashboard

1B, Via API with token

2. Ask the user to start the bot

3. Send a text message

Send with template

1. Create instance and connect

1A, Via dashboard

1B, Via API with QR in your UI

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

1D, Via API with session string

2. Refresh the QR (if it expires)

3. Retrieve the shareable link later

4. Send a text message

After your first send

All send types

Next steps