WTelegramClient

https://github.com/wiz0u/wtelegramclient
Admin
WTelegramClient is a C# and .NET library that allows programmatic connection to Telegram and control...
Tokens:758,769
Snippets:4,148
Trust Score:7.4
License:MIT
Update:6 days ago
Show doc for...
Tokens:
Raw
### Setup WTelegramClient with environment variables

Source: https://github.com/wiz0u/wtelegramclient/blob/master/EXAMPLES.md

Required starting lines for a functional Program.cs. Uses environment variables for configuration (api_id, api_hash, phone_number) and logs in the user if needed.

```csharp
using System;
using System.Linq;
using TL;

using var client = new WTelegram.Client(Environment.GetEnvironmentVariable);
await client.LoginUserIfNeeded();
```

--------------------------------

### SendMediaAsync usage example

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/client-messaging.md

Example showing how to upload a file and send it as a video message.

```csharp
var inputFile = await client.UploadFileAsync("cat.mp4", progress: null);
var msg = await client.SendMediaAsync(peer, "Look at this cat", inputFile, "video");
```

--------------------------------

### SendAlbumAsync usage example

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/client-messaging.md

Example showing how to construct a list of InputMedia objects and send them as an album.

```csharp
var medias = new List<InputMedia>
{
    new InputMediaUploadedPhoto { file = photo1 },
    new InputMediaUploadedPhoto { file = photo2 },
};
var messages = await client.SendAlbumAsync(peer, medias, caption: "Trip photos");
```

--------------------------------

### Interactive login loop example

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/client-login.md

Shows a complete interactive login loop using client.Login. It repeatedly calls Login with the current loginInfo, handles verification_code, name, password, and defaults to null to finish. The example starts with a phone number and prints the logged-in user.

```csharp
WTelegram.Client client = new(apiId, apiHash);
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($"Logged in as {client.User}");
}
await DoLogin("+12025550156");
```

--------------------------------

### Minimal WTelegramClient login example

Source: https://github.com/wiz0u/wtelegramclient/blob/master/README.md

Use this snippet as a starting point for a console app. It creates a WTelegram.Client, calls LoginUserIfNeeded, and prints the logged-in user. The call handles interactive prompts for api_hash, api_id, phone_number, verification_code, and optional sign-up or 2FA steps.

```csharp
static async Task Main(string[] _)
{
    using var client = new WTelegram.Client();
    var myself = await client.LoginUserIfNeeded();
    Console.WriteLine($"We are logged-in as {myself} (id {myself.id})");
}
```

--------------------------------

### Example: Config function and client instantiation

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/client.md

Shows a config provider function and how to create a client and log in using LoginUserIfNeeded.

```csharp
static string Config(string what) => what switch
{
    "api_id" => "123456",
    "api_hash" => "0123456789abcdef0123456789abcdef",
    "phone_number" => "+12025550156",
    "verification_code" => AskCode(), // your app-specific prompt
    _ => null,
};
using var client = new WTelegram.Client(Config);      // configProvider variant
var myself = await client.LoginUserIfNeeded();
```

--------------------------------

### UpdateManager usage example

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/update-manager.md

Shows how to create an UpdateManager, handle updates, and save state on exit.

```csharp
using var client = new WTelegram.Client(Config);
var manager = client.WithUpdateManager(OnUpdate, "Updates.state");   // or new UpdateManager(client, OnUpdate, ...)
Task OnUpdate(TL.Update update)
{
    if (update is UpdateNewMessage unm)
        Console.WriteLine($"{manager.UserOrChat(unm.message.Peer)}: {unm.message.message}");
    return Task.CompletedTask;
}
await client.LoginUserIfNeeded();
// ... on exit:
manager.SaveState("Updates.state");
```

--------------------------------

### HandleUpdate Implementation Example

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/secret-chats.md

Example of feeding UpdateEncryption updates into the secretChats handler within the OnUpdates callback.

```csharp
client.OnUpdates = async updates =>
{
    foreach (var update in updates.UpdateList)
        if (update is UpdateEncryption ue)
            await secretChats.HandleUpdate(ue); // auto-accept
};
```

--------------------------------

### Example: Using HttpMode for stateless HTTP transport

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/client.md

Shows how to create a client, enable HTTP mode, and then log in. Must be called before any connection attempt.

```csharp
var client = new WTelegram.Client(Config);
client.HttpMode();                 // stateless HTTP transport
await client.LoginUserIfNeeded();
```

--------------------------------

### LoginWithQRCode Usage Example

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/client-login.md

Demonstrates how to implement the QR code display callback using the QRCoder package to handle the login URL.

```csharp
using var qrGenerator = new QRCodeGenerator(); // QRCoder package
var user = await client.LoginWithQRCode(url =>
{
    using var qrData = qrGenerator.CreateQrCode(url, QRCodeGenerator.ECCLevel.M);
    Console.WriteLine($"Scan: {url}");
}, logoutFirst: true);
```

--------------------------------

### Log property usage examples

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/helpers.md

Examples of assigning the Log delegate to redirect logs to an ILogger, a file, or to disable logging.

```csharp
WTelegram.Helpers.Log = (lvl, str) => logger.Log((LogLevel)lvl, str);      // ASP.NET ILogger
WTelegram.Helpers.Log = (lvl, str) => File.AppendAllText("wtelegram.log", $"{DateTime.Now} [{lvl}] {str}{Environment.NewLine}");
WTelegram.Helpers.Log = (lvl, str) => { };                                  // disable (not recommended)
```

