​

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>",
    "body": "Welcome! Tap a button below to continue.",
    "metadata": {
      "type": "text",
      "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, document, and location. Set the send type in metadata; a photo, video, or document send needs mediaUrl, and a location send needs latitude / longitude.
• Inline + reply keyboards — inline_keyboard, reply_keyboard, plus force_reply and remove_keyboard.
• Callbacks — inline-keyboard button presses arrive as Telegram callback_query updates. Orbit ingests each press as an inbound message (the button’s callback_data becomes the message body), so it lands in the conversation timeline and fans out on the standard message.received webhook — the same event as any other inbound Telegram message. There is no separate telegram.callback event type to subscribe to.
• 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 (Orbit-side only) — PATCH /messages/:id edits the body and/or scheduled_at of a message that is still scheduled (not yet dispatched); once the message has been sent the edit returns 409 MESSAGE_NOT_EDITABLE. DELETE /messages/:id soft-deletes the Orbit message record and syncs that removal across your dashboards. Neither endpoint calls Telegram’s editMessageText / deleteMessage, so a message already delivered to the chat is not edited or removed in Telegram itself.
• Bot commands + deep links — 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 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

​

Blocked recipients

​

Pricing