> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Telegram API

> Connect a Telegram bot to your organization, verify a chat with the shared sandbox bot, and read unified channel state. Sending production messages goes through the unified Messaging API.

# Telegram API

Telegram is a bring-your-own-bot channel. You onboard in two stages: first verify a chat against Orbit's shared sandbox bot so you can preview the experience, then connect your own bot — created with [@BotFather](https://t.me/BotFather) — for production traffic. This surface manages that lifecycle and exposes the unified channel state your dashboard renders.

**Base path:** `/api/v1/telegram`

**Authentication:** API key (`X-API-Key`) or session JWT. Write endpoints additionally require the `owner`, `admin`, or `developer` role.

## Channel state

Returns the current connection mode and the blocks the dashboard needs to render the right card. The `mode` field drives everything else in the response.

| Method | Path                             | Purpose                    |
| ------ | -------------------------------- | -------------------------- |
| `GET`  | `/api/v1/telegram/channel-state` | Read unified channel state |

`mode` is one of:

| Mode            | Meaning                                                                    |
| --------------- | -------------------------------------------------------------------------- |
| `not_connected` | No sandbox chat verified and no production bot connected                   |
| `verifying`     | A linking token has been minted but no chat has completed verification yet |
| `test_active`   | A chat is verified against the shared sandbox bot                          |
| `production`    | A bring-your-own bot is connected and active                               |

```bash theme={null}
curl https://api.orbit.devotel.io/api/v1/telegram/channel-state \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

```json theme={null}
{
  "data": {
    "mode": "production",
    "bot": {
      "username": "acme_support_bot",
      "display_name": "acme_support_bot",
      "bot_id": "7654321098",
      "connected_at": "2026-06-18T10:04:00.000Z",
      "status": "active",
      "last_verified_at": "2026-06-18T10:04:00.000Z"
    },
    "shared_bot_username": "devotel_orbit_bot"
  },
  "request_id": "req_01J..."
}
```

In `test_active` mode the response carries `verified_account` plus the `daily_test_sends` / `daily_test_limit` counters that back the sandbox send meter (the shared bot is capped at 100 sends/day). In `verifying` mode it carries `verify_token`.

## Sandbox verification

Before connecting your own bot you can verify a chat against Orbit's shared sandbox bot. `start-verify` mints a single-use linking token and a deep link; the dashboard renders the deep link as a QR code. Open the link in Telegram and send `/start` to complete verification.

| Method | Path                                 | Purpose                          |
| ------ | ------------------------------------ | -------------------------------- |
| `POST` | `/api/v1/telegram/test/start-verify` | Mint a linking token + deep link |
| `POST` | `/api/v1/telegram/test/send`         | Send a one-off test message      |
| `POST` | `/api/v1/telegram/test/disconnect`   | Clear verified sandbox chats     |

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/telegram/test/start-verify \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

```json theme={null}
{
  "data": {
    "token": "tg_link_8f2c...",
    "deep_link": "https://t.me/devotel_orbit_bot?start=tg_link_8f2c...",
    "qr_code_value": "https://t.me/devotel_orbit_bot?start=tg_link_8f2c...",
    "expires_in_seconds": 300
  },
  "request_id": "req_01J..."
}
```

`test/send` is mode-aware. In `test_active` mode it delivers through the shared sandbox bot to your verified chat; in `production` mode it delivers through your own connected bot. The request body is the same in both cases:

```json theme={null}
{ "text": "Hello from Orbit" }
```

```json theme={null}
{
  "data": { "sent": true, "message_id": 4821, "mode": "production" },
  "request_id": "req_01J..."
}
```

`text` is 1–1024 characters. If no chat has been verified yet, `test/send` returns `409 TELEGRAM_CHANNEL_NOT_CONNECTED`.

`test/disconnect` clears verified sandbox chats and returns the resulting state. It accepts an optional `reason`:

```json theme={null}
{ "reason": "rotating test device" }
```

## Production bot

Connect your own bot for production traffic by pasting its token from @BotFather. Orbit encrypts the token before persistence, registers the webhook, and reads back the bot's identity.

| Method | Path                              | Purpose                                   |
| ------ | --------------------------------- | ----------------------------------------- |
| `POST` | `/api/v1/telegram/connect-bot`    | Connect a bring-your-own bot              |
| `POST` | `/api/v1/telegram/disconnect-bot` | Disconnect the bot and remove its webhook |

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/telegram/connect-bot \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "bot_token": "7654321098:AAH...your-botfather-token" }'
```

```json theme={null}
{
  "data": {
    "row_id": "tgc_01J...",
    "bot_id": "7654321098",
    "bot_username": "acme_support_bot",
    "webhook_url": "https://api.orbit.devotel.io/webhooks/telegram/...",
    "mode": "production"
  },
  "request_id": "req_01J..."
}
```

`bot_token` is the 20–120 character token issued by @BotFather. Disconnecting removes the webhook and soft-deletes the stored credentials:

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/telegram/disconnect-bot \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

```json theme={null}
{
  "data": { "disconnected": true },
  "request_id": "req_01J..."
}
```

## Demo content

Returns a static demo pack the dashboard uses to preview the channel before a bot is connected.

| Method | Path                            | Purpose                    |
| ------ | ------------------------------- | -------------------------- |
| `GET`  | `/api/v1/telegram/demo-content` | Read the channel demo pack |

## Cost analytics

Returns an estimated cost rollup for your outbound Telegram messages over a time window you choose, broken down by tier. Sending on Telegram is free today, so totals return `$0.00` — use this endpoint to track your Telegram send volume alongside the cost reports for your other channels.

| Method | Path                               | Purpose                       |
| ------ | ---------------------------------- | ----------------------------- |
| `GET`  | `/api/v1/telegram/analytics/costs` | Read estimated Telegram costs |

The `days` query parameter controls the rollup window:

```bash theme={null}
curl https://api.orbit.devotel.io/api/v1/telegram/analytics/costs?days=7 \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

| Parameter | Type    | Range | Default | Description             |
| --------- | ------- | ----- | ------- | ----------------------- |
| `days`    | integer | 1–90  | 30      | Lookback window in days |

The response breaks down costs by tier:

```json theme={null}
{
  "data": {
    "totalEstimated": 0,
    "currency": "USD",
    "breakdown": {
      "free": {
        "count": 150,
        "estimated": 0
      },
      "test": {
        "count": 5,
        "estimated": 0
      }
    },
    "disclaimer": "Telegram is currently free at the provider level — the Telegram Bot API does not charge for outbound messages. Test-mode sends are counted separately from production sends."
  },
  "request_id": "req_01J..."
}
```

* `free`: Production Telegram messages sent through your connected bot (currently \$0.00)
* `test`: Messages sent in test mode through the sandbox bot, counted separately from production (currently \$0.00)

## See also

* [Verify API](/api-reference/verify) — Telegram is also available as a one-time-passcode delivery channel
* [Messaging API](/api-reference/endpoints/messaging) — send production Telegram messages once a bot is connected