Telegram Onboarding: Shared Test Bot to Your Own Bot

This guide walks you from an empty Telegram channel to a working, production-ready setup. It complements the Telegram channel page, which covers message shapes and capability detail — this guide is the ordered path you follow the first time, and re-run whenever you attach, rotate, or retire a bot. Telegram has no approval cycle and no brand registration. The only real gate is that a production bot is a BotFather bot that you own, and Orbit can only connect it via the token BotFather hands you. Until you have a token, the built-in test account lets you send real messages through Orbit’s shared bot so you can validate your integration today.

1. The test-account loop — send real messages today

The test account routes through Devotel’s shared, already-connected bot. You never touch BotFather to use it. Three steps:

Step 1: Start verification

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

The response carries a linking token, a deep link (https://t.me/<shared_bot>?start=<token>), and a QR-code value. Open the deep link (or scan the QR code) in Telegram on your device — the linked chat with the shared bot is what makes the channel test_active.

Step 2: Send a test message through the shared bot

curl -X POST https://api.orbit.devotel.io/api/v1/telegram/test/send \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "<linked_chat_id>",
    "body": "Test loop is live."
  }'

While the channel is test_active, the send goes out under the shared bot. Once you bring your own bot and the channel enters production mode, the same endpoint routes through your bot instead, so your integration code does not change between test and production. Check where you are at any point with GET /api/v1/telegram/channel-state — it returns the channel mode plus the verified-chat list when test-linked:

const response = await fetch('https://api.orbit.devotel.io/api/v1/telegram/channel-state', {
  headers: { 'X-API-Key': process.env.ORBIT_API_KEY },
})
const { data, meta } = await response.json()
console.log(data.mode, data.verified_chats, meta.request_id)

The successful response uses the standard envelope:

200

{
  "data": { "mode": "test_active", "verified_chats": ["<linked_chat_id>"] },
  "meta": { "request_id": "req_telegram_state_01", "timestamp": "2026-10-11T12:00:00.000Z" }
}

Step 3: Deliver demo flows while still test-scope

Test scope is enough to prove a group-keyword flow end to end: message a group that your shared-bot link is in, confirm the inbound message.received hits your webhook, then confirm your keyword router fires. The demo pack (GET /api/v1/telegram/demo-content) ships sample group-keyword and cost-rollup flows so you can validate rendering and routing before you commit a token. To reset the loop — for example, to point a different tester device at it later — call POST /api/v1/telegram/test/disconnect. Verified-chat links clear; the daily test quota carries over. The test account is for evaluation, not production: sends go out under the shared bot’s branding, not yours, and the quota is deliberately small. Move to your own bot below for anything a customer touches.

2. Bring your own bot (paste-token onboarding)

The production path is a single call once BotFather hands you a token.

Talk to @BotFather in Telegram and create a bot. Save the token it returns — treat it like a bearer credential (see Token handling on the channel page).
Connect the token to Orbit:

curl -X POST "https://api.orbit.devotel.io/api/v1/telegram/connect-bot" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token":"<botfather_token>"}'

const result = await client.request('POST', '/telegram/connect-bot', {
  body: { token: process.env.TELEGRAM_BOT_TOKEN },
})
console.log(result.data, result.meta.request_id)

import os

# client is your authenticated Orbit Python SDK client.
result = client.request(
    "POST", "/telegram/connect-bot",
    json={"token": os.environ["TELEGRAM_BOT_TOKEN"]},
)
print(result["data"], result["meta"]["request_id"])

On success, the response is a standard envelope; data confirms the connected bot and meta identifies the request:

200

{
  "data": {},
  "meta": { "request_id": "req_telegram_connect_01", "timestamp": "2026-10-11T12:00:00.000Z" }
}

One bot, one tenant: Orbit identifies a bot by its bot_id (the numeric prefix before the colon) and enforces a single-tenant claim. Once an Orbit organization connects a bot, the same bot_id cannot be connected to a second organization until the first disconnects — a second attempt returns 409 TELEGRAM_BOT_ALREADY_CONNECTED:

409 Error

