Telegram Group Migrated to Supergroup: Update Chat IDs Safely

When a Telegram group migrates to a supergroup, your bot must use the new chat identifier for subsequent sends. The Bot API exposes migrate_to_chat_id and migrate_from_chat_id on service messages, and can return parameters.migrate_to_chat_id in an unsuccessful API response. Record the old-to-new relationship explicitly: update future routing, but preserve the original chat identifiers on stored messages.

Key takeaways

• A group migration changes the destination identity; it is not a webhook transport failure.
• Read structured migration fields instead of matching an error description or guessing an identifier.
• Keep message history under its original chat identity while resolving future sends to the new destination.
• UnifyPort’s public normalized schema does not document an equivalent migration mapping; do not assume these Bot API fields appear there.

What migrate_to_chat_id and migrate_from_chat_id mean

The official Telegram Bot API reference defines both optional fields on Message and the migration field on ResponseParameters:

Evidence	Old chat	New chat
Message containing migrate_to_chat_id	That message’s chat.id	message.migrate_to_chat_id
Message containing migrate_from_chat_id	message.migrate_from_chat_id	That message’s chat.id
Failed request containing parameters.migrate_to_chat_id	The request’s numeric target chat ID	parameters.migrate_to_chat_id

For the response case, retain the original request context. If you sent to a username rather than a stored numeric ID, do not invent an old numeric identity from the error alone.

Telegram warns that migration identifiers can exceed 32 significant bits and have at most 52 significant bits. Its reference allows a signed 64-bit integer or double-precision float for storage. Avoid 32-bit conversions anywhere in the path. Using decimal strings in application-owned keys is also a useful design choice; preserve the sign and exact value.

This guide assumes updates already reach your receiver. For the earlier transport and identity choice, read Telegram Bot API webhook vs unified inbound webhook.

Treat migration as an alias, not a history rewrite

Recommended application design: separate a logical support conversation from its provider destinations. Keep an old-to-new mapping scoped to your tenant and bot integration, plus the evidence that established it. These are local storage concepts, not extra Telegram API fields.

Do not bulk-replace the chat ID on historical message records. Telegram defines message_id as unique inside its chat, not globally. Relabeling old messages as belonging to the new chat risks incorrect associations. An alias between chat destinations is not a documented translation between message identifiers.

Use this transaction-oriented sequence:

1. Authenticate and durably retain the incoming update, or retain the actual API error with its request context.
2. Extract the old and new chat identifiers from the structured evidence above.
3. Insert the mapping and update the current routing destination atomically where your storage permits it.
4. Treat repeated evidence for the same pair as a no-op. Quarantine conflicting mappings or cycles for review rather than overwriting silently.
5. Keep historical records unchanged. Resolve queued sends through the mapping immediately before dispatch.

Make the mapping update and destination resolution cooperate through an application lock or equivalent concurrency control. Otherwise, a worker can read the old target just before another worker commits the migration. Retain error handling for that race even with local coordination.

Recover queued sends without blind retries

A structured unsuccessful response carrying parameters.migrate_to_chat_id provides a new destination. Persist it before considering another attempt, and recheck whether the queued action is still appropriate. A timeout is different: it does not establish a migration or prove that a send failed.

If the task includes a reference to an earlier message, do not simply attach the old message_id to the new chat. Verify that the intended reference is valid or route the task for review. Never quietly turn a context-dependent action into a different message.

For observable send outcomes, see webhook replies vs separate sendMessage requests. A successful intake acknowledgement does not establish that an outbound task completed.

Suggested acceptance tests—not reported results:

• Duplicate migration evidence leaves one mapping and does not create a second send job.
• A delayed old-chat update remains historical evidence and does not reset the current destination.
• A conflicting mapping pauses affected work.
• An unrelated chat with the same title is never merged.
• Stored identifiers survive serialization and database reads without truncation.

The UnifyPort boundary

UnifyPort’s unofficial interface uses message.received with provider, account_id, and data.conversation.id. Keep those identifiers in their own namespace rather than assuming a Bot API chat ID can be substituted directly.

The public event reference does not document migrate_to_chat_id, migrate_from_chat_id, or a guaranteed old-to-new migration mapping. Neither group.updated nor conversation.updated should be treated as such a guarantee. For a connected Telegram messaging account, inspect the list-conversations contract and use returned conversation_id values for reconciliation. A matching title alone is not evidence of continuity; unresolved relationships need review.

For event intake, configure signing_secret and follow webhook delivery verification. UnifyPort has no REST message-history read API or guaranteed replay. Listing current conversations cannot reconstruct missing messages or supply an undocumented migration relationship.

FAQ

Should I change the webhook URL after a group becomes a supergroup?

A new chat identifier is a routing issue, not by itself evidence that the webhook URL needs changing. Inspect the received update and stored destination first.

Can I derive the new ID from the old one?

Use the migration fields supplied by Telegram. Do not construct a destination by adding a prefix or modifying digits.

Should I move every historical message to the new chat ID?

No. Preserve original chat/message pairs. Link the conversations at the application level without claiming that message identifiers were translated.

Does UnifyPort automatically expose the Bot API migration fields?

Its public contract does not document that behavior. Reconcile connected-account identifiers through its own documented API and review uncertain mappings.

Next step and sources

Audit where your sender resolves its destination, especially for queued jobs. For connected-account reconciliation, start with List conversations.

• Telegram Bot API: Message and ResponseParameters, checked on 2026-09-21.
• UnifyPort standard event reference.