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

# Telegram

> Set up Telegram channel posting with a bot token from BotFather.

The Telegram lane publishes to a channel through a bot. It publishes only once a Telegram credential is present in your `.env`; until then the lane is live-but-unauthenticated and waits for you to connect it (set `PENDPOST_MODE=mock` to exercise it through the mock driver).

You own your Telegram bot and channel and are responsible for Telegram's terms of service. pendpost drafts and schedules, but a human approves before anything goes live.

## Setup ceremony

The bot token is static, so there is no token exchange to run. Create the bot, point it at a channel, and confirm the connection.

1. **Create a bot with BotFather.** Open Telegram, message [@BotFather](https://t.me/BotFather), send `/newbot`, and follow the prompts. BotFather hands you an HTTP API token, which is the only credential pendpost needs.
2. **Create the destination channel.** A public channel with an `@username` gives clean post permalinks; a private channel works too but has no shareable links. Record its `@username` (or numeric chat id).
3. **Add the bot as a channel admin.** In the channel, add the bot as an administrator and grant it "Post Messages". Without admin rights the bot cannot publish.

Then confirm the token authenticates and the bot can reach the channel:

```bash theme={null}
node scripts/telegram-social.mjs auth
```

## Environment variables

| Variable | Purpose |
| - | - |
| `TELEGRAM_BOT_TOKEN` | The HTTP API token BotFather issues for your bot. |
| `TELEGRAM_CHANNEL_ID` | The channel you post to, as an `@username` or numeric chat id. |

> [!NOTE]
>
> A lane publishes only once its credential is present. If the Telegram variables are blank, the Telegram lane is live-but-unauthenticated and waits for you to connect it. Set `PENDPOST_MODE=mock` to exercise it through the mock driver.

## Validate the lane

A present credential is not the same as a working one. After setup, validate the Telegram lane in the **Setup** tab, or run a live probe with the `health_recheck` tool, to confirm the credential is live and not just configured. The lane is ready when it reports live.

> [!NOTE]
>
> **Over MCP.** Setup and rotation are an interactive human ceremony; secrets are never written through MCP. An agent can still check status (`account_status`), run a live liveness probe (`health_recheck`), and read non-secret config (`config_get`) over MCP without touching credentials.

## Common failures

| Symptom | Cause | Fix |
| - | - | - |
| Publishing returns "Unauthorized". | The bot token is wrong or was revoked. | Get a fresh token from @BotFather (`/token`), update `TELEGRAM_BOT_TOKEN`, and re-run the auth check. |
| Publishing returns "chat not found" or "not enough rights". | The channel id is wrong, or the bot is not an admin with Post Messages. | Confirm `TELEGRAM_CHANNEL_ID` and add the bot as a channel administrator with posting rights. |


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