--------------------------------

### HtmlText round-trip example

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/services.md

Demonstrates converting HTML to entities and back to HTML, showing a round-trip conversion. The example uses null for the client parameter and shows the expected output comment.

```csharp
string html = "Visit <a href=\"https://example.com\">our site</a>";
var entities = TL.HtmlText.HtmlToEntities(null, ref html);
string back = TL.HtmlText.EntitiesToHtml(null, html, entities);   // round-trip
```

--------------------------------

### Example: Using InputCheckPassword for 2FA login

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/client.md

Shows how to retrieve the account password and check it with InputCheckPassword, then authenticate with Auth_CheckPassword. Requires a logged-in client and a valid 2FA password.

```csharp
var accountPassword = await client.Account_GetPassword();
var inputCheck = await WTelegram.Client.InputCheckPassword(accountPassword, "my2FApassword");
var auth = await client.Auth_CheckPassword(inputCheck);
```

--------------------------------

### UploadFileAsync Usage Example

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/client-transfers.md

Demonstrates uploading a file from a local path with a progress callback and subsequently sending it as media.

```csharp
var inputFile = await client.UploadFileAsync(@"C:\img\photo.jpg", (sent, total) => Console.WriteLine($"{sent}/{total}"));
await client.SendMediaAsync(peer, "See this!", inputFile, "photo");
```

--------------------------------

### UploadFile usage example

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/secret-chats.md

Example of uploading a file and sending it as a secret chat message. Creates a DecryptedMessageMediaDocument, uploads the file, and sends the message with the encrypted file.

```csharp
var media = new TL.Layer73.DecryptedMessageMediaDocument { thumb = ..., thumb_w = ..., ... };
var encFile = await secretChats.UploadFile(File.OpenRead("doc.pdf"), media);
await secretChats.SendMessage(chatId, new TL.Layer73.DecryptedMessage
{
    random_id = Helpers.RandomLong(), media = media
}, file: encFile);
```

--------------------------------

### Custom TCP handler example

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/client.md

An example of configuring a custom TcpHandler to route connections through a SOCKS proxy.

```csharp
client.TcpHandler = async (host, port) =>
{
    var tcp = new TcpClient();
    await tcp.ConnectAsync("127.0.0.1", 9050); // SOCKS proxy port
    // ... do SOCKS handshake, then:
    return tcp;
};
```

--------------------------------

### MarkdownToEntities usage example

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/services.md

Example showing how to convert Markdown text to entities and send the resulting plain text message.

```csharp
string text = "*Hi*, check [this](https://example.com)";
var entities = TL.Markdown.MarkdownToEntities(null, ref text);
await client.SendMessageAsync(peer, text, entities: entities);   // text is now plain
```

--------------------------------

### OnUpdates event handler example

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/client.md

An example of an async handler for the OnUpdates event to process new messages.

```csharp
client.OnUpdates = async updates =>
{
    foreach (var update in updates.UpdateList)
        if (update is UpdateNewMessage unm)
            Console.WriteLine($"{unm.message.Peer.ID}: {unm.message.message}");
    return Task.CompletedTask;
};
```

--------------------------------

### Catching Exceptions

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/errors.md

Example of catching TL.RpcException and WTException.

```APIDOC
## Catching Exceptions

```csharp
try { await client.SendMessageAsync(peer, "hi"); }
catch (TL.RpcException ex)
{
    Console.WriteLine($"{ex.Code} {ex.Message} X={ex.X}"); // e.g. 420 FLOOD_WAIT_X X=60
}
catch (WTException ex) { ... }   // RpcException is also a WTException
```
```

--------------------------------

### SendMessageAsync Usage Example

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/client-messaging.md

Demonstrates sending a simple message to self and a message with Markdown formatting and a link preview.

```csharp
using TL;
await client.SendMessageAsync(InputPeer.Self, "Hello, World!");
await client.SendMessageAsync(chat, "Important [link](https://example.com)",
    entities: TL.Markdown.MarkdownToEntities(null, ref mdText), preview: LinkPreview.AboveText);
```

--------------------------------

### DecryptMessage usage example

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/secret-chats.md

Shows how to handle incoming updates and decrypt secret chat messages. The example subscribes to client.OnUpdates, iterates over updates, and for each UpdateNewEncryptedMessage it decrypts the message and prints the decrypted text.

```csharp
client.OnUpdates += async updates =>
{
    foreach (var update in updates.UpdateList)
        if (update is UpdateNewEncryptedMessage uem)
            foreach (var decrypted in secretChats.DecryptMessage(uem.message))
                Console.WriteLine($"Secret: {decrypted.Message}");
};
```

--------------------------------

### AnalyzeInviteLink Usage Example

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/client-chats.md

Demonstrates how to call AnalyzeInviteLink with a URL and join parameter, then output the chat title.

```csharp
var chat = await client.AnalyzeInviteLink("https://t.me/+InviteHash", join: true);
Console.WriteLine(chat.Title);
```

--------------------------------

### Catching WTException example

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/helpers.md

Shows how to catch WTException to handle both local errors and Telegram RPC errors.

```csharp
try { await client.SendMessageAsync(peer, "hello"); }
catch (WTException ex)
{
    Console.WriteLine($"Failed: {ex.Message}");
}
```

