tg-bot-binding

Summary

---
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.

Security audits