Telegram SDK Migration and the Bot API Boundary

Telegram SDK migration is not the point where the listener stops being a filesystem-first system. It is the point where the API boundary has to stay explicit enough that the runtime contract does not blur into a larger abstraction.

The practical rule is simple: replace the transport layer, not the behavior.

Keep The Boundary Small

The current Telegram API shape is already deliberate. The listener has a client that can ask Telegram for updates with explicit offset and timeout parameters. That keeps the long-poll contract visible instead of burying it in a helper that tries to guess what the runtime should do next.

If the SDK changes, the boundary should still make those controls obvious. A different package can own authentication, request serialization, retries, or payload decoding, but the listener should still decide when to poll, how far to advance, and what to persist after the response lands.

Why The Bot API Boundary Matters

The Bot API boundary is where transport ends and runtime state begins.

That line matters because the listener already has several other durable files that it owns:

• listener state,
• lease ownership,
• history,
• and inbox records.

If the SDK starts absorbing that logic, the runtime contract gets harder to reason about. An operator should be able to inspect the files and understand what happened without first learning the SDK's internal conventions.

The boundary should therefore stay narrow:

• the API client talks to Telegram,
• the intake layer normalizes updates,
• the inbox layer writes durable records,
• and the listener shell keeps lifecycle control.

That split gives future SDK migration room without letting the transport dictate the product model.

What Migration Can Change

Migration can change the mechanics of the HTTP request. It can change the serialization library. It can change retry behavior or response parsing. It can even change how the client object is constructed.

What it should not change is the contract the rest of the listener depends on. The listener still needs:

• explicit offsets,
• readable restart state,
• preserved raw payloads,
• and inbox records that can be inspected later.

Those are product requirements, not implementation details. Any SDK migration that makes them less visible is the wrong migration.

The Practical Check

There is an easy way to tell whether the migration stayed honest.

If a transport change makes it harder to tell what offset was requested, what payload came back, or whether the inbox advanced after persistence, the boundary has grown too wide. If the listener remains readable from the files alone, the SDK swap stayed in its lane.

That is why the Telegram code already keeps normalization separate from the raw API request. The listener should never need to infer its own history from a black box helper. It should write the history.

The Design Rule

A Bot API boundary is useful only if it keeps the rest of the system stable while the transport changes underneath it.

For Telegram, that means the SDK can move, but the runtime contract cannot. The listener still needs the same files, the same stop semantics, and the same restart safety. That is the only migration worth shipping.