--------------------------------

### Invoke low-level usage example

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/client-login.md

Demonstrates low-level usage of the Invoke method to perform Ping and GetFutureSalts operations with error handling.

```csharp
using TL;
var pong = await client.Invoke<TL.Methods.Ping>(new TL.Methods.Ping { ping_id = 42 });
try
{
    var result = await client.Invoke<TL.Methods.GetFutureSalts>(new TL.Methods.GetFutureSalts { num = 8 });
}
catch (RpcException ex)
{
    Console.WriteLine($"RPC error {ex.Code}: {ex.Message} (X={ex.X})");
}
```

--------------------------------

### SendMessage usage example

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/secret-chats.md

Shows how to request a secret chat with a user, wait for remote acceptance via HandleUpdate, and then send a message. The example creates a TL.Layer73.DecryptedMessage with a random_id and a simple text message.

```csharp
var id = await secretChats.Request(InputUser.Self ? user : otherUser);
// (wait for remote acceptance via HandleUpdate)
var msg = new TL.Layer73.DecryptedMessage { random_id = Helpers.RandomLong(), message = "Hello 👋" };
await secretChats.SendMessage(id, msg);
```

--------------------------------

### Example: Using Messages_GetAllChats

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/client-transfers.md

Retrieves all chats and prints each chat's id and title.

```csharp
var chats = await client.Messages_GetAllChats();
foreach (var (id, chat) in chats.chats)
    Console.WriteLine($"{id}: {chat.Title}");
```

--------------------------------

### Retrieve and Iterate Forum Topics

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/client-transfers.md

Example usage of Channels_GetAllForumTopics to fetch topics and print their IDs and titles to the console.

```csharp
var topics = await client.Channels_GetAllForumTopics(peer);
foreach (var topic in topics.topics)
    Console.WriteLine($"{topic.ID}: {topic.Title}");
```

--------------------------------

### Use SOCKS/HTTPS proxy with TcpHandler

Source: https://github.com/wiz0u/wtelegramclient/blob/master/EXAMPLES.md

Configure a SOCKS/HTTPS proxy by setting the TcpHandler delegate. Requires a proxy library like StarkSoftProxy or xNetStandard. The example uses Socks5ProxyClient with placeholder credentials.

```csharp
using var client = new WTelegram.Client(Environment.GetEnvironmentVariable);
client.TcpHandler = async (address, port) =>
{
    var proxy = new Socks5ProxyClient(ProxyHost, ProxyPort, ProxyUsername, ProxyPassword);
    //var proxy = xNet.Socks5ProxyClient.Parse("host:port:username:password");
    return proxy.CreateConnection(address, port);
};
await client.LoginUserIfNeeded();
```

--------------------------------

### OpenChat usage example with CancellationTokenSource

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/client-chats.md

Shows how to call OpenChat with a cancellation token that times out after five minutes. The using statement ensures the token source is disposed, and the method will stop monitoring when the token is cancelled.

```csharp
using var cts = new CancellationTokenSource(TimeSpan.FromMinutes(5));
client.OpenChat(channel, cts.Token);
```

--------------------------------

### Raw ping example using TL.Methods.Ping

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/layer.md

Invokes the low-level Ping method with a ping_id and prints the returned msg_id. Requires a connected client instance.

```csharp
using TL;
var pong = await client.Invoke<TL.Methods.Ping>(new TL.Methods.Ping { ping_id = 12345 });
Console.WriteLine(pong.msg_id);
```

--------------------------------

### Example calls to generated Telegram API methods

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/generated-schema.md

Shows how to call various Telegram API methods using the generated client. Each call returns the parsed result type or a primitive. The comments show the corresponding TL method names.

```csharp
using TL;

var chats = await client.Messages_GetAllChats();                       // messages.getAllChats
var dialogs = await client.Messages_GetDialogs(limit: 100);            // messages.getDialogs
var history = await client.Messages_GetHistory(peer);                  // messages.getHistory
var me = await client.Users_GetUsers(InputUser.Self);                  // users.getUsers
var sent = await client.Messages_SendMessage(peer, "Hello", Helpers.RandomLong()); // messages.sendMessage
var config = await client.Help_GetConfig();                            // help.getConfig
var chatFull = await client.Channels_GetFullChannel(channel);          // channels.getFullChannel
```

--------------------------------

### Download largest photo version to file

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/client-transfers.md

Example showing how to download the largest version of a photo to a file using DownloadFileAsync. The output stream is not disposed by the method.

```csharp
// download the largest photo version to a file
using var output = File.Create("photo.jpg");
var fileType = await client.DownloadFileAsync(message.media is MessageMediaPhoto p ? p.photo : null, output);
```

--------------------------------

### Obtain and send the main invite link

Source: https://github.com/wiz0u/wtelegramclient/blob/master/EXAMPLES.md

Gets the full chat information to retrieve the main exported invite link and sends it to a user.

```APIDOC
## Obtain and send the main invite link

### Description
Gets the full chat information to retrieve the main exported invite link and sends it to a user.

### Method
Client method calls

### Endpoint
client.GetFullChat(chat)
client.SendMessageAsync(user, message)

### Parameters
- **chat** (InputChat) - Required - The target chat.
- **user** (InputUser) - Required - The user to send the invite link to.
- **message** (string) - Required - The message containing the invite link.

### Request Example
```csharp
var mcf = await client.GetFullChat(chat);
var invite = (ChatInviteExported)mcf.full_chat.ExportedInvite;
await client.SendMessageAsync(user, "Join our group with this link: " + invite.link);
```

### Response
- **mcf** (Messages_ChatFull) - Contains the full chat information.
- **invite** (ChatInviteExported) - The exported invite link.
```

