WTelegramClient/README.md

153 lines
11 KiB
Markdown
Raw Normal View History

2021-08-13 17:32:07 +02:00
[![NuGet version](https://img.shields.io/nuget/v/WTelegramClient)](https://www.nuget.org/packages/WTelegramClient/)
[![Build Status](https://img.shields.io/azure-devops/build/wiz0u/WTelegramClient/7)](https://dev.azure.com/wiz0u/WTelegramClient/_build?definitionId=7)
2021-11-27 03:29:19 +01:00
[![API Layer](https://img.shields.io/badge/API_Layer-135-blueviolet)](https://corefork.telegram.org/methods)
2021-11-12 06:10:26 +01:00
[![dev nuget](https://img.shields.io/badge/dynamic/json?color=ffc040&label=dev%20nuget&query=%24.versions%5B0%5D&url=https%3A%2F%2Fpkgs.dev.azure.com%2Fwiz0u%2F81bd92b7-0bb9-4701-b426-09090b27e037%2F_packaging%2F46ce0497-7803-4bd4-8c6c-030583e7c371%2Fnuget%2Fv3%2Fflat2%2Fwtelegramclient%2Findex.json)](https://dev.azure.com/wiz0u/WTelegramClient/_packaging?_a=package&feed=WTelegramClient&package=WTelegramClient&protocolType=NuGet)
2021-08-13 17:32:07 +02:00
[![Support Chat](https://img.shields.io/badge/Chat_with_us-on_Telegram-0088cc)](https://t.me/WTelegramClient)
2021-10-31 03:55:03 +01:00
[![Donate](https://img.shields.io/badge/Help_this_project:-Donate-ff4444)](http://wizou.fr/donate.html)
2021-08-08 14:58:49 +02:00
## _a Telegram Client API library written 100% in C# and .NET Standard_
2021-08-07 06:25:59 +02:00
# How to use
2021-08-07 06:25:59 +02:00
2021-12-15 20:55:24 +01:00
>⚠️ This library relies on asynchronous C# programming (`async/await`) so make sure you are familiar with this advanced topic before proceeding.
2021-12-16 14:41:43 +01:00
>If you are a beginner in C#, starting a project based on this library might not be a great idea.
2021-08-07 06:25:59 +02:00
After installing WTelegramClient through Nuget, your first Console program will be as simple as:
```csharp
static async Task Main(string[] _)
2021-08-07 06:25:59 +02:00
{
using var client = new WTelegram.Client();
2021-08-26 17:46:45 +02:00
var user = await client.LoginUserIfNeeded();
2021-08-07 06:25:59 +02:00
Console.WriteLine($"We are logged-in as {user.username ?? user.first_name + " " + user.last_name} (id {user.id})");
}
```
When run, this will prompt you interactively for your App **api_id** and **api_hash** (that you obtain through Telegram's [API development tools](https://my.telegram.org/apps) page) and try to connect to Telegram servers.
Then it will attempt to sign-in as a user for which you must enter the **phone_number** and the **verification_code** that will be sent to this user (for example through SMS or another Telegram client app the user is connected to).
If the verification succeeds but the phone number is unknown to Telegram, the user might be prompted to sign-up (accepting the Terms of Service) and enter their **first_name** and **last_name**.
2021-10-01 05:46:51 +02:00
And that's it, you now have access to the [full range of Telegram services](https://corefork.telegram.org/methods), mainly through calls to `await client.Some_TL_Method(...)`
2021-08-07 06:25:59 +02:00
# Saved session
If you run this program again, you will notice that only **api_id** and **api_hash** are requested, the other prompts are gone and you are automatically logged-on and ready to go.
2021-08-07 06:25:59 +02:00
2021-08-07 06:59:36 +02:00
This is because WTelegramClient saves (typically in the encrypted file **bin\WTelegram.session**) its state and the authentication keys that were negociated with Telegram so that you needn't sign-in again every time.
2021-08-07 06:25:59 +02:00
That file path is configurable, and under various circumstances (changing user or server address) you may want to change it or simply delete the existing session file in order to restart the authentification process.
# Non-interactive configuration
Your next step will probably be to provide a configuration to the client so that the required elements (in bold above) are not prompted through the Console but answered by your program.
To do this, you need to write a method that will provide the answers, and pass it on the constructor:
2021-08-07 06:25:59 +02:00
```csharp
static string Config(string what)
{
2021-10-28 04:59:41 +02:00
switch (what)
{
case "api_id": return "YOUR_API_ID";
case "api_hash": return "YOUR_API_HASH";
case "phone_number": return "+12025550156";
2021-10-29 23:27:23 +02:00
case "verification_code": Console.Write("Code: "); return Console.ReadLine();
2021-10-28 04:59:41 +02:00
case "first_name": return "John"; // if sign-up is required
case "last_name": return "Doe"; // if sign-up is required
case "password": return "secret!"; // if user has enabled 2FA
default: return null; // let WTelegramClient decide the default config
}
2021-08-07 06:25:59 +02:00
}
...
using var client = new WTelegram.Client(Config);
```
2021-10-29 23:27:23 +02:00
There are other configuration items that are queried to your method but returning `null` let WTelegramClient choose a default adequate value.
Those shown above are the only ones that have no default values and should be provided by your method.
2021-10-29 23:27:23 +02:00
Returning `null` for verification_code or password will show a prompt for console apps, or an error otherwise.
Returning an empty string for verification_code requests resending the code through another method (SMS or Call).
Another simple approach is to pass `Environment.GetEnvironmentVariable` as the config callback and define the configuration items as environment variables.
2021-10-29 23:27:23 +02:00
Undefined variables get the default `null` behavior.
2021-08-07 06:25:59 +02:00
Finally, if you want to redirect the library logs to your logger instead of the Console, you can install a delegate in the `WTelegram.Helpers.Log` static property.
2021-08-07 06:59:36 +02:00
Its `int` argument is the log severity, compatible with the classic [LogLevel enum](https://docs.microsoft.com/en-us/dotnet/api/microsoft.extensions.logging.loglevel)
2021-08-07 06:25:59 +02:00
# Example of API call
2021-11-15 17:17:11 +01:00
> The Telegram API makes extensive usage of base and derived classes, so be ready to use the various syntaxes C# offer to check/cast base classes into the more useful derived classes (`is`, `as`, `case DerivedType` )
2021-08-07 06:25:59 +02:00
2021-11-15 17:17:11 +01:00
All the Telegram API classes/methods are fully documented through Intellisense: Place your mouse over a class/method name, or start typing the call arguments to see a tooltip display their description, the list of derived classes and a web link to the official API page.
2021-08-07 06:25:59 +02:00
2021-10-01 05:46:51 +02:00
The Telegram [API object classes](https://corefork.telegram.org/schema) are defined in the `TL` namespace, and the [API functions](https://corefork.telegram.org/methods) are available as async methods of `Client`.
2021-08-07 06:59:36 +02:00
2021-10-01 05:46:51 +02:00
Below is an example of calling the [messages.getAllChats](https://corefork.telegram.org/method/messages.getAllChats) API function and enumerating the various groups/channels the user is in, and then using `client.SendMessageAsync` helper function to easily send a message:
2021-08-07 06:25:59 +02:00
```csharp
2021-08-07 06:59:36 +02:00
using TL;
...
var chats = await client.Messages_GetAllChats(null);
2021-08-07 06:59:36 +02:00
Console.WriteLine("This user has joined the following:");
foreach (var (id, chat) in chats.chats)
switch (chat) // example of downcasting to their real classes:
2021-08-07 06:25:59 +02:00
{
2021-11-12 06:10:26 +01:00
case Chat smallgroup when smallgroup.IsActive:
Console.WriteLine($"{id}: Small group: {smallgroup.title} with {smallgroup.participants_count} members");
2021-08-07 06:25:59 +02:00
break;
2021-11-12 06:10:26 +01:00
case Channel group when group.IsGroup:
Console.WriteLine($"{id}: Group {group.username}: {group.title}");
2021-08-07 06:25:59 +02:00
break;
2021-11-12 06:10:26 +01:00
case Channel channel:
Console.WriteLine($"{id}: Channel {channel.username}: {channel.title}");
break;
2021-08-07 06:25:59 +02:00
}
Console.Write("Type a chat ID to send a message: ");
long chatId = long.Parse(Console.ReadLine());
var target = chats.chats[chatId];
Console.WriteLine($"Sending a message in chat {chatId}: {target.Title}");
await client.SendMessageAsync(target, "Hello, World");
2021-08-07 06:25:59 +02:00
```
➡️ You can find more useful code snippets in [EXAMPLES.md](https://github.com/wiz0u/WTelegramClient/blob/master/EXAMPLES.md) and in the [Examples subdirectory](https://github.com/wiz0u/WTelegramClient/tree/master/Examples).
2021-11-15 17:17:11 +01:00
2021-12-07 02:32:19 +01:00
<a name="terminology"></a>
2021-10-20 00:24:50 +02:00
# Terminology in Telegram Client API
2021-10-20 00:24:50 +02:00
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)
2021-12-24 07:21:02 +01:00
- `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`!**
- chats : In plural or general meaning, it means either `Chat` or `Channel`
- `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...)*
- DC (DataCenter) : There are a few datacenters depending on where in the world the user (or an uploaded media file) is from.
2021-12-08 15:05:33 +01:00
- Access Hash : Telegram requires you to provide a specific `access_hash` for users, channels, and other resources before interacting with them. See [FAQ #4](https://github.com/wiz0u/WTelegramClient/blob/master/FAQ.md#access-hash) to learn more about it.
2021-08-07 06:59:36 +02:00
# Other things to know
2021-10-13 00:27:40 +02:00
The Client class also offers an `Update` event that is triggered when Telegram servers sends unsollicited Updates or notifications/information/status/service messages, independently of your API requests. See [Examples/Program_ListenUpdates.cs](https://github.com/wiz0u/WTelegramClient/blob/master/Examples/Program_ListenUpdates.cs)
2021-10-01 05:46:51 +02:00
An invalid API request can result in a `RpcException` being raised, reflecting the [error code and status text](https://revgram.github.io/errors.html) of the problem.
2021-08-07 06:59:36 +02:00
The other configuration items that you can override include: **session_pathname, server_address, device_model, system_version, app_version, system_lang_code, lang_pack, lang_code, user_id**
2021-08-07 06:59:36 +02:00
2021-10-13 00:27:40 +02:00
Optional API parameters have a default value of `null` when unset. Passing `null` for a required string/array is the same as *empty* (0-length). Required API parameters/fields can sometimes be set to 0 or `null` when unused (check API documentation or experiment).
2021-08-14 08:55:30 +02:00
2021-10-13 00:27:40 +02:00
I've added several useful converters, implicit cast or helper properties to various API object so that they are more easy to manipulate.
2021-08-14 08:55:30 +02:00
2021-10-01 05:46:51 +02:00
Beyond the TL async methods, the Client class offers a few other methods to simplify the sending/receiving of files, medias or messages.
2021-08-14 08:55:30 +02:00
This library works best with **.NET 5.0+** and is also available for **.NET Standard 2.0** (.NET Framework 4.6.1+ & .NET Core 2.0+)
2021-08-08 14:58:49 +02:00
2021-09-30 20:36:52 +02:00
# Library uses and limitations
This library can be used for any Telegram scenarios including:
- Sequential or parallel automated steps based on API requests/responses
- Real-time monitoring of incoming Updates/Messages
- Download/upload of files/media
- or even a full-featured interactive client
2021-11-15 17:17:11 +01:00
It has been tested in a Console app, WinForms app, ASP.NET webservice.
2021-09-30 20:36:52 +02:00
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.
2021-11-15 17:17:11 +01:00
Developers feedbacks are 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.
2021-10-28 04:59:41 +02:00
If you like this library, please [consider a donation](http://wizou.fr/donate.html).❤ This will help the project keep going.