{
  "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_telegram_conflict_01", "timestamp": "2026-10-11T12:00:00.000Z" }
}

Disconnect the bot from the other organization, or if you suspect the token leaked, revoke it in BotFather and follow the ownership disputes recovery paths. Retrying the same token without resolving ownership returns the same conflict.

Orbit registers the webhook subscription immediately: the bot is pointed at https://api.orbit.devotel.io/api/v1/webhooks/inbound/telegram, and the X-Telegram-Bot-Api-Secret-Token value Telegram must present is rotated and stored in Orbit’s encrypted credential vault. Inbound delivery is live from that call.

Access: /test/*, /connect-bot, and /disconnect-bot are write-class operations — they require the owner, admin, or developer role, not just a valid session.

3. Send with metadata — types, keyboards, and formatting

Sending goes through the unified Messaging surface (POST /api/v1/messages/telegram). The text body is the top-level body field; everything else — the send type, parse_mode, and keyboards — lives under metadata, whose values are all strings. Supported type values: text (default), photo, video, document, location. A photo, video, or document send needs metadata.mediaUrl; a location send needs metadata.latitude and metadata.longitude. Supply inline_keyboard and reply_keyboard as JSON-stringified button[][] arrays — one string, an outer array of rows, each row an array of button objects. parse_mode accepts HTML or MarkdownV2. A full send with a two-row inline keyboard. Each language keeps the keyboard as a JSON string inside metadata; do not pass the button rows as a nested object.

curl -X POST "https://api.orbit.devotel.io/api/v1/messages/telegram" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"<chat_id>","from":"<your_bot_username>","body":"Order #4471 shipped. Track it or talk to a human:","metadata":{"type":"text","parse_mode":"HTML","inline_keyboard":"[[{\"text\":\"Track shipment\",\"callback_data\":\"track_4471\"}],[{\"text\":\"Talk to an agent\",\"callback_data\":\"human_handoff\"}]]"}}'

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: '<chat_id>',
    from: '<your_bot_username>',
    body: 'Order #4471 shipped. Track it or talk to a human:',
    metadata: {
      type: 'text',
      parse_mode: 'HTML',
      inline_keyboard: JSON.stringify([
        [{ text: 'Track shipment', callback_data: 'track_4471' }],
        [{ text: 'Talk to an agent', callback_data: 'human_handoff' }],
      ]),
    },
  }),
})
console.log(await res.json())

import os
import json
import requests

payload = {
    "to": "<chat_id>",
    "from": "<your_bot_username>",
    "body": "Order #4471 shipped. Track it or talk to a human:",
    "metadata": {
        "type": "text",
        "parse_mode": "HTML",
        "inline_keyboard": json.dumps([
            [{"text": "Track shipment", "callback_data": "track_4471"}],
            [{"text": "Talk to an agent", "callback_data": "human_handoff"}],
        ]),
    },
}
response = requests.post(
    "https://api.orbit.devotel.io/api/v1/messages/telegram",
    headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
    json=payload,
)
print(response.json())

package main

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

func main() {
	keyboard, _ := json.Marshal([][]map[string]string{
		{{"text": "Track shipment", "callback_data": "track_4471"}},
		{{"text": "Talk to an agent", "callback_data": "human_handoff"}},
	})
	payload, _ := json.Marshal(map[string]any{
		"to": "<chat_id>", "from": "<your_bot_username>",
		"body": "Order #4471 shipped. Track it or talk to a human:",
		"metadata": map[string]string{
			"type": "text", "parse_mode": "HTML", "inline_keyboard": string(keyboard),
		},
	})
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/messages/telegram", bytes.NewReader(payload))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
}

require 'json'
require 'net/http'
require 'uri'

uri = URI('https://api.orbit.devotel.io/api/v1/messages/telegram')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV.fetch('ORBIT_API_KEY')
req['Content-Type'] = 'application/json'
req.body = {
  to: '<chat_id>', from: '<your_bot_username>',
  body: 'Order #4471 shipped. Track it or talk to a human:',
  metadata: {
    type: 'text', parse_mode: 'HTML',
    inline_keyboard: JSON.generate([
      [{ text: 'Track shipment', callback_data: 'track_4471' }],
      [{ text: 'Talk to an agent', callback_data: 'human_handoff' }],
    ]),
  },
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body

<?php
$keyboard = json_encode([
  [['text' => 'Track shipment', 'callback_data' => 'track_4471']],
  [['text' => 'Talk to an agent', 'callback_data' => 'human_handoff']],
]);
$payload = json_encode([
  'to' => '<chat_id>',
  'from' => '<your_bot_username>',
  'body' => 'Order #4471 shipped. Track it or talk to a human:',
  'metadata' => ['type' => 'text', 'parse_mode' => 'HTML', 'inline_keyboard' => $keyboard],
]);
$ch = curl_init('https://api.orbit.devotel.io/api/v1/messages/telegram');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
echo curl_exec($ch);

A successful request is accepted for delivery and returns the full response envelope:

202

{
  "data": { "id": "msg_01HZM3GK5E0Y4X9N7J2C0RPTD6", "status": "queued", "channel": "telegram", "to": "<chat_id>" },
  "meta": { "request_id": "req_telegram_send_01", "timestamp": "2026-10-11T12:00:00.000Z" }
}

force_reply and remove_keyboard use the same stringified-array convention when you want a forced text reply or a keyboard removed.

4. Inbound webhook — receive Telegram messages

A plain inbound message and an inline-keyboard press both arrive at your webhook as message.received on the telegram channel. For a button press, the button’s callback_data becomes the message body; there is no separate telegram.callback event to subscribe to.

import http from 'node:http'

const server = http.createServer((req, res) => {
  if (req.method !== 'POST' || req.url !== '/webhooks/telegram') {
    res.writeHead(404).end()
    return
  }

  // Telegram's X-Telegram-Bot-Api-Secret-Token is sent to Orbit's inbound
  // endpoint, not forwarded to your event receiver. Orbit validates it there.
  let body = ''
  req.setEncoding('utf8')
  req.on('data', (chunk) => { body += chunk })
  req.on('end', () => {
    const event = JSON.parse(body)
    if (event.type === 'message.received' && event.data?.channel === 'telegram') {
      console.log('Telegram inbound:', event.data.body)
    }
    res.writeHead(200).end()
  })
})

server.listen(3000)

Telegram sends X-Telegram-Bot-Api-Secret-Token to Orbit’s registered inbound URL. Orbit rotates the per-bot secret_token during connect and validates it before forwarding the normalized event to your receiver. Your receiver sees the forwarded message.received payload; it does not receive Telegram’s secret header. Never use a BotFather token as a webhook secret. Example forwarded event:

{
  "type": "message.received",
  "data": {
    "id": "msg_01HZM3GK5E0Y4X9N7J2C0RPTD6",
    "channel": "telegram",
    "from": "581234567",
    "to": "<your_bot_username>",
    "body": "Hello from Telegram",
    "created_at": "2026-10-11T12:00:00.000Z"
  },
  "meta": { "request_id": "req_telegram_inbound_01", "timestamp": "2026-10-11T12:00:00.000Z" }
}

5. Edit and delete are Orbit-side only

PATCH /messages/:id and DELETE /messages/:id operate on the Orbit message record — they never call Telegram’s editMessageText or deleteMessage:

PATCH: 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 — a delivered message is not re-editable.
DELETE: soft-deletes the Orbit message record and syncs the removal across your dashboards.

If you claim the message is edited or removed in Telegram itself, that is wrong — Orbit does not attempt it. For a delivered message the right recovery is a follow-up correction sent to the chat.

6. Lifecycle — retire the bot

POST /api/v1/telegram/disconnect-bot soft-deletes the connected-bot row and revokes the webhook registration with Telegram (deleteWebhook). The conversation history survives — Orbit keys history by bot_id, not by the token — so if you rotate the token via BotFather and reconnect with the new value, your history is preserved.

7. Error reference

A failed send returns a JSON error envelope whose error.code is one of the values below.

Code	HTTP	Cause	Fix
`INVALID_RECIPIENT`	422	The `to` chat id is missing or empty.	Send a non-empty chat id — numeric for a user or group, `@channelname` for a channel.
`MISSING_REQUIRED_FIELD`	422	A `photo` / `video` / `document` send was missing `mediaUrl`, or a `location` send was missing `latitude` / `longitude` in `metadata`.	Supply the field the send `type` requires.
`TELEGRAM_BOT_ALREADY_CONNECTED`	409	Another Orbit organization already holds the `bot_id` claim for this bot.	Disconnect the other org first, or resolve it as an ownership dispute.
`MESSAGE_NOT_EDITABLE`	409	You attempted to `PATCH` a message that is already sent.	Only scheduled messages are editable — send a follow-up correction instead.
`RATE_LIMIT_EXCEEDED`	429	Telegram’s flood-control rejected the send (too many requests in a short window).	Orbit already waits the `retry_after` Telegram returns before retrying; once the budget is exhausted, back off and re-send after the window.
`MESSAGE_SEND_FAILED`	502 (or the Telegram status when it is a 4xx)	Telegram rejected the send — a revoked or invalid bot token, a malformed payload, or an upstream 5xx.	For a 401, issue a new token via `/revoke` in BotFather and reconnect. For a 4xx, check the payload. A 502 is transient — retry.

Webhook security depends on the same secret_token per bot that Orbit rotates on connect — inbound updates that do not present it are rejected, so a spoofed sender cannot inject traffic into your callbacks.

8. Group events via the `telegram-group-events` module

Community bots added to groups or supergroups produce a different event shape — member joins and leaves, message-delete floods, and group keyword flows land on the dedicated telegram-group-events webhook module rather than the plain inbound path. Keep your primary handler on message.received for the customer chat surface, and subscribe the group module only if your bot operates in groups — the high-churn event classes (member-count churn, message-delete storms) are classified and dropped there so standard routing stays clean.

9. The model behind the ladder

The concept page The channel test-account model documents what this guide walks through operationally: the three-mode state machine, the two gate classes (send-permitted vs bot-owner-only), the shared-bot identity lock, and why the same endpoints route differently per mode so your code doesn’t change between test and production.

WhatsApp

Developer console

Contact center

Guides

Messaging Controls

Audience & Support Tools

Telegram onboarding: shared test bot to your own bot

Telegram Onboarding: Shared Test Bot to Your Own Bot

1. The test-account loop — send real messages today

Step 1: Start verification

Step 2: Send a test message through the shared bot

Step 3: Deliver demo flows while still test-scope

2. Bring your own bot (paste-token onboarding)

3. Send with metadata — types, keyboards, and formatting

4. Inbound webhook — receive Telegram messages

5. Edit and delete are Orbit-side only

6. Lifecycle — retire the bot

7. Error reference

8. Group events via the `telegram-group-events` module

9. The model behind the ladder

​Telegram Onboarding: Shared Test Bot to Your Own Bot

​1. The test-account loop — send real messages today

​Step 1: Start verification

​Step 2: Send a test message through the shared bot

​Step 3: Deliver demo flows while still test-scope

​2. Bring your own bot (paste-token onboarding)

​3. Send with metadata — types, keyboards, and formatting

​4. Inbound webhook — receive Telegram messages

​5. Edit and delete are Orbit-side only

​6. Lifecycle — retire the bot

​7. Error reference

​8. Group events via the telegram-group-events module

​9. The model behind the ladder

Telegram Onboarding: Shared Test Bot to Your Own Bot

1. The test-account loop — send real messages today

Step 1: Start verification

Step 2: Send a test message through the shared bot

Step 3: Deliver demo flows while still test-scope

2. Bring your own bot (paste-token onboarding)

3. Send with metadata — types, keyboards, and formatting

4. Inbound webhook — receive Telegram messages

5. Edit and delete are Orbit-side only

6. Lifecycle — retire the bot

7. Error reference

8. Group events via the `telegram-group-events` module

9. The model behind the ladder