--------------------------------

### Client constructor with configProvider, startSession, saveSession

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/client.md

Constructor signature for session persistence via byte-array callbacks, suitable for database storage.

```csharp
public Client(Func<string, string> configProvider, byte[] startSession, Action<byte[]> saveSession)
```

--------------------------------

### Client(Func<string, string> configProvider, byte[] startSession, Action<byte[]> saveSession)

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/client.md

Creates a WTelegram.Client instance with a config callback and byte-array callbacks for session persistence. This is the documented way to store sessions in a database.

```APIDOC
## Client(Func<string, string> configProvider, byte[] startSession, Action<byte[]> saveSession)

### Description
Creates a WTelegram.Client instance with a config callback and byte-array callbacks for session persistence. This is the documented way to store sessions in a database.

### Method
Constructor

### Parameters
#### Constructor Parameters
- **configProvider** (`Func<string, string>`) - Required - Config callback
- **startSession** (byte[]) - Required - Initial serialized session state (may be empty/`[]`)
- **saveSession** (`Action<byte[]>`) - Required - Receives the updated serialized session state

### Example
```csharp
public Client(Func<string, string> configProvider, byte[] startSession, Action<byte[]> saveSession)
```
```

--------------------------------

### Initialize UpdateManager and Save State

Source: https://github.com/wiz0u/wtelegramclient/blob/master/FAQ.md

Shows how to initialize the UpdateManager with or without state recovery and how to save the state after the client is disposed.

```csharp
// if you don't care about missed updates while your program was down:
var manager = client.WithUpdateManager(OnUpdate);

// if you want to recover missed updates using the state saved on the last run of your program
var manager = client.WithUpdateManager(OnUpdate, "Updates.state");
// to save the state later, preferably after disposing the client:
manager.SaveState("Updates.state")
```

--------------------------------

### Messages_Search usage example

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/client-messaging.md

Example of using Messages_Search with InputMessagesFilterPhotoVideo to search for photos with query 'cats' and limit 50. Iterates over results.Messages and prints each message ID.

```csharp
var results = await client.Messages_Search<InputMessagesFilterPhotoVideo>(peer, "cats", limit: 50);
foreach (var msg in results.Messages) Console.WriteLine(msg.ID);
```

--------------------------------

### Client(int apiID, string apiHash, string sessionPathname = null)

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/client.md

Creates a WTelegram.Client instance using a simple constructor that builds an internal config callback for api_id, api_hash, and session_pathname. Login is then driven by client.Login(loginInfo) or LoginUserIfNeeded.

```APIDOC
## Client(int apiID, string apiHash, string sessionPathname = null)

### Description
Creates a WTelegram.Client instance using a simple constructor that builds an internal config callback for api_id, api_hash, and session_pathname. Login is then driven by client.Login(loginInfo) or LoginUserIfNeeded.

### Method
Constructor

### Parameters
#### Constructor Parameters
- **apiID** (int) - Required - Telegram application API ID
- **apiHash** (string) - Required - Telegram application API hash
- **sessionPathname** (string) - Optional (default: null) - Session file path (`session_pathname` config)

### Example
```csharp
public Client(int apiID, string apiHash, string sessionPathname = null)
```
```

--------------------------------

### LoginUserIfNeeded usage example

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/client-login.md

Example of calling LoginUserIfNeeded with custom CodeSettings that allow app hash and missed call verification. Uses a WTelegram.Client instance with a Config callback.

```csharp
using var client = new WTelegram.Client(Config);
var settings = new TL.CodeSettings { flags = TL.CodeSettings.Flags.allow_app_hash | TL.CodeSettings.Flags.allow_missed_call };
var me = await client.LoginUserIfNeeded(settings);
```

--------------------------------

### Client constructor with configProvider and sessionStore

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/client.md

Constructor signature for the canonical constructor with a Stream session store.

```csharp
public Client(Func<string, string> configProvider = null, Stream sessionStore = null)
```

--------------------------------

### InputUser and InputChannel class definitions

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/types.md

Shows the hand-written partial class definitions for InputUserBase, InputUserSelf, InputUser, and InputChannel. InputUser and InputChannel require an access_hash, which must be obtained from the User or Channel structures first. Implicit conversions to InputPeerUser and InputPeerChannel are provided.

```csharp
partial class InputUserBase { public abstract long? UserId { get; } }
partial class InputUserSelf { public override long? UserId => null; }
public sealed partial class InputUser : InputUserBase   // 0xF21158C6
{
	public long user_id;
	public long access_hash;
	public long? UserId => user_id;
	public static InputUserSelf Self => new();
	public InputUser(long user_id, long access_hash);
	public static implicit operator InputPeerUser(InputUser user);
}
partial class InputChannel   // 0x40F202FD (channel)
{
	public long channel_id;
	public long access_hash;
	public InputChannel(long channel_id, long access_hash);
	public static implicit operator InputPeerChannel(InputChannel channel);
}
```

--------------------------------

### Client(Func<string, string> configProvider = null, Stream sessionStore = null)

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/client.md

