Obtaining User Phone Numbers via Telegram Bot API: A Practical Guide Based on Bot 2.0

Introduction

In developing applications based on the Telegram Bot API, user identification is a common requirement. Many developers wish to directly obtain user phone numbers via telegramUserId to streamline interactions. However, the design principles of the Telegram Bot API emphasize user privacy, limiting direct phone number queries. Based on the best answer (Answer 1) from the Q&A data, this article delves into the solution introduced in Bot 2.0, supplemented by insights from other answers.

Bot 2.0 and Phone Number Acquisition Mechanism

The 2.0 version of the Telegram Bot API introduced the KeyboardButton.WithRequestContact feature, allowing developers to request users to share their phone numbers. This mechanism relies on user consent rather than passive queries. When a user clicks a specific button, the Telegram client prompts for confirmation, ensuring privacy control remains with the user. This approach aligns with Telegram's security policies, preventing unauthorized data access.

From a technical perspective, the KeyboardButton class provides the WithRequestContact method to create buttons for contact information requests. In C# using the Telegram.Bot library, this can be integrated as shown in the following code example:

ReplyKeyboardMarkup requestReplyKeyboard = new(
    new[]
    {
        KeyboardButton.WithRequestContact("Send my phone Number"),
    });

await botClient.SendTextMessageAsync(chatId: message.Chat.Id,
                                    text: "Could you please send your phone number?",
                                    replyMarkup: requestReplyKeyboard);

Upon user response, the message type changes to MessageType.Contact, and developers can extract the phone number from the message.Contact.PhoneNumber property. For example:

if (message.Type == MessageType.Contact && message.Contact != null)
{
    Console.WriteLine($"Phone number: {message.Contact.PhoneNumber}");
}

Limitations of Traditional Methods

Prior to Bot 2.0, the Telegram Bot API did not provide a direct interface for obtaining phone numbers. As noted in Answer 2, the API only returns basic user information such as userid, first_name, and chat_id, with phone numbers treated as sensitive data under strict protection. Developers needing phone numbers had to rely on explicit requests or lower-level Telegram API methods, which could involve complex authorization processes.

Answer 3 further illustrates the user interaction process through visual examples: after a user sends the /myNumber command, the bot replies with a message containing a request button; upon clicking and confirming, the phone number is sent. This highlights the importance of user control, mitigating risks of automated data collection.

Privacy and Security Considerations

Telegram's design philosophy emphasizes end-to-end encryption and user privacy, leading to a conservative approach in the Bot API for phone number handling. Through KeyboardButton.WithRequestContact, Telegram ensures full user control over personal data, complying with regulations like GDPR. Developers should follow best practices, requesting phone numbers only when necessary and clearly communicating data usage to users.

In code implementation, it is advisable to add error handling and logging to address scenarios such as user refusal or network issues. For instance, the HandleUpdateAsync method can be extended to handle different update types:

public static async Task HandleUpdateAsync(ITelegramBotClient botClient, Update update, CancellationToken cancellationToken)
{
    var handler = update.Type switch
    {
        UpdateType.Message => BotOnMessageReceived(botClient, update.Message!),
        _ => UnknownUpdateHandlerAsync(botClient, update)
    };

    try
    {
        await handler;
    }
    catch (Exception exception)
    {
        await HandleErrorAsync(botClient, exception, cancellationToken);
    }
}

Conclusion

Obtaining user phone numbers via the Telegram Bot API is feasible but must rely on the Bot 2.0 KeyboardButton.WithRequestContact feature, dependent on user consent. This article details implementation steps, code examples, and privacy considerations, providing a practical guide for developers. Compared to direct queries, this method is safer and more compliant, fostering user trust in applications. Moving forward, developers should monitor official documentation for updates to adapt to new features.