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

# Telegram Channel

> Connect your bot to Telegram

Connect your bot to Telegram using the Telegram Bot API. Telegram bots support native typing indicators, inline buttons, media messages, and work in groups and private chats.

## Prerequisites

Before setting up a Telegram channel, you need:

* A Telegram account
* Access to [@BotFather](https://t.me/BotFather) bot
* A bot token from BotFather

## Creating a Telegram Bot

<Steps>
  <Step title="Open BotFather">
    Start a chat with [@BotFather](https://t.me/BotFather) on Telegram.
  </Step>

  <Step title="Create New Bot">
    Send the command:

    ```
    /newbot
    ```
  </Step>

  <Step title="Choose Name">
    BotFather will ask for a name. Enter a display name for your bot:

    ```
    My Support Bot
    ```
  </Step>

  <Step title="Choose Username">
    Enter a username (must end in "bot"):

    ```
    my_support_bot
    ```
  </Step>

  <Step title="Copy Token">
    BotFather will provide a token:

    ```
    123456789:ABCdefGHIjklMNOpqrsTUVwxyz
    ```

    Copy this token - you'll need it for the next step.
  </Step>
</Steps>

<Callout type="warning">
  Keep your bot token secret. Anyone with the token can control your bot.
</Callout>

## Connecting to Chatbot Platform

<Steps>
  <Step title="Navigate to Channels">
    In Chatbot Platform, go to your bot and click **Channels**.
  </Step>

  <Step title="Create Telegram Channel">
    Click **Create Channel** and select **Telegram**.
  </Step>

  <Step title="Enter Token">
    Paste the bot token from BotFather.
  </Step>

  <Step title="Save">
    Click **Create** to establish the connection.
  </Step>

  <Step title="Webhook Auto-Configuration">
    The platform automatically configures the webhook with Telegram's API.
  </Step>
</Steps>

## Features

### Native Typing Indicators

Telegram supports native typing indicators via the `sendChatAction` API:

```
User: "Hello"
Bot: [shows typing animation with three dots]
Bot: "Hi! How can I help?"
```

Enable typing indicators in bot behavior settings.

### Group Chats

Bots work in Telegram groups with per-user context:

* Each user has separate conversation history
* Bot can respond to @mentions or all messages
* Group context is maintained per user

To add bot to a group:

1. Add bot as group member
2. Grant admin permissions if needed
3. Configure group privacy settings in BotFather

### Private Chats

Direct 1:1 conversations with users:

* Simple conversation context
* Full message history
* Native features like buttons and media

### Inline Buttons

Future support for inline buttons and actions:

```
Question: "Do you want to continue?"
[Yes] [No]
```

## Configuration

### Bot Privacy Settings

Configure in BotFather with `/setprivacy`:

**Privacy Mode Disabled**:

* Bot receives all group messages
* Can respond to any message
* Required for full conversation context

**Privacy Mode Enabled**:

* Bot only receives messages with @mention
* Or commands starting with /
* Limited context awareness

### Group Permissions

For groups, the bot needs:

* **Read Messages**: Receive messages
* **Send Messages**: Reply to users
* **Send Media**: Images, files, etc.

Configure in group settings or make bot an admin.

## Testing

<Steps>
  <Step title="Find Your Bot">
    Search for your bot username in Telegram.
  </Step>

  <Step title="Start Chat">
    Click **Start** or send `/start`.
  </Step>

  <Step title="Send Message">
    Send a test message.
  </Step>

  <Step title="Verify Response">
    The bot should respond using your configured integration.
  </Step>
</Steps>

## Troubleshooting

### Bot Not Responding

**Check**:

* Token is correct
* Channel is enabled
* Bot has integration configured
* Webhook is registered (check platform logs)

### Bot Not Receiving Group Messages

**Possible causes**:

* Privacy mode is enabled (disable in BotFather)
* Bot needs @mention
* Bot not added to group

**Solution**:

* Use `/setprivacy` in BotFather
* Set to **disabled**
* Re-add bot to group if needed

### Webhook Errors

If webhook registration fails:

* Verify token is valid
* Check token has no extra spaces
* Regenerate token in BotFather if needed

## Advanced Features

### Commands

Register bot commands in BotFather:

```
/start - Start conversation
/help - Get help
/settings - Configure preferences
```

Use `/setcommands` in BotFather.

### Custom Keyboard

Future support for custom keyboards with predefined buttons.

### Media Messages

Bot can receive and process:

* Photos
* Documents
* Audio
* Video
* Location (latitude, longitude, and optional metadata)

When a user shares their location in Telegram, your integration receives the location data in the message payload, allowing you to build location-aware features like finding nearby places or providing directions.

## Security

<CardGroup cols={2}>
  <Card title="Token Security" icon="lock">
    Never share or expose your bot token publicly
  </Card>

  <Card title="Webhook Validation" icon="shield-check">
    Platform validates all requests are from Telegram
  </Card>

  <Card title="Rate Limiting" icon="gauge">
    Telegram enforces rate limits on bot API calls
  </Card>

  <Card title="Spam Protection" icon="shield">
    Implement spam detection in your integration if needed
  </Card>
</CardGroup>

## Rate Limits

Telegram enforces these limits:

| Action                      | Limit         |
| --------------------------- | ------------- |
| Messages to same chat       | 1 per second  |
| Messages to different chats | 30 per second |
| Messages to same group      | 20 per minute |

The platform handles rate limiting automatically.

## Best Practices

<Callout type="tip">
  Test your bot in a private chat before adding to groups to ensure it works correctly.
</Callout>

**Do**:

* Set clear bot description in BotFather
* Configure bot commands for better UX
* Use typing indicators for longer responses
* Handle media messages gracefully

**Don't**:

* Share bot token publicly
* Spam users with messages
* Forget to test group behavior
* Leave privacy mode enabled if you need full context

## Next Steps

<CardGroup cols={2}>
  <Card title="Slack Channel" icon="slack" href="/bots/channels/slack">
    Also deploy to Slack
  </Card>

  <Card title="Bot Behaviors" icon="sliders" href="/bots/behaviors/index">
    Configure typing and detection
  </Card>
</CardGroup>