The canonical constructor for WTelegram.Client. Accepts a config callback and a Stream for session storage. If session_key config is null, the session is encrypted with api_hash.

```APIDOC
## Client(Func<string, string> configProvider = null, Stream sessionStore = null)

### Description
The canonical constructor for WTelegram.Client. Accepts a config callback and a Stream for session storage. If session_key config is null, the session is encrypted with api_hash.

### Method
Constructor

### Parameters
#### Constructor Parameters
- **configProvider** (`Func<string, string>`) - Optional (default: `DefaultConfigOrAsk`) - Config callback; queried at least for `api_id`, `api_hash`, `session_pathname`. Returning `null` falls back to `DefaultConfig` or a console prompt
- **sessionStore** (Stream) - Optional (default: new `SessionStore(Config("session_pathname"))`) - Must support initial `Length` & `Read()` of a saved session, then `Write()` of updates; other members are ignored

### Example
```csharp
public Client(Func<string, string> configProvider = null, Stream sessionStore = null)
```
```

--------------------------------

### DeleteChat Method and Usage

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/client-chats.md

Method signature and example for deleting a chat. Corresponds to Messages_DeleteChat or Channels_DeleteChannel.

```csharp
public async Task<UpdatesBase> DeleteChat(InputPeer peer);
```

```csharp
var updates = await client.DeleteChat(peer);
```

--------------------------------

### Client constructor with apiID, apiHash, sessionPathname

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/client.md

Constructor signature for the simple constructor that builds an internal config callback.

```csharp
public Client(int apiID, string apiHash, string sessionPathname = null)
```

--------------------------------

### UploadFile and DownloadFile method signatures

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/secret-chats.md

Method signatures for UploadFile and DownloadFile. UploadFile encrypts the stream with AES-IGE, uploads it, stores size/key/iv in media.SizeKeyIV, and returns an InputEncryptedFile. DownloadFile downloads and decrypts, verifies the fingerprint, and returns the MIME type or null.

```csharp
public async Task<InputEncryptedFileBase> UploadFile(Stream stream, DecryptedMessageMedia media, Client.ProgressCallback progress = null);
public async Task<string> DownloadFile(EncryptedFile encryptedFile, DecryptedMessageMedia media, Stream outputStream, Client.ProgressCallback progress = null);
```

--------------------------------

### DeleteMessages Method and Usage

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/client-chats.md

Method signature and example for deleting specific messages by ID. Deletes messages for all participants.

```csharp
public Task<Messages_AffectedMessages> DeleteMessages(InputPeer peer, params int[] id);
```

```csharp
await client.DeleteMessages(peer, 123, 125, 130);
```

--------------------------------

### Configure WTelegram.Client with Environment.GetEnvironmentVariable

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/configuration.md

Pass Environment.GetEnvironmentVariable as the config callback to drive the library purely from environment variables. Every key in the configuration table becomes an environment variable; undefined ones behave as null answers.

```csharp
using var client = new WTelegram.Client(Environment.GetEnvironmentVariable);
```

```text
WTELEGRAM_SESSION_PATHNAME=/data/session  # (or e.g. api_id, api_hash, phone_number, ...)
```

--------------------------------

### OpenChat

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/client-chats.md

Starts monitoring a group or channel without joining. Continuously calls Updates_GetChannelDifference and raises differences as updates.

```APIDOC
## OpenChat

### Description
Starts monitoring a group or channel without joining. Continuously calls Updates_GetChannelDifference and raises differences as updates.

### Method
GET

### Endpoint
OpenChat

### Parameters
#### Path Parameters
- **channel** (InputChannel) - Required - Group/channel to monitor without joining
- **ct** (CancellationToken) - Required - Stop the monitoring loop

### Response
#### Success Response (200)
No return value (async void).

### Notes
Note the **async void** signature — exceptions are printed to the console when not cancelled. After cancelling, updates may still arrive for a few more seconds.

### Example
```csharp
using var cts = new CancellationTokenSource(TimeSpan.FromMinutes(5));
client.OpenChat(channel, cts.Token);
```
```

--------------------------------

### CollectUsersChats usage example

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/services.md

Shows how to call CollectUsersChats on the result of Messages_GetAllDialogs to populate user and chat dictionaries, which can be reused with UpdateManager or a custom cache.

```csharp
var dialogs = await client.Messages_GetAllDialogs();
dialogs.CollectUsersChats(myUsers, myChats);   // reuse with UpdateManager, or your own cache
```

--------------------------------

### Upload a streamable video with optional custom thumbnail

Source: https://github.com/wiz0u/wtelegramclient/blob/master/EXAMPLES.md

Uploads a video file and sends it as a streamable media message with a caption. Optionally uploads a custom thumbnail and attaches it. Requires Xabe.FFmpeg NuGet package for video metadata extraction; you can manually set width, height, and duration if known.

