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

# Connect a Telegram account

> Set up your own Telegram app once per Mac, link a Telegram account by QR code, and grant it to an agent.

> [!NOTE]
>
> Draft: these steps await verification against the current release of Agenium.

**Outcome:** an agent reads (and, if you allow, writes in) a Telegram account through the [Telegram capability](https://docs.agenium.io/capabilities/telegram.md).

Telegram needs two things: once per Mac, your own Telegram app, and then one connection per account. Agenium ships no shared Telegram app, so a block on one app never breaks anyone else's login.

```mermaid theme={null}
flowchart LR
  app["Your Telegram app<br/>api_id + api_hash"] --> setup["Setup:<br/>Telegram App"]
  setup --> add["Add connection:<br/>QR code, then 2FA password"]
  add --> conn["Connection"]
  conn -- "Give access:<br/>read or read and write" --> agent["Agent"]
```

## What you need

* The Telegram capability installed and allowed in **Capabilities**. See [Capabilities](https://docs.agenium.io/app/capabilities.md#install-one).
* An app of your own from [my.telegram.org](https://my.telegram.org): its **App api\_id** and **App api\_hash**.
* The Telegram app on your phone, signed in to the account you want to connect, and the account's two-step password if it has one.
* Optionally, for transcribing voice messages, a Deepgram key in [Settings > Transcription](https://docs.agenium.io/app/settings.md#transcription).

## Steps in the app

**1. Open the Telegram capability**

For a shared connection any agent can be granted, open **Capabilities** and press **Telegram**. For the agent's own account, open the agent's page and press its Telegram tile instead.

**2. Set up the Telegram App**

The **Telegram App** block sits above Connections. Enter **App api\_id** as shown on my.telegram.org and **App api\_hash**, then **Save**. Beside the block's title, Agenium shows whether Telegram accepts the app, rejects it, or has blocked it, with Telegram's reason. A link at its right shows the steps to create the app.

Until the app is set, **Add** stays disabled with the reason.

**3. Add the connection by QR code**

Press the last tile in **Connections**. A sheet shows a QR code. On your phone, open Telegram's settings, choose to link a device, and scan it.

**4. Enter the two-step password, if asked**

When the account has a two-step password, the sheet asks for it next.

Logging in by phone number and code is the second way, a link away in the same sheet.

**5. Grant it to an agent**

A connection added on the capability's page is shared. On the agent's page, open its Telegram tile and use **Give access**, choosing **read** or **read and write**. A connection added on the agent's page is already that agent's own and granted to it.

## Steps by command line

The capability's own command covers the same setup and login; `telegram help` gives its reference, and `telegram doctor` checks that it is ready.

## Check it worked

1. The connection's tile shows the account's name and its Telegram id, with a health dot once checked. Use **Check** from its ⋯ menu.
2. In the agent's view, the connection shows as granted, marked read or read and write.
3. Ask the agent in a session to read a recent chat.

## Common failures

| What you see | Why, and what to do |
| - | - |
| **Add** is disabled | The Telegram App is not set. Fill in App api\_id and App api\_hash and Save. |
| The app shows as rejected or blocked | Telegram refuses that app; its reason is shown. Create a new app on my.telegram.org. |
| The QR code expires | It renews by itself until you scan it. Scan the current one. |
| No connection appears after a failed attempt | By design: a connection is recorded only once its login succeeds. Start again. |
| The agent cannot send | The connection was granted read-only. Grant read and write. |
| Voice messages are not transcribed | No Deepgram key is set. Add it in Settings > Transcription; it is the one key every capability uses. |

## Related

* [Capabilities: connections](https://docs.agenium.io/app/capabilities.md#connections)
* [Telegram capability](https://docs.agenium.io/capabilities/telegram.md)
* [Your first agent](https://docs.agenium.io/first-agent.md#the-personal-agents-onboarding), whose onboarding asks for Telegram


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.