Skip to main content

Documentation Index

Fetch the complete documentation index at: https://orbit-docs.devotel.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Telegram

Orbit’s Telegram channel wraps the Telegram Bot API so you can send and receive messages, photos, documents, inline keyboards, and callbacks from the same unified Messaging surface used for every other channel. Each Orbit organization can attach one or more bots; webhook delivery is automatic.

​
Send a message

curl -X POST https://orbit-api.devotel.io/api/v1/messages/telegram \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "<chat_id>",
    "from": "<your_bot_username>",
    "type": "text",
    "text": "Welcome! Tap a button below to continue.",
    "reply_markup": {
      "inline_keyboard": [
        [
          { "text": "Order status", "callback_data": "order_status" },
          { "text": "Talk to an agent", "callback_data": "human_handoff" }
        ]
      ]
    }
  }'

​
Response

{
  "data": {
    "message_id": "msg_tg_abc123",
    "status": "sent",
    "channel": "telegram"
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2026-05-09T00:00:00Z"
  }
}

​
Capabilities

  • Text + media — text (with HTML / MarkdownV2 formatting), photo, video, audio, document, voice, animation, sticker.
  • Inline + reply keyboards — inline_keyboard, reply_keyboard, plus force_reply and remove_keyboard.
  • Callbacks — callback_query events surfaced as telegram.callback webhooks; auto-answerCallbackQuery is handled by Orbit so the spinner clears in the user’s client.
  • Chat actions — typing, upload_photo, etc., either via the API or auto-emitted by Orbit when a long-running send is in flight.
  • Edit + delete — the PATCH /messages/:id and DELETE /messages/:id endpoints translate to editMessageText and deleteMessage.
  • Inline mode + bot commands — registered via the bot setup wizard; /start deep-links land on your conversation routing rules.
  • Webhook security — Telegram’s secret_token header is validated against the per-bot secret stored in Orbit’s encrypted credential vault.

​
Onboarding flow

  1. Talk to @BotFather and create a bot. Save the token it returns.
  2. From the dashboard, navigate to Channels → Telegram → Add bot and paste the token.
  3. Orbit auto-registers the webhook URL https://orbit-api.devotel.io/api/v1/webhooks/inbound/telegram and rotates the secret_token header value.
  4. Optional: configure inline mode and the bot command list directly from the channel detail page.

​
Common errors

CodeHTTPCauseFix
TG_INVALID_TOKEN401The bot token has been revoked or rotated by BotFather.Issue a new token via /revoke in BotFather, then update credentials in the dashboard.
TG_CHAT_NOT_FOUND404The chat id no longer exists or the user has blocked the bot.Skip the recipient; this is permanent until the user re-engages.
TG_FORBIDDEN_BY_USER403The user has explicitly blocked the bot.Mark the contact as opted-out; do not retry.
TG_FILE_TOO_LARGE413Attachment exceeds 50 MB (text-API) / 2 GB (Bot API).Use the file upload endpoint to chunk, or host externally and send a URL.
TG_FLOOD_WAIT429Too many requests in a short window.Honour the Retry-After header — Telegram’s flood-control is strict.

​
Pricing

The Telegram Bot API itself is free. Orbit charges a flat per-1M platform fee for delivery and webhook fan-in. See the pricing page.