```csharp
var chats = await client.Messages_GetAllChats();
InputPeer peer = chats.chats[1234567890]; // the chat we want
const string videoPath = @"C:\...\video.mp4";
const string thumbnailPath = @"C:\...\thumbnail.jpg";

// Extract video information using Xabe.FFmpeg or similar library
var mediaInfo = await FFmpeg.GetMediaInfo(videoPath);
var videoStream = mediaInfo.VideoStreams.FirstOrDefault();
int width = videoStream?.Width ?? 0;
int height = videoStream?.Height ?? 0;
int duration = (int)mediaInfo.Duration.TotalSeconds;

// Upload video file
var inputFile = await Client.UploadFileAsync(videoPath);

// Prepare InputMedia structure with video attributes
var media = new InputMediaUploadedDocument(inputFile, "video/mp4",
    new DocumentAttributeVideo { w = width, h = height, duration = duration, 
        flags = DocumentAttributeVideo.Flags.supports_streaming });
if (thumbnailPath != null)
{
	// upload custom thumbnail and complete InputMedia structure
    var inputThumb = await client.UploadFileAsync(thumbnailPath);
    media.thumb = inputThumb;
    media.flags |= InputMediaUploadedDocument.Flags.has_thumb;
}

// Send the media message
await client.SendMessageAsync(peer, "caption", media);
```

--------------------------------

### Login method signature

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/client-login.md

Declares the public async method Login that takes a string loginInfo and returns a Task<string>. The return value is the name of the next configuration item needed, or null when login succeeds.

```csharp
public async Task<string> Login(string loginInfo);
```

--------------------------------

### Obsolete stubs

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/services.md

Deliberately obsolete extension methods that throw a WTException to guide TLSharp migrants toward new helper names. They are marked with [Obsolete] and error: true.

```APIDOC
## Obsolete stubs

### Description
Deliberately obsolete (`error: true`) extension methods that throw a `WTException`; they exist to guide TLSharp migrants toward the new helper names.

### Methods

#### Messages_GetChats
```csharp
[Obsolete("The method you're looking for is Messages_GetAllChats", true)]
public static Task<Messages_Chats> Messages_GetChats(this Client _);
```

#### Channels_GetChannels
```csharp
[Obsolete("The method you're looking for is Messages_GetAllChats", true)]
public static Task<Messages_Chats> Channels_GetChannels(this Client _);
```

#### Users_GetUsers
```csharp
[Obsolete("The method you're looking for is Messages_GetAllDialogs", true)]
public static Task<UserBase[]> Users_GetUsers(this Client _);
```

#### Messages_GetMessages
```csharp
[Obsolete("If you want to get all messages from a chat, use method Messages_GetHistory", true)]
public static Task<Messages_MessagesBase> Messages_GetMessages(this Client _);
```
```

--------------------------------

### Obsolete stub methods

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/services.md

Deliberately obsolete extension methods that throw a WTException to guide TLSharp migrants toward the new helper names. Each method is marked with [Obsolete(..., true)] to cause compile-time errors.

```csharp
[Obsolete("The method you're looking for is Messages_GetAllChats", true)]
public static Task<Messages_Chats> Messages_GetChats(this Client _);
[Obsolete("The method you're looking for is Messages_GetAllChats", true)]
public static Task<Messages_Chats> Channels_GetChannels(this Client _);
[Obsolete("The method you're looking for is Messages_GetAllDialogs", true)]
public static Task<UserBase[]> Users_GetUsers(this Client _);
[Obsolete("If you want to get all messages from a chat, use method Messages_GetHistory", true)]
public static Task<Messages_MessagesBase> Messages_GetMessages(this Client _);
```

--------------------------------

### Catching TL.RpcException and WTException

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/errors.md

Shows how to catch TL.RpcException and WTException when calling client methods. The example prints the error code, message, and X value (e.g., 420 FLOOD_WAIT_X X=60). RpcException is a subclass of WTException, so the catch order matters.

```csharp
try { await client.SendMessageAsync(peer, "hi"); }
catch (TL.RpcException ex)
{
    Console.WriteLine($"{ex.Code} {ex.Message} X={ex.X}"); // e.g. 420 FLOOD_WAIT_X X=60
}
catch (WTException ex) { ... }   // RpcException is also a WTException
```

--------------------------------

### Full custom config callback for WTelegram.Client

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/configuration.md

Provides a complete custom config callback that returns values for api_id, api_hash, session_pathname, phone_number, verification_code, and server_address. Unknown keys return null to use defaults or prompt. The client is then instantiated with this callback.

```csharp
static string Config(string what) => what switch
{
    "api_id" => Environment.GetEnvironmentVariable("TG_API_ID"),
    "api_hash" => Environment.GetEnvironmentVariable("TG_API_HASH"),
    "session_pathname" => "/var/data/user1.session",
    "phone_number" => "+12025550156",
    "verification_code" => GetCodeFromUser(),   // your UI
    "server_address" => "2>149.154.167.40:443", // test DC
    _ => null,                                   // use defaults / prompt
};
using var client = new WTelegram.Client(Config);
```

--------------------------------

### Collect users and chats with CollectUsersChats and resolve peers with UserOrChat

Source: https://github.com/wiz0u/wtelegramclient/blob/master/EXAMPLES.md

Use CollectUsersChats to aggregate user and chat details from API responses and updates into dictionaries, and UserOrChat to resolve a Peer into a User or ChatBase. The example shows initializing dictionaries, collecting from dialogs and updates, and resolving the first dialog's peer.

```csharp
private Dictionary<long, User> _users = new();
private Dictionary<long, ChatBase> _chats = new();
...
var dialogs = await client.Messages_GetAllDialogs();
dialogs.CollectUsersChats(_users, _chats);

private async Task OnUpdates(UpdatesBase updates)
{
    updates.CollectUsersChats(_users, _chats);
    ...
}

// example of UserOrChat usage:
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}");
```

