# Telegram

import Screenshot from "@docs/Screenshot.astro"
import SurfaceTabs from "@docs/SurfaceTabs.astro"
import AskRen from "@docs/AskRen.astro"

Each Telegram group or DM connects to one [Ren project](/docs/concepts/projects/), and Ren replies in the same conversation. One bot serves all organizations, without a separate installation. A project invite link adds the bot to your conversation.

## Link your Telegram account

Link your Telegram account so Ren knows which messages are yours. Each Telegram account links to one Ren user per organization.

<SurfaceTabs>
<Fragment slot="app">

1. Go to **Settings → Mentions**.
2. In the **Communication** section, select **Connect Telegram**. Ren opens a link to the Ren bot in Telegram.
3. In Telegram, select **Start**. The bot replies "✅ Your Telegram account is now linked to Ren."

The link works once and expires after 15 minutes.

<Screenshot
  shot="channels/telegram/link"
  alt="Settings Mentions with the Telegram row and the Connect Telegram button"
/>

</Fragment>
<Fragment slot="cli">

```sh
ren telegram link-code
```

Open the link it prints on a device with Telegram and select **Start**.

</Fragment>
</SurfaceTabs>

Linking is optional when the chat has a fallback sender: without a link, your messages run as that fallback sender.

## Use Ren in a group

A project invite link adds the bot to a group and maps the group to that project.

<SurfaceTabs>
<Fragment slot="app">

1. Open the project's **@Ren** tab.
2. On the **Telegram** card, select **Create invite link for a new chat**.
3. Select **Open in a group (bot must be admin)**. Choose the Telegram group. Make the bot an admin.

The bot posts "✅ This chat is now connected to …" with the project's name. To set a fallback sender, create the link from **Settings → Mentions → Telegram** with **Add Telegram chat** instead.

</Fragment>
<Fragment slot="ask-ren">

<AskRen prompt="Create a Telegram invite link for this project." />

</Fragment>
<Fragment slot="cli">

```sh
ren telegram claim-code --project-id <project-id>
```

Open the group link it prints. To move a chat that's already connected to another project, run `ren telegram chats set <chat-id> --project-id <project-id>`.

</Fragment>
</SurfaceTabs>

In a group, Ren reads only messages that @mention the bot or reply to one of its messages, and ignores the rest of the conversation.

- **Start a chat** by mentioning the bot in a new message.
- **Continue a chat** by replying to any of Ren's messages in it.

## Use Ren in a DM

DMs also need a project mapping. Create a project invite link and select **Open in a direct message**. Without a mapping, the bot asks you to connect the DM first.

In a DM, you don't need to mention the bot:

- **Start a chat** by sending a new message.
- **Continue a chat** by replying to one of Ren's messages.

## Attachments

Ren receives documents and photos you send with a message. Files over 32 MB are skipped, and Ren sees a note that they were.

Ren reads images, text files, and PDFs directly. It saves other files to the space's machine and opens them with its tools.

## Receive files and open artifacts

Files Ren creates, like a report or a spreadsheet, arrive in the chat as documents after its reply.

An [artifact](/docs/concepts/artifacts/), such as a dashboard or a small game, is a web page. Ask Ren for its link, and open it in your phone's browser.

## FAQ

<details>
<summary>Can Ren send me reminders?</summary>

Ask Ren to create a [schedule](/docs/concepts/schedules/) in the project. Each run can post to that project's Telegram chats.

</details>

<details>
<summary>Can Ren talk to other bots?</summary>

No. Telegram doesn't deliver messages from other bots to Ren.

</details>

<details>
<summary>What happens when Ren needs permission?</summary>

Telegram chats deny actions that need approval and continue without them. Configure [project permissions](/docs/concepts/projects/#permissions) before sending requests.

</details>