Telegram's username field can be an empty string — and which handle to use instead

Telegram's username field can be an empty string, which may lead to confusion when constructing links. The person who founded Telegram, Durov, has an account with an empty username field. When you attempt to build a link using chat.username or chat.id, it will result in t.me/1006503122, a URL that does not resolve for human users.

Every response from Telegram's API is live output, captured on September 16, 2026. A channel can have multiple public handles, and when it does, the primary username field goes empty, and the handles move into a usernames array. Each entry in the usernames array carries its own flags, indicating its activity status and editability.

There can be up to six active handles for a single channel. Only one of these handles is editable, and that is the one that belongs to the channel owner. The flags are presented in bitfield form, with 2 representing the active bit alone and 3 representing the active and editable bits. The active and editable handle is the one the owner controls and the one that should be used in a link.

There are two main shapes of the usernames data returned by the Telegram API. The first shape has a username field and usernames set to null, indicating a single handle. The second shape has an empty username field and usernames as an array, indicating multiple handles. Code that handles only one of these shapes is likely to be incorrect half the time.

The correct way to determine the handle that should be used in a link is to look for the active and editable handle first, then any active handle, and finally, the plain username field. To achieve this, you can use a function that checks the usernames array first, then falls back to the username field if the array is not available. The function should return None if no suitable handle can be found. This approach ensures that the link built from the handle is valid and points to the correct location.