--------------------------------

### Simplified login with WTelegram.Client and DoLogin method

Source: https://github.com/wiz0u/wtelegramclient/blob/master/README.md

Use this C# snippet to log in with WTelegramClient 3.0.0+ without a Config method. The DoLogin method loops until login completes, handling verification_code, name (for sign-up), and password (2FA) inputs. You can interrupt the loop with return and resume later by calling DoLogin again with the requested code.

```csharp
WTelegram.Client client = new WTelegram.Client(YOUR_API_ID, "YOUR_API_HASH"); // this constructor doesn't need a Config method
await DoLogin("+12025550156"); // initial call with user's phone_number
...
//client.Dispose(); // the client must be disposed when you're done running your userbot.

async Task DoLogin(string loginInfo) // (add this method to your code)
{
   while (client.User == null)
      switch (await client.Login(loginInfo)) // returns which config is needed to continue login
      {
         case "verification_code": Console.Write("Code: "); loginInfo = Console.ReadLine(); break;
         case "name": loginInfo = "John Doe"; break;    // if sign-up is required (first/last_name)
         case "password": loginInfo = "secret!"; break; // if user has enabled 2FA
         default: loginInfo = null; break;
      }
   Console.WriteLine($"We are logged-in as {client.User} (id {client.User.id})");
}
```

--------------------------------

### Load(Stream input)

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/secret-chats.md

Loads DH config and all chats from the provided stream. Throws WTException("Unrecognized Secrets format") if the format is invalid.

```APIDOC
## Load(Stream input)

### Description
Loads DH config and all chats from the provided stream. Throws WTException("Unrecognized Secrets format") if the format is invalid.

### Method
Load

### Parameters
#### Parameters
- **input** (Stream) - Required - The stream to read the serialized data from.

### Request Example
```csharp
secretChats.Load(inputStream);
```

### Response
No return value.

### Error Handling
- **WTException** - Thrown when the stream contains an unrecognized secrets format.
```

--------------------------------

### DownloadFileAsync overload signatures

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/client-transfers.md

Lists all five overloads of DownloadFileAsync, each accepting different media types (Photo, Document, InputFileLocationBase) and optional parameters for size, DC, and progress.

```csharp
public async Task<Storage_FileType> DownloadFileAsync(Photo photo, Stream outputStream, PhotoSizeBase photoSize = null, ProgressCallback progress = null);
public async Task<Storage_FileType> DownloadFileAsync(Photo photo, Stream outputStream, VideoSize videoSize, ProgressCallback progress = null);
public async Task<string> DownloadFileAsync(Document document, Stream outputStream, PhotoSizeBase thumbSize = null, ProgressCallback progress = null);
public async Task<Storage_FileType> DownloadFileAsync(Document document, Stream outputStream, VideoSize videoSize, ProgressCallback progress = null);
public async Task<Storage_FileType> DownloadFileAsync(InputFileLocationBase fileLocation, Stream outputStream, int dc_id = 0, long fileSize = 0, ProgressCallback progress = null);
```

--------------------------------

### Login

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/client-login.md

Implements the interactive login loop. Returns the name of the next configuration item needed to continue, or null when login succeeded.

```APIDOC
## Login

### Description
Implements the interactive login loop. Returns the name of the next configuration item needed to continue, or `null` when login succeeded. Intended for GUI/Web apps where a blocking Config callback is inconvenient.

### Method
Login

### Signature
```csharp
public async Task<string> Login(string loginInfo);
```

### Parameters
- **loginInfo** (string) - Required - First call: the phone number. Subsequent calls: the requested login value.

### Returns
- **string** - The name of the next configuration item needed to continue, or `null` when login succeeded. Possible values: `verification_code`, `name` (sign-up), `password` (2FA), `email` and `email_verification_code` (email registration).

### Example
```csharp
WTelegram.Client client = new(apiId, apiHash);
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($"Logged in as {client.User}");
}
await DoLogin("+12025550156");
```
```

--------------------------------

### LoginWithQRCode

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/client-login.md

Logs in a user via QR code. Displays the QR code URL via the provided callback, handles token migration and 2FA if needed.

```APIDOC
## LoginWithQRCode

### Description
Logs in a user via QR code. Displays the QR code URL via the provided callback, handles token migration and 2FA if needed.

### Method
LoginWithQRCode

### Signature
public async Task<User> LoginWithQRCode(Action<string> qrDisplay, long[] except_ids = null, bool logoutFirst = true, CancellationToken ct = default);

### Parameters
- **qrDisplay** (`Action<string>`) - Required - Callback receiving the `tg://login?token=...` URL to display as QR code
- **except_ids** (long[]) - Optional - Prevent login as these user ids
- **logoutFirst** (bool) - Optional - Log out first if a user session exists
- **ct** (CancellationToken) - Optional - Abort the wait if login isn't completed

### Returns
- **Task<User>** - The logged-in `TL.User`.

### Remarks
Handles `auth.exportLoginToken` / `Auth_ImportLoginToken` migration to another DC, waits for the user to scan the code (via `UpdateLoginToken` updates), and 2FA via `LoginPasswordNeeded` if needed.

