update documentation before release

EXAMPLES.md

@@ -430,6 +430,12 @@ You can find an example for such custom session store in [Examples/Program_Herok
 <a name="reaction"></a><a name="pinned"></a><a name="custom_emoji"></a>
 ### Fun with custom emojies and reactions on pinned messages
 ```csharp
+// • Sending a message with custom emojies in Markdown to ourself:
+var text = "Vicksy says Hi! [👋](emoji?id=5190875290439525089)";
+var entities = client.MarkdownToEntities(ref text, premium: true);
+await client.SendMessageAsync(InputPeer.Self, text, entities: entities);
+// also available in HTML: "<tg-emoji id=\"5190875290439525089\">👋</tg-emoji>"
+
 // • Fetch all available standard emoji reactions
 var all_emoji = await client.Messages_GetAvailableReactions();
 
@@ -475,3 +481,12 @@ await client.Messages_ForwardMessages(from_chat, new[] { msg.ID }, new[] { WTele
 // • Alternative solution to copy the message (the full message is needed)
 await client.SendMessageAsync(to_chat, msg.message, msg.media?.ToInputMedia(), entities: msg.entities);
 ```
+
+<a name="e2e"></a><a name="secrets"></a>
+### Send/receive end-to-end encrypted messages in Secret Chats
+
+This can be done easily using the helper class `WTelegram.SecretChats` offering methods to manage/encrypt/decrypt secret chats & encrypted messages.
+
+You can view a full working example at [Examples/Program_SecretChats.cs](Examples/Program_SecretChats.cs).
+
+Secret Chats have been tested successfully with Telegram Android & iOS official clients.

FAQ.md

@@ -42,6 +42,9 @@ This might require adding a reference *(and `using`)* to the Microsoft.VisualBas
 
 A more complex solution requires the use of a `ManualResetEventSlim` that you will wait for in Config callback,
 and when the user has provided the verification_code through your app, you "set" the event to release your Config callback so it can return the code.  
+
+Another solution is to use the [alternative login method](README.md#alternative-simplified-configuration-login),
+calling `client.Login(...)` as the user provides the requested configuration elements.
 You can download such full example apps [for WinForms](https://github.com/wiz0u/WTelegramClient/raw/master/Examples/WinForms_app.zip) and [for ASP.NET](https://github.com/wiz0u/WTelegramClient/raw/master/Examples/ASPnet_webapp.zip)
 
 <a name="access-hash"></a>
@@ -237,6 +240,22 @@ Pure WebApp hosts might not be adequate as they will recycle (stop) your app if
 There are many cheap VPS Hosting offers available, for example Heroku:  
 See [Examples/Program_Heroku.cs](Examples/Program_Heroku.cs) for such an implementation and the steps to host/deploy it.
 
+<a name="secrets"></a>
+#### 14. Secret Chats implementation details
+
+The following choices were made while implementing Secret Chats in WTelegramClient:
+- It may not support remote antique Telegram clients *(prior to 2018, still using insecure MTProto 1.0)*
+- It doesn't store outgoing messages *(so if remote client was offline for a week and ask us to resend old messages, we will send void data)*
+- It doesn't store incoming messages on disk *(it's up to you if you want to store them)*
+- If you pass `DecryptMessage` parameter `fillGaps: true` *(the default)*, incoming messages are ensured to be delivered to you in correct order.  
+If for some (weird) reason, we received them in incorrect order, messages are kept in memory until the requested missing messages are obtained.  
+If those missing messages are never obtained during the session, incoming messages might get stuck and lost.
+- SecretChats file data is only valid for the current user, so make sure to select the right file *(or a new file name)* if you change logged-in user.
+- If you want to accept Secret Chats request only from specific user, you must check it in OnUpdate before:  
+`await Secrets.HandleUpdate(ue, ue.chat is EncryptedChatRequested ecr && ecr.admin_id == EXPECTED_USER_ID);`
+- As recommended, new encryption keys are negotiated every 100 sent/received messages or after one week.  
+If remote client doesn't complete this negotiation before reaching 200 messages, the Secret Chat is aborted.
+
 <a name="troubleshoot"></a>
 ## Troubleshooting guide
 

README.md

@@ -87,6 +87,31 @@ Another simple approach is to pass `Environment.GetEnvironmentVariable` as the c
 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.
 Its `int` argument is the log severity, compatible with the [LogLevel enum](https://docs.microsoft.com/en-us/dotnet/api/microsoft.extensions.logging.loglevel)
 
+# Alternative simplified configuration & login
+Since version 3.0.0, a new approach to login/configuration has been added. Some people might find it easier to deal with:
+
+```csharp
+WTelegram.Client client = new WTelegram.Client(YOUR_API_ID, "YOUR_API_HASH");
+await DoLogin("+12025550156");
+
+async Task DoLogin(string loginInfo) // add this method to your code
+{
+    while (client.User == null)
+	    switch (await client.Login(loginInfo)) // returns which configuration info is requested for the login to continue
+	    {
+		    case "verification_code": Console.Write("Code: "); loginInfo = Console.ReadLine(); break;
+		    case "name": loginInfo = "John Doe"; break;    // if sign-up is required (first_name + 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})");
+}
+```
+
+With this method, you can choose in some cases to interrupt the login loop via a `return` instead of `break`, and resume it later
+by calling `DoLogin(requestedCode)` again once you've obtained the requested code/password/etc...
+See [WinForms example](https://github.com/wiz0u/WTelegramClient/raw/master/Examples/WinForms_app.zip) and [ASP.NET example](https://github.com/wiz0u/WTelegramClient/raw/master/Examples/ASPnet_webapp.zip)
+
 # Example of API call
 
 >ℹ️ The Telegram API makes extensive usage of base and derived classes, so be ready to use the various C# syntaxes
@@ -168,6 +193,7 @@ This library can be used for any Telegram scenarios including:
 - Sequential or parallel automated steps based on API requests/responses
 - Real-time [monitoring](https://github.com/wiz0u/WTelegramClient/blob/master/EXAMPLES.md#updates) of incoming Updates/Messages
 - Download/upload of files/media
+- Exchange end-to-end encrypted messages in [Secret Chats](https://github.com/wiz0u/WTelegramClient/blob/master/EXAMPLES.md#e2e)
 - Building a full-featured interactive client
 
 It has been tested in a Console app, [in Windows Forms](https://github.com/wiz0u/WTelegramClient/raw/master/Examples/WinForms_app.zip),