tg-bot-binding

---

name: tg-bot-binding version: 1.1.0 description: | Telegram bot binding: create the bot, connect to Starchild, verify, troubleshoot.

Two ways to bind: (1) scan-to-create (recommended, auto-bind) or (2) manual BotFather + token + verify.

Use when setting up Telegram delivery (e.g. add my TG bot, bot binding code, fix "telegram not pushing", whitelist a TG username).

metadata: starchild: emoji: "🤖" skillKey: tg-bot-binding

user-invocable: true disable-model-invocation: false

---

Telegram Bot Binding Guide

When the user asks about Telegram Bot binding, setup, connection, verification, or any related topic, provide them with the following guide. Always respond in the user's language.

Overview

Starchild lets you connect your own Telegram Bot so you can chat with your AI agent directly in Telegram. There are two ways to bind a bot:

1. Scan to create bot (Recommended) — scan a QR code, confirm creation in Telegram, and Starchild completes the binding automatically. No token to copy, no verification code.
2. Manual binding — create a bot via @BotFather, paste the token in the Dashboard, then verify ownership with a code.

Prefer the scan-to-create method whenever possible — it's faster and has fewer steps.

---

Method A: Scan to Create Bot (Recommended)

This method creates a new bot for you and binds it in a single flow — no token and no verification code.

Step 1: Open the Telegram Bot section

1. Go to the Starchild Dashboard (web interface).
2. Click your avatar at the bottom-left corner of the page.
3. In the Account Management popup, find the Telegram Bot section.
4. Click "Scan to create bot".

Step 2: Scan the QR code

A QR code appears together with a link. Do either of the following:

• Scan the QR code with your Telegram app (camera → scan), or
• Click "Open in Telegram" to jump straight to the creation page.

Step 3: Confirm creation in Telegram

Telegram opens a bot-creation page. Confirm that you want to create the bot.

Step 4: Done!

Starchild detects the new bot and completes the binding automatically. The bot goes straight to "running" — no verification code needed. Send /start in Telegram to begin chatting with your AI agent.

Note: A bot created this way is managed by Starchild's bot infrastructure. To remove it later, use the Delete Bot action in the Dashboard (not @BotFather).

---

Method B: Manual Binding (BotFather + Token)

Use this flow if you prefer to create and own the bot token yourself via @BotFather.

Step 1: Create a Telegram Bot via BotFather

1. Open Telegram and search for @BotFather (the official Telegram bot for creating bots).
2. Send /newbot to BotFather.
3. Follow the prompts:
   • Enter a display name for your bot (e.g., "My Starchild Agent").
   • Enter a username for your bot (must end in bot, e.g., my_starchild_bot).
4. BotFather will reply with your Bot Token — a string like 123456789:ABCdefGHIjklMNOpqrsTUVwxyz. Copy this token and keep it safe. Do not share it publicly.

Step 2: Add the Bot Token in Starchild Dashboard

1. Go to the Starchild Dashboard (web interface).
2. Click your avatar at the bottom-left corner of the page.
3. In the Account Management popup, find the Telegram Bot section.
4. Paste your Bot Token and submit.
5. The system will:
   • Verify the token with Telegram's API (calling getMe).
   • Generate a 6-digit verification code (valid for 5 minutes).
   • Set the bot status to "pending".
6. You will see the verification code displayed on the dashboard. Copy this code.

Step 3: Verify Bot Ownership in Telegram

You have two ways to verify:

Option A: Deep Link (Recommended)

Click the verification link provided on the dashboard. It will open your bot in Telegram and automatically submit the verification code. The link format is:

https://t.me/<your_bot_username>?start=verify_<CODE>

Option B: Manual Verification

1. Open your bot in Telegram (search for @<your_bot_username>).
2. Send /start — the bot will prompt you to enter the verification code.
3. Type the 6-digit code and send it.

Step 4: Done!

Once verified, the bot status changes to "active" briefly, then automatically transitions to "running" — meaning your bot is live and ready. You can start chatting with your AI agent through Telegram. Send /start to see the welcome message and available commands.

---

Bot Status Reference

Status	Meaning
pending	Bot token added, awaiting ownership verification (manual flow only)
active	Ownership verified, transitioning to running
running	Bot is live and ready to use
deleted	Bot has been removed by the user

---

Troubleshooting

"Verification code expired"

The verification code is valid for 5 minutes. If it expires:

• Go back to the Dashboard and click "Refresh Code" to generate a new one.
• Then verify again in Telegram with the new code.

"Too many failed attempts"

After 5 incorrect attempts, the verification code is invalidated for security:

• Go to the Dashboard, delete the bot, and add it again to get a fresh code.

"Bot token is already registered by another user"

Each Bot Token can only be bound to one Starchild account. If you see this error:

• Make sure you're using a new, unused bot token.
• If you previously used this token, the old binding may still exist. Create a new bot via @BotFather.

"You already have an active bot"

Each account can only have one active bot at a time:

• To switch bots, first delete the current bot from the Dashboard, then add the new one.
• Note: After deleting a bot, there is a 1-hour cooldown before you can add a new one.

"Cooldown active — Please wait before adding a new bot"

After deleting a bot, you must wait 1 hour before adding a new one. The dashboard will show the cooldown expiration time.

"Too many attempts. Please wait a moment and try again."

The scan-to-create flow is rate-limited. If you see this message, wait a short while before clicking "Scan to create bot" again.

"Authorization expired. Please try again."

The scan-to-create QR code / link is only valid for a limited time. If it expires:

• Cancel the current pairing, then click "Scan to create bot" again to get a fresh QR code.

Bot is not responding in Telegram

• Check the bot status on the Dashboard — it should be "running".
• If the status is "pending", complete the verification step (manual flow).
• Try sending /start to the bot.
• If the issue persists, try deleting and re-adding the bot (after the 1-hour cooldown).

---

Quick Reference

Action	Where
Create + bind a bot (fastest)	Starchild Dashboard → bottom-left avatar → Account Management → Telegram Bot → "Scan to create bot" → scan QR code → confirm in Telegram
Create a new Telegram bot manually	Telegram → @BotFather → /newbot
Add bot token	Starchild Dashboard → bottom-left avatar → Account Management → Telegram Bot
Verify ownership	Telegram → Your bot → enter verification code
Refresh verification code	Starchild Dashboard → Account Management → Telegram Bot → "Refresh Code"
Delete bot	Starchild Dashboard → Account Management → Telegram Bot → "Delete Bot"
Check bot status	Starchild Dashboard → Account Management → Telegram Bot

---

Important Notes

• Recommended flow: Use "Scan to create bot" — it creates and binds the bot automatically with no token or verification code.
• Scan-created bots are managed by Starchild: They are created through Starchild's bot infrastructure. Delete them from the Dashboard, not from @BotFather.
• Security: In the manual flow, your Bot Token is encrypted (AES-256) before storage. It is never exposed in API responses.
• One bot per account: You can only have one active Telegram bot at a time.
• Cooldown: After deleting a bot, wait 1 hour before adding a new one.
• Rate limits: Adding a bot and refreshing codes are limited to 3 requests per minute.
• Verification attempts: You have 5 attempts to enter the correct code before it's invalidated.