### Example
```csharp
using var qrGenerator = new QRCodeGenerator(); // QRCoder package
var user = await client.LoginWithQRCode(url =>
{
    using var qrData = qrGenerator.CreateQrCode(url, QRCodeGenerator.ECCLevel.M);
    Console.WriteLine($"Scan: {url}");
}, logoutFirst: true);
```
```

--------------------------------

### Sample generated signature for Auth_SignIn

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/generated-schema.md

A sample generated method signature for Auth_SignIn, showing how optional parameters and flags are handled. It is marked [Obsolete] and directs to use LoginUserIfNeeded instead. The method builds an Auth_SignIn instance and calls client.Invoke.

```csharp
/// <summary>Signs in a user with a validated phone number. ...</summary>
[Obsolete("Use LoginUserIfNeeded instead of this method. ...")]
public static Task<Auth_AuthorizationBase> Auth_SignIn(this Client client, string phone_number, string phone_code_hash, string phone_code = null, EmailVerification email_verification = null)
	=> client.Invoke(new Auth_SignIn
	{
		flags = (Auth_SignIn.Flags)((phone_code != null ? 0x1 : 0) | (email_verification != null ? 0x2 : 0)),
		phone_number = phone_number,
		phone_code_hash = phone_code_hash,
		phone_code = phone_code,
		email_verification = email_verification,
	});
```

--------------------------------

### ConnectAsync

Source: https://github.com/wiz0u/wtelegramclient/blob/master/_autodocs/api-reference/client-login.md

Establishes the authenticated connection without negotiating user login. Usually not needed because LoginUserIfNeeded/LoginBotIfNeeded call it automatically.

```APIDOC
## ConnectAsync

### Description
Establishes the authenticated connection without negotiating user login. Usually you don't need it: `LoginUserIfNeeded`/`LoginBotIfNeeded` call it automatically.

### Method
ConnectAsync

### Signature
```csharp
public async Task ConnectAsync(bool quickResume = false);
```

### Parameters
- **quickResume** (bool) - Optional - Default: false - Attempt to resume the session immediately, without re-issuing `invokeWithLayer`/`initConnection`/`help.getConfig`.

### Details
Config callback is queried for `server_address` (default `"2>149.154.167.50:443"`. For test servers, return e.g. `"2>149.154.167.40:443"`). Inside, the client negotiates an auth key (`CreateAuthorizationKey`), starts the reception `Reactor` task and the keep-alive loop, and issues `InitConnection` (`initConnection` wrapping `help.getConfig`) unless `quickResume` applies.

### Returns
Task (asynchronous operation)
```

--------------------------------

### Create a new invite link and send it

Source: https://github.com/wiz0u/wtelegramclient/blob/master/EXAMPLES.md

Creates a new exported invite link for a chat and sends it to a user.

```APIDOC
## Create a new invite link and send it

### Description
Creates a new exported invite link for a chat and sends it to a user.

### Method
Client method calls

### Endpoint
client.Messages_ExportChatInvite(chat, title)
client.SendMessageAsync(user, message)

### Parameters
- **chat** (InputChat) - Required - The target chat.
- **title** (string) - Optional - Title for the invite link.
- **user** (InputUser) - Required - The user to send the invite link to.
- **message** (string) - Required - The message containing the invite link.

### Request Example
```csharp
var invite = (ChatInviteExported)await client.Messages_ExportChatInvite(chat, title: "MyLink");
await client.SendMessageAsync(user, "Join our group with this link: " + invite.link);
```

### Response
- **invite** (ChatInviteExported) - The newly created invite link.
```

--------------------------------

### List members from a channel/group using Channels_GetParticipants

Source: https://github.com/wiz0u/wtelegramclient/blob/master/EXAMPLES.md

Retrieves all chats, selects a channel by ID, and iterates through participants using pagination. The loop continues until all participants are fetched.

```csharp
var chats = await client.Messages_GetAllChats();
var channel = (Channel)chats.chats[1234567890]; // the channel we want
for (int offset = 0; ;)
{
    var participants = await client.Channels_GetParticipants(channel, null, offset);
    foreach (var (id, user) in participants.users)
        Console.WriteLine(user);
    offset += participants.participants.Length;
    if (offset >= participants.count || participants.participants.Length == 0) break;
}
```

--------------------------------

### Change logging settings

Source: https://github.com/wiz0u/wtelegramclient/blob/master/EXAMPLES.md

Shows how to redirect WTelegramClient logs to a file, VS Output, an ILogger, or disable them. The lvl argument corresponds to standard LogLevel values.

```csharp
// • Log to file in replacement of default Console screen logging, using this static variable:
static StreamWriter WTelegramLogs = new StreamWriter("WTelegram.log", true, Encoding.UTF8) { AutoFlush = true };
...
WTelegram.Helpers.Log = (lvl, str) => WTelegramLogs.WriteLine($"{DateTime.Now:yyyy-MM-dd HH:mm:ss} [{"TDIWE!"[lvl]}] {str}");

// • Log to VS Output debugging pane in addition (+=) to the default Console screen logging:
WTelegram.Helpers.Log += (lvl, str) => System.Diagnostics.Debug.WriteLine(str);

// • In ASP.NET service, you will typically send logs to an ILogger:
WTelegram.Helpers.Log = (lvl, str) => _logger.Log((LogLevel)lvl, str);

// • Disable logging (⛔️𝗗𝗢𝗡'𝗧 𝗗𝗢 𝗧𝗛𝗜𝗦 as you won't be able to diagnose any upcoming problem):
WTelegram.Helpers.Log = (lvl, str) => { };
```
Tokens:
Raw