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

​

Send a message

curl -X POST https://api.orbit.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": {
    "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://api.orbit.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.

​

Token handling — your responsibility

• Never commit a bot token to git, public or private. GitHub and GitLab both surface tokens to search; bots have scraped them in seconds.
• Never paste a token into a chat, ticket, screenshot, or screen-share. Use the dashboard paste field, which masks the value after submit.
• Rotate immediately via /revoke in BotFather if you believe a token has been exposed. Old tokens stop working the moment a new one is issued; reconnect in Orbit with the new value and the existing conversation history is preserved (we key history by bot_id, not by the token).
• Scope each environment to its own bot. Use distinct BotFather bots for dev / staging / production so a leaked dev token doesn’t compromise customer conversations.

​

Ownership disputes

1. Revoke the token via BotFather (you, as the bot’s BotFather owner). Open @BotFather, select the bot, and run /revoke. BotFather issues a new token; the leaked token immediately stops working. The hostile tenant’s webhook registration is now dead — Telegram refuses every send / receive against the old token. Once the hostile claim is functionally inert, contact Orbit support (see step 2) to release the bot_id claim so you can connect with the new token.
2. Open an ownership-dispute ticket with Orbit support. Email support@devotel.io with subject Telegram bot ownership dispute — <bot_username> and include:
   • The bot’s @username and numeric bot_id (the digits before the colon in any token you’ve held).
   • Proof of BotFather ownership — a screenshot of the /mybots list in BotFather showing the bot under your Telegram account, OR a fresh token rotation timestamp from BotFather that we can correlate against Telegram’s getMe response on the live token.
   • The Orbit organization you want the bot claim transferred to.
   Support will verify your BotFather ownership against Telegram’s API, force-disconnect the hostile tenant’s row (revoking their webhook registration in the process), and unblock the bot_id so you can connect from your own Orbit organization. Median response time is one business day; security-sensitive disputes are escalated to on-call.

​

Common errors

​

Pricing