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

# Telegram

> Connect a Telegram bot to a space for direct messages.

Connect a Telegram bot to any Friday space so users can chat with it over DM. Messages flow into the same conversation pipeline the web chat uses, and replies go back to Telegram.

## Prerequisites

* A Telegram account on your phone (the one that will own the bot).
* Friday running with the bundled tunnel active (Telegram requires a public HTTPS URL).

## Setup

<Steps>
  <Step title="Create a bot with BotFather">
    1. Open the **Telegram** app on your phone and search for **BotFather** (official account, blue checkmark). Tap **Start**.
    2. Send `/newbot`.
    3. Choose a **display name** (what users see, e.g. *Friday Studio*).
    4. Choose a **username** ending in `bot` (e.g. `friday_studio_xxxxx_bot`).
    5. BotFather replies with a **bot token** like `123456789:ABC-DEF-GHIJKLM...`. Treat it like a password — anyone with it controls the bot.
  </Step>

  <Step title="Connect Telegram in Studio">
    1. In Studio, select your space from the sidebar and click **Info**.
    2. Find the **Communicators** card and click **Connect** next to **Telegram**.
    3. Paste the **Bot Token** into the form, then submit.

    Studio stores the token securely and registers the webhook with Telegram automatically. The status flips to **Connected** when it's done.
  </Step>

  <Step title="Talk to your bot">
    In Telegram, search for your bot by username (`@friday_studio_xxxxx_bot`) and tap **Start** or send a message. The first message creates a chat in your space — it should appear in Studio with a green **TELEGRAM** badge, and replies flow back automatically.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Bot doesn't respond at all">
    Most likely the tunnel URL is stale (the development tunnel gets a new URL on every restart). Reconnect Telegram in Studio so it re-registers the webhook against the current tunnel.
  </Accordion>

  <Accordion title="Bot token rejected when connecting">
    Double-check you copied the full token from BotFather (numeric ID before the colon, secret after). Regenerate via BotFather → `/token` if needed.
  </Accordion>
</AccordionGroup>

## Configure via YAML

For CI or fully scripted setups, paste the bot token directly into `workspace.yml` or the `.env` file in the Friday home directory (default `~/.friday/local/.env`).

<Tabs>
  <Tab title="Credentials inline">
    ```yaml workspace.yml theme={null}
    communicators:
      telegram:
        kind: telegram
        bot_token: 123456789:ABC-DEF-GHIJKLM...
    ```
  </Tab>

  <Tab title="Credentials via env">
    ```bash # Friday home .env (default ~/.friday/local/.env) theme={null}
    TELEGRAM_BOT_TOKEN=123456789:ABC-DEF-GHIJKLM...
    ```

    ```yaml workspace.yml theme={null}
    communicators:
      telegram:
        kind: telegram
    ```
  </Tab>
</Tabs>

When you skip Studio, you also need to register the webhook with Telegram yourself. Grab the tunnel URL from Studio → **Settings** → **Webhook tunnel** and run:

```bash theme={null}
TELEGRAM_BOT_TOKEN="123456789:ABC-..."
TUNNEL_URL="https://<random>.trycloudflare.com"

SUFFIX="${TELEGRAM_BOT_TOKEN#*:}"
curl -s -X POST \
  "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/setWebhook" \
  -d "url=${TUNNEL_URL}/platform/telegram/${SUFFIX}"
```

Restart Friday after editing config.