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

# Telegram

> Set up a Telegram bot to chat with your ArgentOS agent.

## Overview

Telegram is the recommended starting channel for ArgentOS. Setup takes under 5 minutes and the Bot API is reliable and well-documented.

## Prerequisites

* A Telegram account
* ArgentOS gateway running (`argent gateway start`)

## Setup

<Steps>
  <Step title="Create a Bot with BotFather">
    1. Open Telegram and search for **@BotFather**
    2. Send `/newbot`
    3. Choose a display name (e.g., "My Argent Agent")
    4. Choose a username ending in `bot` (e.g., `my_argent_bot`)
    5. Copy the **HTTP API token** BotFather gives you
  </Step>

  <Step title="Add the Channel">
    ```bash theme={null}
    argent channels add telegram
    ```

    When prompted, paste your bot token. The CLI will verify the token and save it to your config.
  </Step>

  <Step title="Configure (Optional)">
    Edit `argent.json` to customize Telegram-specific settings:

    ```json theme={null}
    {
      "channels": {
        "telegram": {
          "enabled": true,
          "token": "123456789:ABCdefGHIjklMNOpqrSTUvwxYZ",
          "allowedUsers": [],
          "polling": true,
          "webhook": {
            "enabled": false,
            "url": "https://your-domain.com/webhook/telegram",
            "port": 8443
          }
        }
      }
    }
    ```
  </Step>

  <Step title="Test">
    Send a message to your bot on Telegram. You should see it appear in the gateway logs and receive a response.

    ```bash theme={null}
    argent gateway logs --follow
    ```
  </Step>
</Steps>

## Polling vs Webhook

<Tabs>
  <Tab title="Polling (Default)">
    The bot periodically checks for new messages. Simpler setup, works behind NAT.

    ```json theme={null}
    {
      "channels": {
        "telegram": {
          "polling": true
        }
      }
    }
    ```
  </Tab>

  <Tab title="Webhook">
    Telegram pushes messages to your server. Lower latency, requires a public HTTPS endpoint.

    ```json theme={null}
    {
      "channels": {
        "telegram": {
          "polling": false,
          "webhook": {
            "enabled": true,
            "url": "https://your-domain.com/webhook/telegram",
            "port": 8443
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Security

### Restricting Access

<Warning>
  By default, anyone who finds your bot can message it. Use `allowedUsers` to restrict access.
</Warning>

```json theme={null}
{
  "channels": {
    "telegram": {
      "allowedUsers": [123456789, 987654321]
    }
  }
}
```

## Supported Features

| Feature          | Supported |
| ---------------- | --------- |
| Text messages    | Yes       |
| Photos/images    | Yes       |
| Documents/files  | Yes       |
| Voice messages   | Yes       |
| Inline keyboards | Yes       |
| Group chats      | Partial   |
| Threads/topics   | No        |