> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bothive.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Telegram Bots

> Deploy your Bothive agent as a real Telegram bot in under 5 minutes.

<div className="hero-container">
  <h1 className="hero-title">
    Deploy to Telegram
  </h1>

  <p className="hero-subtitle">
    Connect your Bothive agent to Telegram with a bot token. Your agent runs as a real Telegram bot — no servers, no webhooks to manage.
  </p>
</div>

## Why Telegram

<CardGroup cols={3}>
  <Card title="Where your users are" icon="users" className="glass-effect">
    900M+ active users. If your community, customers, or team uses Telegram — meet them there.
  </Card>

  <Card title="Rich bot features" icon="star" className="glass-effect">
    Commands, inline keyboards, media, groups, channels, DMs. Telegram has one of the best bot APIs available.
  </Card>

  <Card title="Zero friction" icon="bolt" className="glass-effect">
    Users don't need to install anything. They just message your bot on Telegram.
  </Card>
</CardGroup>

## Step-by-step setup

<Steps>
  <Step title="Create your bot with BotFather">
    Open Telegram and search for **@BotFather**. Send `/newbot` and follow the prompts:

    1. Enter a **display name** (e.g., `Acme Support`)
    2. Enter a **username** — must end in `bot` (e.g., `AcmeSupportBot`)
    3. BotFather sends you a token: `7123456789:AAFxxxxxxxxxxxxxxxxxx`

    **Save this token** — you'll need it in the next step.
  </Step>

  <Step title="Connect the token to Bothive">
    In your Bothive dashboard:

    1. Open your bot → **Channels**
    2. Click **Telegram** → **Connect**
    3. Paste your bot token
    4. Click **Save**

    Bothive automatically sets the webhook. You'll see a green  when the connection is live.
  </Step>

  <Step title="Write your HiveLang bot">
    ```hivelang theme={null}
    bot TelegramSupportBot {
      description: "Customer support for Telegram users"

      capabilities {
        knowledgebase.search
        support.createTicket
        billing.getSubscription
      }

      instructions {
        You are a helpful support agent for Acme SaaS.

        When users ask about their account:
        - Ask for their email if not provided
        - Look up their subscription status
        - Explain issues clearly, in plain language

        Format responses for Telegram:
        - Use *bold* for important information
        - Use bullet points for steps
        - Keep responses concise — under 200 words

        If you cannot resolve an issue, create a support ticket
        and tell the user they'll hear back within 24 hours.
      }

      on "/start" {
        say "*Welcome to Acme Support!* \n\nI can help you with billing, account issues, and product questions. What do you need help with?"
      }

      on "/status" {
        say "All systems operational \nCheck https://status.acme.com for live status."
      }
    }
    ```
  </Step>

  <Step title="Test in Telegram">
    Search for your bot in Telegram → send `/start` → confirm the welcome message appears.

    Send a real support question and check that:

    * The response arrives within 2 seconds
    * Formatting looks correct in Telegram
    * Tool calls (if any) succeed
  </Step>

  <Step title="Set BotFather commands (optional)">
    Add a command menu so users know what your bot can do:

    1. Message @BotFather → `/setcommands`
    2. Select your bot
    3. Paste your command list:

    ```
    start - Welcome and intro
    status - Check service status
    help - List all commands
    ```
  </Step>
</Steps>

## Telegram-specific formatting

Bothive uses Telegram's MarkdownV2 formatting when responding on the Telegram channel:

| Format     | Syntax         | Example                            |
| ---------- | -------------- | ---------------------------------- |
| Bold       | `*text*`       | **Important**                      |
| Italic     | `_text_`       | *note*                             |
| Code       | `` `code` ``   | `bot_id`                           |
| Code block | ` ```code``` ` | Multi-line code                    |
| Link       | `[text](url)`  | [Dashboard](https://bothive.cloud) |

<Tip>
  Tell your agent explicitly in the instructions to use Telegram formatting. The model adapts its output to whichever channel it's responding on if you guide it.
</Tip>

## Common Telegram setup issues

<AccordionGroup>
  <Accordion title="Bot doesn't respond to messages">
    Check that the webhook is set correctly. In Bothive, open **Channels → Telegram** and click **Verify webhook**. If it shows a red , try reconnecting with the token.
  </Accordion>

  <Accordion title="Privacy mode blocking group messages">
    By default, Telegram bots only receive messages that start with `/` in groups. To change this, send `/setprivacy` to @BotFather and disable privacy mode — or ensure users tag your bot with `@YourBotUsername`.
  </Accordion>

  <Accordion title="Agent sends duplicate responses">
    This usually means you've connected the same bot token in multiple places. Make sure the token is only connected to one Bothive bot.
  </Accordion>

  <Accordion title="Slow responses (>5 seconds)">
    Check which tools are being called in the Run trace. Slow tool calls are usually integration issues — check your integration credentials. You can also switch to a faster model (e.g., GPT-4o mini or Groq) for response-speed-critical bots.
  </Accordion>
</AccordionGroup>

## Groups vs DMs

| Feature             | Direct Messages              | Group Chats                  |
| ------------------- | ---------------------------- | ---------------------------- |
| Setup complexity    | Simple                       | Requires privacy mode config |
| Session persistence | Per user                     | Per (group\_id, user\_id)    |
| Best for            | Personal assistants, support | Community bots, team tools   |
| @mention required   | No                           | Yes (with privacy mode on)   |

## Next reads

<CardGroup cols={3}>
  <Card title="Slack Bots" icon="slack" href="./slack-bots" className="glass-effect" />

  <Card title="Deploy to Channels" icon="rocket" href="./deploy-to-channels" className="glass-effect" />

  <Card title="Observability" icon="chart-line" href="../concepts/observability" className="glass-effect" />
</CardGroup>