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

curl https://api.orbit.devotel.io/api/v1/telegram/channel-state \
  -H "X-API-Key: dv_live_sk_your_key_here"

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

curl -X POST https://api.orbit.devotel.io/api/v1/telegram/test/start-verify \
  -H "X-API-Key: dv_live_sk_your_key_here"

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

{ "text": "Hello from Orbit" }

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

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

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" }'

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

curl -X POST https://api.orbit.devotel.io/api/v1/telegram/disconnect-bot \
  -H "X-API-Key: dv_live_sk_your_key_here"

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

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:

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

API Reference

All Endpoints

Telegram API

Telegram API

Channel state

Sandbox verification

Production bot

Demo content

Cost analytics

See also

​Telegram API

​Channel state

​Sandbox verification

​Production bot

​Demo content

​Cost analytics

​See also

Telegram API

Channel state

Sandbox verification

Production bot

Demo content

Cost analytics

See also