# Telegram errors

Telegram connectivity is Limited. The production HTTP receiver exists, but webhook registration is not automated end to end; the polling script is a developer alternative, not a second production channel.

## Symptom

The dashboard cannot connect a bot, Telegram messages receive no reply, duplicate updates appear to be ignored, or delivery to Telegram fails after the agent has produced a response.

## Cause

A bot token can be attached to only one agent, an invalid token is rejected, and the token value is not recoverable later. The receiver validates Telegram's secret header. Invalid callbacks deliberately return a quiet success response so they do not reveal channel state or create retry noise. `channel_upstream_failed` means the provider rejected or failed the outbound reply.

## Verify

Confirm the channel still exists, the intended agent is published and receives traffic, webhook registration targets the correct Operade receiver, and Telegram sends the configured secret token header. Check Activity without copying the bot token or provider URL. For duplicate updates, verify the Telegram update identifier before assuming a missing turn.

## Recovery

Correct webhook registration and test with a private text message. If the bot token is wrong or lost, delete and recreate the channel with the current token. For an upstream failure, verify Telegram availability and retry with a new message after the issue clears. Do not use the development poller alongside a production webhook.

## Escalation

Escalate with the safe channel and agent identifiers, update identifier, UTC time, and public code. Never send the bot token, webhook secret, or a URL containing credentials. Read [Telegram Limited](/docs/deploy/telegram-limited), [Conversations](/docs/monitor/conversations), and [Support](/docs/reference/support).

## Error code index

- `channel_upstream_failed` — Telegram did not accept the outbound channel request.

Because availability is Limited, this guide describes current tested behavior and does not promise automated setup or production readiness beyond it.