wiz0u/WTelegramClient
1
0
Fork 0
mirror of https://github.com/wiz0u/WTelegramClient.git synced 2025-12-06 06:52:01 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity

improved documentation for newbies

Browse source
This commit is contained in:
Wizou 2021-12-26 18:28:10 +01:00
parent 51a89bc6a1
commit 791dc88ea0
4 changed files with 64 additions and 19 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
.github/dev.yml vendored
View file

@ -2,7 +2,7 @@ pr: none
trigger: trigger:
- master - master
name: 1.8.2-dev.$(Rev:r) name: 1.8.3-dev.$(Rev:r)
pool: pool:
vmImage: ubuntu-latest vmImage: ubuntu-latest

37
EXAMPLES.md
View file

@ -125,8 +125,11 @@ Console.Write("Choose a chat ID to send a message to: ");
long chatId = long.Parse(Console.ReadLine()); long chatId = long.Parse(Console.ReadLine());
await client.SendMessageAsync(chats.chats[chatId], "Hello, World"); await client.SendMessageAsync(chats.chats[chatId], "Hello, World");
``` ```
*Note: the list returned by Messages_GetAllChats contains the `access_hash` for those chats.* Notes:
See a longer version of this example in [Examples/Program_GetAllChats.cs](Examples/Program_GetAllChats.cs) - The list returned by Messages_GetAllChats contains the `access_hash` for those chats. Read [FAQ #4](FAQ.MD#access-hash) about this.
- If a small private chat group has been migrated to a supergroup, you may find both the old `Chat` and a `Channel` with different IDs in the `chats.chats` result,
but the old `Chat` will be marked with flag [deactivated] and should not be used anymore. See [Terminology in ReadMe](README.md#terminology).
- You can find a longer version of this method call in [Examples/Program_GetAllChats.cs](Examples/Program_GetAllChats.cs)
<a name="schedule-msg"></a> <a name="schedule-msg"></a>
### Schedule a message to be sent to a chat ### Schedule a message to be sent to a chat
@ -142,18 +145,18 @@ await client.SendMessageAsync(peer, "This will be posted in 3 minutes", schedule
<a name="upload"></a> <a name="upload"></a>
### Upload a media file and post it with caption to a chat ### Upload a media file and post it with caption to a chat
```csharp ```csharp
const int TargetChatId = 1234567890; // the chat we want const int ChatId = 1234567890; // the chat we want
const string Filepath = @"C:\...\photo.jpg"; const string Filepath = @"C:\...\photo.jpg";
using var client = new WTelegram.Client(Environment.GetEnvironmentVariable); using var client = new WTelegram.Client(Environment.GetEnvironmentVariable);
await client.LoginUserIfNeeded(); await client.LoginUserIfNeeded();
var chats = await client.Messages_GetAllChats(null); var chats = await client.Messages_GetAllChats(null);
InputPeer peer = chats.chats[TargetChatId]; InputPeer peer = chats.chats[ChatId];
var inputFile = await client.UploadFileAsync(Filepath); var inputFile = await client.UploadFileAsync(Filepath);
await client.SendMediaAsync(peer, "Here is the photo", inputFile); await client.SendMediaAsync(peer, "Here is the photo", inputFile);
``` ```
<a name="list-dialog"></a> <a name="list-dialogs"></a>
### List all dialogs (chats/groups/channels/user chat) the user is in ### List all dialogs (chats/groups/channels/user chat) the user is in
```csharp ```csharp
using var client = new WTelegram.Client(Environment.GetEnvironmentVariable); using var client = new WTelegram.Client(Environment.GetEnvironmentVariable);
@ -220,20 +223,20 @@ var participants = await client.Channels_GetAllParticipants(channel);
using var client = new WTelegram.Client(Environment.GetEnvironmentVariable); using var client = new WTelegram.Client(Environment.GetEnvironmentVariable);
await client.LoginUserIfNeeded(); await client.LoginUserIfNeeded();
var chats = await client.Messages_GetAllChats(null); var chats = await client.Messages_GetAllChats(null);
const long chatId = 1234567890; // the target chat const long ChatId = 1234567890; // the target chat
var chat = chats.chats[chatId]; var chat = chats.chats[ChatId];
``` ```
After the above code, once you [have obtained](https://github.com/wiz0u/WTelegramClient/blob/master/FAQ.md#access-hash) an `InputUser` or `User`, you can: After the above code, once you [have obtained](https://github.com/wiz0u/WTelegramClient/blob/master/FAQ.md#access-hash) an `InputUser` or `User`, you can:
```csharp ```csharp
// • Directly add the user to a simple Chat: // • Directly add the user to a simple Chat:
await client.Messages_AddChatUser(1234567890, user, int.MaxValue); await client.Messages_AddChatUser(ChatId, user, int.MaxValue);
// • Directly add the user to a Channel/group: // • Directly add the user to a Channel/group:
await client.Channels_InviteToChannel((Channel)chat, new[] { user }); await client.Channels_InviteToChannel((Channel)chat, new[] { user });
// You may get exception USER_PRIVACY_RESTRICTED if the user has denied the right to be added to a chat // You may get exception USER_PRIVACY_RESTRICTED if the user has denied the right to be added to a chat
// or exception USER_NOT_MUTUAL_CONTACT if the user left the chat previously and you want to add him again // or exception USER_NOT_MUTUAL_CONTACT if the user left the chat previously and you want to add him again
// • Obtain the main invite link for a simple Chat: // • Obtain the main invite link for a simple Chat:
var mcf = await client.Messages_GetFullChat(1234567890); var mcf = await client.Messages_GetFullChat(ChatId);
// • Obtain the main invite link for a Channel/group: // • Obtain the main invite link for a Channel/group:
var mcf = await client.Channels_GetFullChannel((Channel)chat); var mcf = await client.Channels_GetFullChannel((Channel)chat);
// extract the invite link and send it to the user: // extract the invite link and send it to the user:
@ -248,7 +251,7 @@ await client.Messages_EditExportedChatInvite(chat, invite.link, revoked: true);
await client.Messages_DeleteExportedChatInvite(chat, invite.link); await client.Messages_DeleteExportedChatInvite(chat, invite.link);
// • Remove the user from a simple Chat: // • Remove the user from a simple Chat:
await client.Messages_DeleteChatUser(1234567890, user); await client.Messages_DeleteChatUser(ChatId, user);
// • Remove the user from a Channel/group: // • Remove the user from a Channel/group:
await client.Channels_EditBanned((Channel)chat, user, new ChatBannedRights { flags = ChatBannedRights.Flags.view_messages }); await client.Channels_EditBanned((Channel)chat, user, new ChatBannedRights { flags = ChatBannedRights.Flags.view_messages });
``` ```
@ -361,16 +364,24 @@ client.TcpHandler = async (address, port) =>
<a name="logging"></a> <a name="logging"></a>
### Change logging settings ### Change logging settings
Log to VS Output debugging pane in addition to default Console screen logging: By default, WTelegramClient logs are displayed on the Console screen.
If you are not in a Console app or don't want the logs on screen, you can redirect them as you prefer:
* Log to VS Output debugging pane in addition to default Console screen logging:
```csharp ```csharp
WTelegram.Helpers.Log += (lvl, str) => System.Diagnostics.Debug.WriteLine(str); WTelegram.Helpers.Log += (lvl, str) => System.Diagnostics.Debug.WriteLine(str);
``` ```
Log to file in replacement of default Console screen logging: * Log to file in replacement of default Console screen logging:
```csharp ```csharp
WTelegram.Helpers.Log = (lvl, str) => File.AppendAllText("WTelegram.log", str + Environment.NewLine); WTelegram.Helpers.Log = (lvl, str) => File.AppendAllText("WTelegram.log", str + Environment.NewLine);
``` ```
More efficient example with a static variable and detailed logging to file: * More efficient example with a static variable and detailed logging to file:
```csharp ```csharp
static StreamWriter WTelegramLogs = new StreamWriter("WTelegram.log", true, Encoding.UTF8) { AutoFlush = true }; 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}"); WTelegram.Helpers.Log = (lvl, str) => WTelegramLogs.WriteLine($"{DateTime.Now:yyyy-MM-dd HH:mm:ss} [{"TDIWE!"[lvl]}] {str}");
```
* In an ASP.NET service, you will typically send logs to a `ILogger`:
```csharp
WTelegram.Helpers.Log = (lvl, str) => _logger.Log((LogLevel)lvl, str);
```

36
FAQ.md
View file

@ -45,7 +45,7 @@ An `access_hash` is required by Telegram when dealing with a channel, user, phot
This serves as a proof that you are entitled to access it (otherwise, anybody with the ID could access it) This serves as a proof that you are entitled to access it (otherwise, anybody with the ID could access it)
> A small private `Chat` don't need an access_hash and can be queried using their `chat_id` only. > A small private `Chat` don't need an access_hash and can be queried using their `chat_id` only.
However most common chat groups are not `Chat` but a `Channel` supergroup (without the `broadcast` flag). See Terminology in [ReadMe](README.md#terminology). However most common chat groups are not `Chat` but a `Channel` supergroup (without the `broadcast` flag). See [Terminology in ReadMe](README.md#terminology).
Some TL methods only applies to private `Chat`, some only applies to `Channel` and some to both. Some TL methods only applies to private `Chat`, some only applies to `Channel` and some to both.
The `access_hash` must usually be provided within the `Input...` structure you pass in argument to an API method (`InputPeer`, `InputChannel`, `InputUser`, etc...). The `access_hash` must usually be provided within the `Input...` structure you pass in argument to an API method (`InputPeer`, `InputChannel`, `InputUser`, etc...).
@ -73,6 +73,8 @@ After that, you should be able to see/install the pre-release versions in your N
This happens when you connect to Telegram Test servers instead of Production servers. This happens when you connect to Telegram Test servers instead of Production servers.
On these separate test servers, all created accounts and chats are periodically deleted, so you shouldn't use them under normal circumstances. On these separate test servers, all created accounts and chats are periodically deleted, so you shouldn't use them under normal circumstances.
You can verify this is your case by looking at [WTelegram logs](EXAMPLES.MD#logging) on the line `Connected to (Test) DC x...`
This wrong-server problem typically happens when you use WTelegramClient Github source project in your application in DEBUG builds. This wrong-server problem typically happens when you use WTelegramClient Github source project in your application in DEBUG builds.
It is **not recommended** to use WTelegramClient in source code form. It is **not recommended** to use WTelegramClient in source code form.
Instead, you should use the Nuget manager to **import the WTelegramClient Nuget package** into your application. Instead, you should use the Nuget manager to **import the WTelegramClient Nuget package** into your application.
@ -123,6 +125,38 @@ If you think your phone number was banned from Telegram for a wrong reason, you
In any case, WTelegramClient is not responsible for the bad usage of the library and we are not affiliated to Telegram teams, so there is nothing we can do. In any case, WTelegramClient is not responsible for the bad usage of the library and we are not affiliated to Telegram teams, so there is nothing we can do.
<a name="chat-id"></a>
#### 9. Why the error `CHAT_ID_INVALID`?
Most chat groups you see are likely of type `Channel`, not `Chat`.
This difference is important to understand. Please [read about the Terminology in ReadMe](README.md#terminology).
You typically get the error `CHAT_ID_INVALID` when you try to call API methods designed specifically for a `Chat`, with the ID of a `Channel`.
All API methods taking a `long api_id` as a direct method parameter are for Chats and cannot be used with Channels.
There is probably another method achieving the same result but specifically designed for Channels, and it will have a similar name, but beginning with `Channels_` ...
However, note that those Channel-compatible methods will require an `InputChannel` or `InputPeerChannel` object as argument instead of a simple channel ID.
That object must be created with both fields `channel_id` and `access_hash` correctly filled. You can read more about this in [FAQ #4](#access-hash).
<a name="chats-chats"></a>
#### 10. `chats.chats[id]` throws KeyNotFoundException. My chats list is empty or does not contain the chat id.
There can be several reasons why `chats.chats[id]` raise an error:
- The user account you're currently logged-in as has not joined this particular chat.
API method [Messages_GetAllChats](https://corefork.telegram.org/method/messages.getAllChats) will only return those chat groups/channels the user is in, not all Telegram chat groups.
- You're trying to use a Telegram.Bot (or TDLib) numerical ID, like -1001234567890
Telegram Client API don't use these kind of IDs for chats. Remove the -100 prefix and try again with the rest (1234567890).
- You're trying to use a user ID instead of a chat ID.
Private messages with a user are not called "chats". See [Terminology in ReadMe](README.md#terminology).
To obtain the list of users (as well as chats and channels) the logged-in user is currenly engaged in a discussion with, you should [use the API method Messages_GetDialogs](EXAMPLES.md#list-dialogs)
- the `chats.chats` dictionary is empty.
This is the case if you are logged-in as a brand new user account (that hasn't join any chat groups/channels)
or if you are connected to a Test DC (a Telegram datacenter server for tests) instead of Production DC
([read FAQ #6](#wrong-server) for more)
To help determine if `chats.chats` is empty or does not contain a certain chat, you should [dump the chat list to the screen](EXAMPLES.md#list-chats)
or simply use a debugger: Place a breakpoint after the Messages_GetAllChats call, run the program up to there, and use a Watch pane to display the content of the chats.chats dictionary.
<a name="troubleshoot"></a> <a name="troubleshoot"></a>
## Troubleshooting guide ## Troubleshooting guide

8
README.md
View file

@ -111,7 +111,7 @@ await client.SendMessageAsync(target, "Hello, World");
In the API, Telegram uses some terms/classnames that can be confusing as they differ from the terms shown to end-users: In the API, Telegram uses some terms/classnames that can be confusing as they differ from the terms shown to end-users:
- `Channel` : A (large or public) chat group *(sometimes called supergroup)* or a broadcast channel (the `broadcast` flag differenciate those) - `Channel` : A (large or public) chat group *(sometimes called supergroup)* or a broadcast channel (the `broadcast` flag differenciate those)
- `Chat` : A private simple chat group with less than 200 members (it may be migrated to a supergroup `Channel` with a new ID when it gets bigger or public, in which case the old `Chat` will still exist but be `deactivated`) - `Chat` : A private simple chat group with less than 200 members (it may be migrated to a supergroup `Channel` with a new ID when it gets bigger or public, in which case the old `Chat` will still exist but be `deactivated`)
**⚠ Most chat groups you see are really of type `Channel` not `Chat`!** **⚠️ Most chat groups you see are really of type `Channel`, not `Chat`!**
- chats : In plural or general meaning, it means either `Chat` or `Channel` - chats : In plural or general meaning, it means either `Chat` or `Channel`
- `Peer` : Either a `Chat`, `Channel` or a private chat with a `User` - `Peer` : Either a `Chat`, `Channel` or a private chat with a `User`
- Dialog : The current status of a chat with a `Peer` *(draft, last message, unread count, pinned...)* - Dialog : The current status of a chat with a `Peer` *(draft, last message, unread count, pinned...)*
@ -137,16 +137,16 @@ This library works best with **.NET 5.0+** and is also available for **.NET Stan
# Library uses and limitations # Library uses and limitations
This library can be used for any Telegram scenarios including: This library can be used for any Telegram scenarios including:
- Sequential or parallel automated steps based on API requests/responses - Sequential or parallel automated steps based on API requests/responses
- Real-time monitoring of incoming Updates/Messages - Real-time [monitoring](https://github.com/wiz0u/WTelegramClient/blob/master/EXAMPLES.md#updates) of incoming Updates/Messages
- Download/upload of files/media - Download/upload of files/media
- or even a full-featured interactive client - or even a full-featured interactive client
It has been tested in a Console app, WinForms app, ASP.NET webservice. It has been tested in a Console app, [in a WinForms app](https://github.com/wiz0u/WTelegramClient/blob/master/FAQ.md#gui), [in ASP.NET webservice](https://github.com/wiz0u/WTelegramClient/blob/master/EXAMPLES.md#logging).
Secret chats (end-to-end encryption, PFS) and connection to CDN DCs have not been tested yet. Secret chats (end-to-end encryption, PFS) and connection to CDN DCs have not been tested yet.
Please don't use this library for Spam or Scam. Respect Telegram [Terms of Service](https://telegram.org/tos) as well as the [API Terms of Service](https://core.telegram.org/api/terms) or you might get banned from Telegram servers. Please don't use this library for Spam or Scam. Respect Telegram [Terms of Service](https://telegram.org/tos) as well as the [API Terms of Service](https://core.telegram.org/api/terms) or you might get banned from Telegram servers.
Developers feedbacks are welcome in the Telegram support group [@WTelegramClient](https://t.me/WTelegramClient) Developers feedback is welcome in the Telegram support group [@WTelegramClient](https://t.me/WTelegramClient)
You can also check our [📖 Frequently Asked Questions](https://github.com/wiz0u/WTelegramClient/blob/master/FAQ.md) for more help and troubleshooting guide. You can also check our [📖 Frequently Asked Questions](https://github.com/wiz0u/WTelegramClient/blob/master/FAQ.md) for more help and troubleshooting guide.
If you like this library, please [consider a donation](http://wizou.fr/donate.html).❤ This will help the project keep going. If you like this library, please [consider a donation](http://wizou.fr/donate.html).❤ This will help the project keep going.