Errors worth branching on

These six failures cover the message send (POST /api/v1/messages/telegram) and bot onboarding, hammered by every auto-response in the chat flow. Each block below is a full { error, meta } envelope as the API returns it, and the matrix at the bottom answers retry vs surface for the same six classes. For the platform-wide decision table these branches plug into, see the error handling guide.

401 — Unauthorized

  {
    "error": {
      "code": "UNAUTHORIZED",
      "message": "The API key is invalid, expired, or lacks the required scope.",
      "status": 401
    },
    "meta": {
      "request_id": "req_telegrama1",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 401 on this page is the bearer key failing before the route ran — it never means the resource is wrong. Rotate the key or re-mint the scoped token; retrying the same request changes nothing.

403 — Forbidden

  {
    "error": {
      "code": "FORBIDDEN",
      "message": "The key is valid but does not have the scope this operation requires.",
      "status": 403
    },
    "meta": {
      "request_id": "req_telegrama1f",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 403 means the key authenticated but the operation is gated by scope — check the key’s scopes on the developer page; a 403 is never a data-not-found shape.

422 — Schema

  {
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "The request failed input validation.",
      "status": 422,
      "details": { "field": "chat_id", "value": "tg-0192", "expected": "a numeric chat id or @channel slug from the Telegram client" }
    },
    "meta": {
      "request_id": "req_telegramb2",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 422 means the payload did not match the request schema — branch on error.details.field and resend with the numeric chat id or the tenant-registered channel slug instead of blind-retrying the same body.

429 — Rate

  {
    "error": {
      "code": "RATE_LIMITED",
      "message": "Too many requests in the current window.",
      "status": 429,
      "details": { "retry_after": 12 }
    },
    "meta": {
      "request_id": "req_telegramc3",
      "timestamp": "2026-09-03T12:00:00Z",
      "docs_url": "https://docs.orbit.devotel.io/errors/RATE_LIMITED"
    }
  }

The Retry-After header and error.details.retry_after are both set on every 429 — resend the SAME request after the lower of the two.

402 — Feature gate

  {
    "error": {
      "code": "TELEGRAM_BOT_TOKEN_REVOKED",
      "message": "The Telegram bot token for this channel has been revoked upstream.",
      "status": 402,
      "details": { "bot_id": "bot_0192", "revoked_at": "2026-09-03T11:59:00Z" }
    },
    "meta": {
      "request_id": "req_telegramd4",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

Surface token renewal — resend only works after the re-auth webhook, not on replay.

409 — Bot already claimed

  {
    "error": {
      "code": "TELEGRAM_BOT_ALREADY_CONNECTED",
      "message": "The Telegram bot behind this token is already connected to another organization.",
      "status": 409,
      "details": { "bot_id": "bot_0192" }
    },
    "meta": {
      "request_id": "req_telegrame5",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 409 fires on POST /api/v1/telegram/connect-bot when the BotFather token you pasted resolves to a bot another organization already claimed. Disconnect the bot on the other organization first; for a token leak, revoke the token in BotFather and follow the ownership-disputes recovery flow. Retrying the same connect just re-raises the 409.

60-second retry matrix

Class	Meaning	Branch response
401 `UNAUTHORIZED`	the bearer key itself fails	Surface. Rotate the key or re-mint the scoped token; do not retry the same request.
403 `FORBIDDEN`	the key lacks this operation’s scope	Surface. Fix the key’s scope set; a retry with the same key never heals it.
422 `VALIDATION_ERROR`	the payload does not match the schema	Fix, then resend intentionally. Branch on `error.details.field`; a blind retry repeats the same 422.
429 `RATE_LIMITED`	the window quota is exhausted	Retry after `error.details.retry_after` (or the `Retry-After` header) with the same request body.
`TELEGRAM_BOT_ALREADY_CONNECTED` (409 conflict)	the bot token is claimed elsewhere	Surface. Disconnect the bot on the other organization, or revoke and re-issue the token in BotFather; a retry re-raises the same conflict.
`TELEGRAM_BOT_TOKEN_REVOKED` (402 feature gate)	Surface token renewal	Branch on `error.code`. Resend only works after the re-auth webhook, not on replay.

Worked request and response samples

The scanner flagged this page because the worked sections below shipped as bare <CodeGroup> blocks — no <RequestExample> wrappers for the samples index to count. Each it registers — send and state-read — now carries RequestExample over a six-language CodeGroup (cURL, Node SDK escape hatch, Python, Go, Ruby, PHP), paired with a ResponseExample success envelope. The errors matrix above is unchanged; the envelope it branches on is rendered here.

Send a message — POST /api/v1/messages/telegram

The copy-paste pair for the production send path. POST /api/v1/messages/telegram delivers to any numeric chat id or @channel slug your connected bot can reach — the recipient goes in to, the message text in body (both required) — unlike the onboarding POST /api/v1/telegram/test/send operation the generated block below documents (onboarding-only, no recipient parameter; see “Test send is onboarding-only” under this section).

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/messages/telegram" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "581234567",
    "body": "Your order OR-88231 has shipped.",
    "metadata": { "order_id": "OR-88231" }
  }'

Node.js

const res = await fetch('https://api.orbit.devotel.io/api/v1/messages/telegram', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    to: '581234567',
    body: 'Your order OR-88231 has shipped.',
    metadata: { order_id: 'OR-88231' },
  }),
})
const envelope = await res.json()
console.log(envelope.data.id, envelope.data.status)

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post(
    "https://api.orbit.devotel.io/api/v1/messages/telegram",
    headers=headers,
    json={
        "to": "581234567",
        "body": "Your order OR-88231 has shipped.",
        "metadata": {"order_id": "OR-88231"},
    },
)
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{
		"to": "581234567",
		"body": "Your order OR-88231 has shipped.",
		"metadata": {"order_id": "OR-88231"}
	}`)
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/messages/telegram", bytes.NewBuffer(body))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/messages/telegram')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  to: '581234567',
  body: 'Your order OR-88231 has shipped.',
  metadata: { order_id: 'OR-88231' }
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/messages/telegram');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  'to' => '581234567',
  'body' => 'Your order OR-88231 has shipped.',
  'metadata' => ['order_id' => 'OR-88231'],
]));
echo curl_exec($ch);

{
  "data": {
    "id": "msg_01HZM3GK5E0Y4X9N7J2C0RPTD6",
    "status": "queued",
    "channel": "telegram",
    "to": "581234567",
    "body": "Your order OR-88231 has shipped.",
    "created_at": "2026-09-03T12:00:00Z"
  },
  "meta": {
    "request_id": "req_telegramsend01",
    "timestamp": "2026-09-03T12:00:00Z"
  }
}

A 202 means accepted, not delivered — the 200-response walkthrough of the onboarding test/send sample below explains WHEN the mode-aware test operation matters; production traffic uses the pair above.

Read the bot state — GET /api/v1/telegram/channel-state

cURL

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

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/telegram/channel-state', {
  method: 'GET',
  headers: { 'X-API-Key': process.env.ORBIT_API_KEY! },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/telegram/channel-state", headers=headers)
print(r.json())

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/telegram/channel-state", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/telegram/channel-state')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/telegram/channel-state');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
]);
echo curl_exec($ch);

{
  "data": {
    "mode": "production",
    "bot": {
      "username": "acme_support_bot",
      "display_name": "Acme Support",
      "bot_id": "bot_0192",
      "connected_at": "2026-09-01T10:00:00Z",
      "status": "active",
      "last_verified_at": "2026-09-03T11:30:00Z"
    }
  },
  "meta": {
    "request_id": "req_telegramstate01",
    "timestamp": "2026-09-03T12:00:00Z"
  }
}

The 404 evicted-id and 402 revoked-bot envelopes the errors section carries above map to this same read/send pair — TELEGRAM_BOT_TOKEN_REVOKED (402) is the state-read branch, TELEGRAM_CHANNEL_NOT_CONNECTED (409) is what the send raises when channel-state reports not_connected. Keep the lifecycle samples below ordered the same way.

Worked Telegram samples

The generated operations below carry the raw request/response schemas. This section walks the exact calls the dashboard and your integration make when they run the Telegram send/link flow: check channel state, send a message on the right mode, connect or disconnect your own bot, and watch the rollout cost. Each sample shows a curl request, a TypeScript fetch, and the 200 envelope the API returns. Four-hundred-series failures on these calls map to the branch list in the errors section above — resending is application-level when your handler replays a message (e.g. a chabot auto-response), so keep retries limited to 429 here.

1. Check channel state

GET /api/v1/telegram/channel-state is the call you make first, every time — the response tells you which mode the next four samples run in (not_connected → verifying → test_active → production). Bot details (username, status, connected_at) are only present in production mode; test counters only on test states.

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

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/telegram/channel-state', {
  method: 'GET',
  headers: { 'X-API-Key': process.env.ORBIT_API_KEY! },
})
console.log(await res.json())

A production envelope (the BYO bot block is the whole state):

200

{
  "data": {
    "mode": "production",
    "bot": {
      "username": "acme_support_bot",
      "display_name": "Acme Support",
      "bot_id": "bot_0192",
      "connected_at": "2026-09-01T10:00:00Z",
      "status": "active",
      "last_verified_at": "2026-09-03T11:30:00Z"
    }
  },
  "meta": {
    "request_id": "req_telegramstate01",
    "timestamp": "2026-09-03T12:00:00Z"
  }
}

A test_active envelope drops the bot block and surfaces the verified chat + counters that gate /test/send:

200

{
  "data": {
    "mode": "test_active",
    "verified_account": {
      "username": "acme_ops",
      "chat_id": "581234567",
      "verified_at": "2026-09-02T08:15:00Z"
    },
    "daily_test_sends": 3,
    "daily_test_limit": 100,
    "shared_bot_username": "orbit_devotel_test_bot"
  },
  "meta": {
    "request_id": "req_telegramstate02",
    "timestamp": "2026-09-03T12:00:00Z"
  }
}

A verifying mid-flow state carries the single-use linking token (verify_token) the FE renders as a deep link / QR — the same token POST /test/start-verify mints below.

2. Send a test message

POST /api/v1/telegram/test/send fires one message on the right delivery path for the mode: in production it goes out your own bot to the chat you verified in step 1; in test_active it goes out the shared platform bot and bumps the daily cap. The 409 TELEGRAM_CHANNEL_NOT_CONNECTED from sample 1 (before a bot is connected) is the guard the operation itself raises.

curl -X POST "https://api.orbit.devotel.io/api/v1/telegram/test/send" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Your order has shipped — tracking #OR-88231." }'

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/telegram/test/send', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ text: 'Your order has shipped — tracking #OR-88231.' }),
})
console.log(await res.json())

The successful envelope mirrors the shared sent / message_id / mode shape the send-schemas give:

200

{
  "data": {
    "sent": true,
    "message_id": "tg_msg_8f4d2a",
    "mode": "production"
  },
  "meta": {
    "request_id": "req_telegramsend01",
    "timestamp": "2026-09-03T12:00:00Z"
  }
}

3. Connect and disconnect your own bot

Bring-your-own-bot onboarding is two owner/admin/developer-gated calls: POST /api/v1/telegram/connect-bot accepts the BotFather token and mints the webhook; POST /api/v1/telegram/disconnect-bot revokes the webhook upstream and soft-deletes the row. The connected mode locks this page to production.

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": "1234567890:AAExampletokenstring_from_BotFather" }'

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/telegram/connect-bot', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ bot_token: process.env.TELEGRAM_BOT_TOKEN! }),
})
console.log(await res.json())

Successful connect envelope (the webhook URL is returned once — store it):

200

{
  "data": {
    "row_id": "tb_row_01",
    "bot_id": "bot_0192",
    "bot_username": "acme_support_bot",
    "webhook_url": "https://api.orbit.devotel.io/api/v1/webhooks/telegram/bot_0192",
    "mode": "production"
  },
  "meta": {
    "request_id": "req_telegramconnect01",
    "timestamp": "2026-09-03T12:00:00Z"
  }
}

Disconnect:

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

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/telegram/disconnect-bot', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.ORBIT_API_KEY! },
})
console.log(await res.json())

4. Watch the rollout cost

GET /api/v1/telegram/analytics/costs?days=30 (default window, clamp 1–90) returns the per-tenant Telegram cost rollup for the dashboard donut, so test-mode/street-traffic reads stay inside the same envelope discipline.

curl -X GET "https://api.orbit.devotel.io/api/v1/telegram/analytics/costs?days=30" \
  -H "X-API-Key: dv_live_sk_your_key_here"

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch(
  'https://api.orbit.devotel.io/api/v1/telegram/analytics/costs?days=30',
  {
    method: 'GET',
    headers: { 'X-API-Key': process.env.ORBIT_API_KEY! },
  },
)
console.log(await res.json())

For webhook-delivered events (inbound MO replies, DLR), register your endpoint on the webhooks page and verify X-Orbit-Signature before trusting the body — the full per-language verification handler is at Verify webhook signatures.

Lifecycle send-receive-analytics samples

The four samples above exercise the onboarding flow. These five cover the day-two lifecycle — the calls your integration makes once the bot is in production mode: send, receive, measure, and monitor.

1. Send a text message

POST /api/v1/messages/telegram accepts a message for delivery through the connected bot. The recipient to is the chat id you verified during onboarding (a numeric id, or the @channel slug for channels). The API enqueues the send and returns the Devotel message id, so your handler can track the DLR without holding the HTTP window open.

curl -X POST "https://api.orbit.devotel.io/api/v1/messages/telegram" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "581234567",
    "body": "Your order OR-88231 has shipped.",
    "metadata": {
      "order_id": "OR-88231"
    }
  }'

const res = await fetch('https://api.orbit.devotel.io/api/v1/messages/telegram', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    to: '581234567',
    body: 'Your order OR-88231 has shipped.',
    metadata: { order_id: 'OR-88231' },
  }),
})
const envelope = await res.json()
console.log(envelope.data.id, envelope.data.status)

202

{
  "data": {
    "id": "msg_01HZM3GK5E0Y4X9N7J2C0RPTD6",
    "status": "queued",
    "channel": "telegram",
    "to": "581234567",
    "body": "Your order OR-88231 has shipped.",
    "created_at": "2026-09-03T12:00:00Z"
  },
  "meta": {
    "request_id": "req_telegramlifecycle01",
    "timestamp": "2026-09-03T12:00:00Z"
  }
}

A 202 here means the message is accepted, not yet delivered — the lifecycle flips to delivered (or failed with an error code) on the DLR webhook. If the connection is not in production mode the same call raises the 409 TELEGRAM_CHANNEL_NOT_CONNECTED above, so keep the launch gate on sample 4 (bot profile reads).

2. Send rich content with inline buttons

The same endpoint carries one media attachment per message via media_url. Inline-keyboard buttons and captions travel in metadata — keep button capacity to two rows and let the captions come through the text surface, which is how Telegram renders rich messages in DM chats:

curl -X POST "https://api.orbit.devotel.io/api/v1/messages/telegram" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "581234567",
    "body": "Driver photo attached — confirm the pickup.",
    "media_url": "https://cdn.example.com/fleet/driver-912.jpg",
    "metadata": {
      "caption": "Driver photo attached — confirm the pickup.",
      "reply_markup": "{\"inline_keyboard\":[[{\"text\":\"Confirm pickup\",\"callback_data\":\"pickup:confirm\"},{\"text\":\"Reschedule\",\"callback_data\":\"pickup:reschedule\"}]]}"
    }
  }'

const res = await fetch('https://api.orbit.devotel.io/api/v1/messages/telegram', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    to: '581234567',
    body: 'Driver photo attached — confirm the pickup.',
    media_url: 'https://cdn.example.com/fleet/driver-912.jpg',
    metadata: {
      caption: 'Driver photo attached — confirm the pickup.',
      reply_markup: JSON.stringify({
        inline_keyboard: [
          [
            { text: 'Confirm pickup', callback_data: 'pickup:confirm' },
            { text: 'Reschedule', callback_data: 'pickup:reschedule' },
          ],
        ],
      }),
    },
  }),
})
console.log(await res.json())

The media URL must be publicly fetchable by the Bot API — signed CDN URLs need to stay valid for at least the delivery window (status stays queued until the Bot API acknowledges the attachment). The same shape works for video/… and document/… attachments — swap the media type in the URL, keep caption under 1024 characters.

3. Inbound webhook handler — /start makes it a conversation

Customer replies arrive on the HTTPS endpoint you register on the webhooks page. The handler below verifies the X-Orbit-Signature HMAC before answering a /start — the pattern every inbound surface repeats:

import { createHmac, timingSafeEqual } from 'node:crypto'

export async function POST(req: Request) {
  // 1. Reject unsigned bodies before parsing — signature covers the raw body.
  const body = await req.text()
  const signature = req.headers.get('x-orbit-signature') ?? ''
  const expected = createHmac('sha256', process.env.ORBIT_WEBHOOK_SECRET!)
    .update(body)
    .digest('hex')
  const sigOk = signature.length === expected.length &&
    timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
  if (!sigOk) return new Response('invalid signature', { status: 401 })

  // 2. Branch on the inbound event — answer /start, log everything else.
  const event = JSON.parse(body)
  if (event.type === 'telegram.message.inbound' && event.data.text === '/start') {
    await fetch('https://api.orbit.devotel.io/api/v1/messages/telegram', {
      method: 'POST',
      headers: {
        'X-API-Key': process.env.ORBIT_API_KEY!,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        to: event.data.chat_id,
        body: 'Welcome — reply with your order number or type "help".',
      }),
    })
  }
  return new Response('ok', { status: 200 })
}

Return 200 promptly — the webhook surface re-delivers with backoff on non-2xx, so the reply send belongs behind an async queue the moment the handler grows past a trivial auto-answer. The same signature pattern is written out per SDK language at Verify webhook signatures.

4. Read channel analytics

GET /api/v1/analytics/telegram is the Telegram-only KPI surface the generic per-channel rollup can’t express — the Bot API has no carrier DLR, so the funnel counters you care about are outbound volume, the bot-blocked share (users who blocked the bot or closed the chat), custom-emoji usage, and the group-vs-DM split:

curl -X GET "https://api.orbit.devotel.io/api/v1/analytics/telegram?days=7" \
  -H "X-API-Key: dv_live_sk_your_key_here"

const res = await fetch(
  'https://api.orbit.devotel.io/api/v1/analytics/telegram?days=7',
  {
    method: 'GET',
    headers: { 'X-API-Key': process.env.ORBIT_API_KEY! },
  },
)
console.log(await res.json())

200

{
  "data": {
    "totals": {
      "total_outbound": 12840,
      "bot_blocked_count": 213,
      "bot_blocked_rate": 1.66,
      "custom_emoji_count": 640,
      "custom_emoji_rate": 4.98
    },
    "group_vs_dm": {
      "dm": 9120,
      "non_dm": 3720,
      "by_chat_type": [
        { "chat_type": "private", "message_count": 9120 },
        { "chat_type": "supergroup", "message_count": 2400 },
        { "chat_type": "group", "message_count": 1320 }
      ]
    },
    "trend": [
      {
        "period": "2026-08-29",
        "total_outbound": 1832,
        "bot_blocked_count": 31,
        "custom_emoji_count": 92
      },
      {
        "period": "2026-08-30",
        "total_outbound": 1904,
        "bot_blocked_count": 28,
        "custom_emoji_count": 101
      }
    ]
  },
  "meta": {
    "request_id": "req_telegramanalytics01",
    "timestamp": "2026-09-03T12:00:00Z"
  }
}

Branch on bot_blocked_rate — when it climbs past your baseline the bot is being blocked by users, and the fix is content-side (fewer messages, deeper opt-out), not transport-side. The response is cached for 60s, so dashboards can poll it per page-load without per-user cost.

5. Bot profile reads — health before the first send

The connect call returns the bot profile once; GET /api/v1/telegram/channel-state re-reads it on demand, which is the right pre-send check for any automated sender (an “is the bot still connected and active?” gate that catches a revoked token before the first send attempt of the run).

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

// Gate a send batch on the bot being connected — fail the run BEFORE
// the first send attempt, not on the first 409.
const state = await fetch(
  'https://api.orbit.devotel.io/api/v1/telegram/channel-state',
  { headers: { 'X-API-Key': process.env.ORBIT_API_KEY! } },
).then((r) => r.json())

const bot = state.data.bot
if (state.data.mode !== 'production' || bot?.status !== 'active') {
  throw new Error('Telegram bot not in production-active mode — aborting batch')
}
console.log(`bot @${bot.username} (${bot.bot_id}) connected since ${bot.connected_at}`)

200

{
  "data": {
    "mode": "production",
    "bot": {
      "username": "acme_support_bot",
      "display_name": "Acme Support",
      "bot_id": "bot_0192",
      "connected_at": "2026-09-01T10:00:00Z",
      "status": "active",
      "last_verified_at": "2026-09-03T11:30:00Z"
    }
  },
  "meta": {
    "request_id": "req_telegramstate03",
    "timestamp": "2026-09-03T12:00:00Z"
  }
}

Chat-level reads are analytics-history reads, not bot-state reads — after a bot connects, the contacts your messages create sync into the Contacts surface via the inbound webhook; browse recent chats from the Contacts API rather than polling Telegram directly. The production-only bot block above is the single source of truth for connection health on this page.

Test send is onboarding-only

POST /api/v1/telegram/test/send (the “Send Telegram test message” operation generated below) is an onboarding-only endpoint: it delivers exactly one message to the chat you verified during onboarding and takes no recipient or chat_id parameter — the only required body field is text (1–1024 characters). For production delivery to any chat id or @channel slug your bot can reach, use POST /api/v1/messages/telegram — worked sample in “Send a message” at the top of this page. The success envelope the send returns (the same shape the worked send section shows):

200

{
  "data": {
    "sent": true,
    "message_id": "tg_msg_8f4d2a",
    "mode": "production"
  },
  "meta": {
    "request_id": "req_telegramsend02",
    "timestamp": "2026-09-03T12:00:00Z"
  }
}

A successful POST /api/v1/telegram/connect-bot (required body bot_token, the BotFather token) returns the connected-bot profile along with the webhook URL — returned once at connect time, and re-readable any time from GET /api/v1/telegram/channel-state:

200

{
  "data": {
    "row_id": "tb_row_01",
    "bot_id": "bot_0192",
    "bot_username": "acme_support_bot",
    "webhook_url": "https://api.orbit.devotel.io/api/v1/webhooks/telegram/bot_0192",
    "mode": "production"
  },
  "meta": {
    "request_id": "req_telegramconnect02",
    "timestamp": "2026-09-03T12:00:00Z"
  }
}

And the GET /api/v1/telegram/analytics/costs rollup that feeds the dashboard donut (per-tenant cost estimate; Telegram currently bills at $0):

200

{
  "data": {
    "totalEstimated": 0,
    "currency": "USD",
    "breakdown": {
      "free": { "count": 42, "estimated": 0 },
      "test": { "count": 3, "estimated": 0 }
    },
    "disclaimer": "Telegram delivery currently bills at $0; totals are estimates."
  },
  "meta": {
    "request_id": "req_telegramcosts01",
    "timestamp": "2026-09-03T12:00:00Z"
  }
}

API Reference

All Endpoints

Errors worth branching on