Set Up Telegram

Pinchy supports Telegram as a channel for your agents. Each agent can have its own Telegram bot, and users link their Telegram account once to access all bots they have permission to use.

Prerequisites

• A running Pinchy instance with at least one agent
• A Telegram account
• Admin access to Pinchy

Step 1: Create a Telegram Bot

1. Open BotFather in Telegram (or use the desktop/web app for easy copy-paste)
2. Send /newbot
3. Choose a display name for your bot
4. Choose a username ending in bot (must be unique on Telegram)
5. Copy the bot token BotFather gives you

Tip

Use Telegram Web or the desktop app to easily copy the token.

Step 2: Connect the Bot to Smithers

1. Go to Settings → Telegram
2. Click Set up Telegram
3. Paste the bot token
4. Click Connect

Your bot token is encrypted at rest and never leaves your server.

Step 3: Link Your Telegram Account

After an admin connects a bot, each team member links their own Telegram account:

1. Go to Settings → Telegram
2. Scan the QR code with your phone (or click "Open in Telegram")
3. Send any message to the bot
4. Copy the pairing code from the bot's response
5. Paste it into Pinchy and click Link

You're now linked. Messages you send to the bot are answered by the agent.

Sending Files and Photos

Send a photo or a file to the bot, and Pinchy mirrors it into the agent's workspace automatically — no upload step needed. The agent can then read it, or hand it to a tool like odoo_attach_file, the same way it would a chat attachment or an email attachment. See Attachments for how this fits into the rest of the upload system.

A couple of things worth knowing:

• Size limit: Telegram bots can only download files up to 20 MB, so that's the effective ceiling — Pinchy's own mirror limit is a more generous 25 MB.
• Photo vs. file: Telegram recompresses and strips metadata from anything sent as a photo, and replaces the filename with a generated one. If you need the original quality — full resolution, EXIF data, the real filename — send it as a file/document instead of a photo. For everyday things like receipts, either way works fine.

Connect Additional Agents

Each agent can have its own Telegram bot. To connect a second agent:

Before you start

Pinchy's main Telegram bot must already be set up in Settings → Telegram (Steps 1 and 2 above). Users link their Telegram account via the main bot; without it, additional agent bots have no way to receive messages. If you see a "Telegram isn't set up yet" message in the agent's Telegram tab, go to Settings → Telegram first.

1. Create a new bot via BotFather (repeat Step 1)
2. Go to Agent Settings → Telegram for the agent you want to connect
3. Paste the new bot token and click Connect

Note

Each bot token can only be used by one agent. If you try to use the same token for two agents on this deployment, Pinchy will reject it.

This check is per-deployment, though — Pinchy can't see a different Pinchy (a staging stack, a local dev stack) polling the same token. Telegram allows only one poller per bot, so if two deployments share a token they fight over it: one wins each round, the other gets a getUpdates 409 "Conflict: terminated by other getUpdates request", and the bot drops messages while OpenClaw crash-restarts the channel. Give each environment its own bot token. Pinchy also actively checks for this at connect time: it briefly probes Telegram before saving the token and rejects the connection outright if another deployment is already polling it, so you find out immediately instead of discovering a degraded bot later. That check is a point-in-time snapshot, though — a conflict that starts up after a successful connect isn't caught by it. For that, Pinchy's channel-health watchdog keeps watching — a Degraded badge appears on the agent's Telegram settings and channel.degraded / channel.polling_failed rows land in the audit trail. Once the conflict is sustained, the watchdog also restarts the affected bot at increasing intervals (channel.restarted audit rows), so polling resumes within about a minute of the conflicting poller going away — without waiting out OpenClaw's internal retry backoff, which can otherwise leave the bot dark for up to ten minutes. After a few restarts without recovery it stops forcing restarts and hands back to OpenClaw's own retry, so a genuinely persistent conflict settles down instead of restarting endlessly. Turn this off with TELEGRAM_CONFLICT_AUTO_RESTART=false.

If the conflict survives those restarts and the bot on this deployment was connected recently (within the last 24 hours), we go a step further: we automatically disable it. The idea is that the newcomer backs off so the deployment that's been running the token for a while doesn't get disrupted by an environment that just showed up. When we auto-disable an account, we stop polling for it, clear its Telegram user pairings, and record a channel.auto_disabled audit row — a persistent, actionable message appears on the agent's Telegram settings explaining what happened. The disable survives a restart, so you won't see the bot quietly come back the next time Pinchy starts. Once you've stopped the token elsewhere (or switched to a separate one), click Reconnect to clear the disabled state and try again.

A long-standing connection is never auto-disabled this way — only the side that just showed up. If you'd rather handle conflicts manually, set TELEGRAM_CONFLICT_AUTO_DISABLE=false in your deployment's environment; the Degraded badge and audit trail keep working as before, we just won't disable anything automatically.

How Permissions Work

Telegram access follows Pinchy's permission model:

• Agents with visibility "All": Every linked user can message the bot
• Restricted agents: Only users in the agent's allowed groups (and admins) can message the bot
• If a user messages a bot they don't have access to, they receive a pairing prompt instead of an agent response

When group memberships or agent visibility change, Telegram access is updated automatically.

Unlinking and Removing

• Unlink your account: Settings → Telegram → Unlink. You can re-link anytime.
• Disconnect an agent's bot: Agent Settings → Telegram → Disconnect (not available for Smithers)
• Remove Telegram for everyone: Settings → Telegram → Remove Telegram for everyone. This disconnects all bots and unlinks all users.

Caution

Smithers' bot cannot be disconnected individually. Use "Remove Telegram for everyone" to remove all Telegram integration at once.

Channel-config preservation

From v0.5.5 onward, pairing or disconnecting a Telegram bot only touches that bot's entry in the OpenClaw channels block. Sibling channel sub-blocks owned by OpenClaw (or future channel types) are preserved unchanged. Earlier versions occasionally rewrote sibling entries when telegram config changed, which could disturb other channels — fixed in #314.