WTelegramClient Documentation

WTelegramClient supports Secret Chats with the following characteristics:

• Compatibility: May not support very old Telegram clients (pre-2018 using MTProto 1.0).
• Storage: Outgoing messages are not stored by the library. Incoming messages are not stored on disk by default (storage is the user's responsibility).
• Message Ordering: By default, DecryptMessage uses fillGaps: true, which ensures messages are delivered in the correct order by keeping them in memory until missing messages are obtained. If missing messages are never received, incoming messages may get stuck.
• Session Files: Secret Chat file data is specific to the logged-in user. Use a unique file name if switching users.
• Filtering Requests: To accept Secret Chat requests only from a specific user, check the OnUpdates handler:

await Secrets.HandleUpdate(ue, ue.chat is EncryptedChatRequested ecr && ecr.admin_id == EXPECTED_USER_ID);

• Key Negotiation: New encryption keys are negotiated every 100 messages or every week. If negotiation fails to complete by 200 messages, the chat is aborted.

Many API responses (including UpdatesBase) contain users and chats dictionaries. These dictionaries provide the necessary details and access_hash required to interact with specific entities.

To work with these entities effectively:

1. Use IPeerResolver: Root structures that contain these dictionaries implement IPeerResolver. You can call .UserOrChat(peer) to resolve a Peer object into a User or a ChatBase (like Chat or Channel).
2. Use CollectUsersChats: Use this helper method to aggregate users and chats into your own local dictionaries. This is crucial for handling Updates where Telegram might send incomplete structures.
3. Handle Missing Data: If you receive an UpdateShortMessage or UpdateShortChatMessage for a user not in your local dictionaries, use Updates_GetDifference to fetch the missing information.

private Dictionary<long, User> _users = new();
private Dictionary<long, ChatBase> _chats = new();

// Collecting from dialogs
var dialogs = await client.Messages_GetAllDialogs();
dialogs.CollectUsersChats(_users, _chats);

// Collecting from updates
private async Task OnUpdates(UpdatesBase updates)
{
    updates.CollectUsersChats(_users, _chats);
    
    // Resolving a peer
    var firstPeer = dialogs.UserOrChat(dialogs.dialogs[0].Peer);
    if (firstPeer is User firstUser) Console.WriteLine($"First dialog is with user {firstUser}");
    else if (firstPeer is ChatBase firstChat) Console.WriteLine($"First dialog is {firstChat}");
}

// Recovering gaps for short messages
if (updates is UpdateShortMessage usm && !_users.ContainsKey(usm.user_id))
{
    var fullDiff = await client.Updates_GetDifference(usm.pts - usm.pts_count, usm.date, 0);
    fullDiff.CollectUsersChats(_users, _chats);
}

The library uses specific terminology that may differ from the standard Telegram user interface:

• Channel: A large or public chat group (often called a supergroup) or a broadcast channel.
• Chat: A private basic chat group with fewer than 200 members. Note that most groups you interact with are actually Channel types.
• chats: A general term referring to either Chat or Channel objects (excludes private user DMs).
• Peer: An abstraction representing a Chat, Channel, or User.
• Dialog: The status of a chat with a Peer (includes last message, unread count, etc.), representing a single line in a chat list.
• Access Hash: A required security token used when interacting with users, channels, or other resources.
• DC (DataCenter): Regional servers used by Telegram.
• Session / Authorization: The pairing between a specific device and a phone number.
• Participant: A member or subscriber of a chat group or channel.

Unlike the Telegram Bot API, the Telegram Client API requires an access_hash to interact with channels, users, and other entities. Using only an ID will result in errors like CHANNEL_INVALID or USER_ID_INVALID.

An access_hash is a proof that the logged-in user is authorized to access that specific resource.

How to obtain an access_hash:

Obtain description structures (such as Channel, User, Photo, or Document) through:

• Receiving updates.
• Querying API methods like Messages_GetAllDialogs or Contacts_ResolveUsername.
• Using helper methods like UserOrChat or CollectUsersChats.

How to use it in API calls:

When calling an API method that requires an Input... structure (like InputPeer, InputChannel, or InputUser):

• Recommended: Pass the description structure (e.g., the User or Channel object) directly. The library uses implicit conversion operators to automatically create the required Input... structure.
• Manual: Extract the access_hash from the description structure and manually construct the Input... object.

For more control over the login flow (e.g., in GUI apps like WinForms or web apps like ASP.NET), use the simplified constructor and the Login method. This allows you to handle each step of the authentication process manually by checking the string returned by client.Login(loginInfo).

Common return values from client.Login:

• "verification_code": Next step is providing the code.
• "name": Next step is providing first/last name for sign-up.
• "password": Next step is providing the 2FA password.
• default: No specific config needed, continue loop.

WTelegram.Client client = new WTelegram.Client(YOUR_API_ID, "YOUR_API_HASH");
await DoLogin("+12025550156");

async Task DoLogin(string loginInfo)
{
   while (client.User == null)
      switch (await client.Login(loginInfo))
      {
         case "verification_code": Console.Write("Code: "); loginInfo = Console.ReadLine(); break;
         case "name": loginInfo = "John Doe"; break;
         case "password": loginInfo = "secret!"; break;
         default: loginInfo = null; break;
      }
   Console.WriteLine($"We are logged-in as {client.User} (id {client.User.id})");
}

You can retrieve contacts using two different approaches:

1. Simple Method: Use Contacts_GetContacts() to get a list of contacts currently in the account.
2. GDPR Export (Takeout) Method: For a more comprehensive export, use the Account_InitTakeoutSession system. This involves initializing a session, invoking methods via InvokeWithTakeout, and finally finishing the session with Account_FinishTakeoutSession.

// Simple Method
var contacts = await client.Contacts_GetContacts();
foreach (User contact in contacts.users.Values)
    Console.WriteLine($"{contact} {contact.phone}");

// Takeout Method
using TL.Methods;
var takeout = await client.Account_InitTakeoutSession(contacts: true);
var finishTakeout = new Account_FinishTakeoutSession();
try
{
    var savedContacts = await client.InvokeWithTakeout(takeout.id, new Contacts_GetSaved());
    foreach (SavedPhoneContact contact in savedContacts)
        Console.WriteLine($"{contact.first_name} {contact.last_name} {contact.phone}, added on {contact.date}");
    finishTakeout.flags = Account_FinishTakeoutSession.Flags.success;
}
finally
{
    await client.InvokeWithTakeout(takeout.id, finishTakeout);
}

WTelegramClient provides a simpler and more secure approach than TLSharp.

Key Migration Points:

• Method Calling: All API methods have dedicated async methods. Use the pattern await client.Method_Name(params). Note that in the method name, dots are replaced with underscores (e.g., Auth_SendCode becomes Auth_SendCode).
• Session Management: Sessions are created or resumed automatically on startup. WTelegramClient session files are incompatible with TLSharp .dat files; you must create new sessions.
• Simplified Login: Do not manually call Auth_SendCode, SignIn, or SignUp. Instead, call await client.LoginUserIfNeeded() after creating the client. The library automatically handles:
  • Resuming existing sessions.
  • 2FA password requests.
  • Email registration and verification.
  • Account sign-up (first/last name).
  • Resending verification codes.
• Features: WTelegramClient supports MTProto v2.0, transport obfuscation, protocol security checks, MTProto Proxy, and real-time updates.