docs: Updated README and docs

naseif · Mar 16, 2022 · 4d0ab40 · 4d0ab40
1 parent ace5bad
commit 4d0ab40
Show file tree

Hide file tree

Showing 108 changed files with 867 additions and 711 deletions.
diff --git a/README.md b/README.md
@@ -11,6 +11,18 @@ Fast and Flexible Telegram Bot API Framework for Node.js written in TypeScript.
 - Speedy and efficient
 - Beginner friendly
 
+<!-- TOC -->
+
+- [Installation](#installation)
+- [Loading and configuring the module](#importing)
+- [Getting started](#getting-started)
+- [Events](#telegram-events)
+- [Examples](#examples)
+  - [Sending Files](#sending-files)
+  - [Inline Keyboards](#inline-keyboards)
+
+<!-- /TOC -->
+
 ## Installation
 
 ```
@@ -60,6 +72,97 @@ telegram.on("message", async (message) => {
 telegram.startPolling();
 ```
 
+## Telegram Events
+
+Events you can listen to usign `teletron-ts`:
+
+- message
+- edited_message
+- edited_channel_post
+- channel_post
+- inline_query
+- chosen_inline_result
+- callback_query
+- shipping_query
+- poll
+- poll_answer
+- chat_join_request
+
+Please note that both `inline_query` and `chosen_inline_result` only work if you enabled this option by sending `/setinline` to `@BotFather`
+
+For more information regarding inline queries visit the telegram docs [here](https://core.telegram.org/bots/inline)
+
+## Examples
+
+### Sending Files
+
+There are 3 ways to send files. You can use the file id of a file that already exist on telegram servers, provide an HTTP URL to the file which then will be downloaded by telegram servers or upload a local file. Lets assume we want to send a photo via the bot:
+
+```ts
+import { TelegramAPI } from "teletron-ts";
+
+const telegram = new TelegramAPI("token"); // bot token
+
+telegram.on("message", async (message) => {
+  // First Method: Using an already existing file_id of a file that has been previously uploaded on telegram
+  await telegram.sendPhoto(
+    message.chat.id,
+    "AgADBQADqacxG2gbbxCWBkgvcmeAgxVPyjIABBlug37DKyhDEU0AAgI"
+  );
+
+  // Second Method: Using an HTTP photo url
+  await telegram.sendPhoto(
+    message.chat.id,
+    "https://reshape.sport1.de/c/t/85599615-c80d-47f0-9179-4375d6e4fa93/976x549"
+  );
+
+  // Thrid Method: Using a local file
+  await telegram.sendPhoto(message.chat.id, { file: "./anime.jpg" });
+});
+
+// fetch updates from the api
+telegram.startPolling();
+```
+
+### Inline Keyboards
+
+Inline keyboards are buttons that will be sent along with the message. These become especially useful if you want to wait for user input to perform certain action!
+
+```ts
+import { TelegramAPI } from "teletron-ts";
+import { IInlineKeyboardMarkup } from "teletron-ts";
+
+const telegram = new TelegramAPI("token");
+
+telegram.on("message", async (m) => {
+  const inlineKeyboards: IInlineKeyboardMarkup = {
+    inline_keyboard: [
+      [
+        { text: "Very Good!", callback_data: "vgood" },
+        { text: "Fine", callback_data: "fine" },
+      ],
+      [{ text: "Amazing", callback_data: "amazing" }],
+    ],
+  };
+
+  await telegram.sendMessage(
+    m.chat.id,
+    "Hey there, how are you feeling today?",
+    {
+      reply_markup: JSON.stringify(inlineKeyboards),
+    }
+  );
+});
+
+telegram.on("callback_query", async (query) => {
+  if (query.data && query.data === "vgood")
+    return await telegram.sendMessage(
+      query.message.chat.id,
+      "I am feeling very good today too!"
+    );
+});
+```
+
 ## Contributions
 
 Software contributions are welcome. If you are not a dev, testing and reproting bugs can also be very helpful!

diff --git a/docs/assets/highlight.css b/docs/assets/highlight.css
@@ -15,10 +15,10 @@
     --dark-hl-6: #4FC1FF;
     --light-hl-7: #795E26;
     --dark-hl-7: #DCDCAA;
-    --light-hl-8: #098658;
-    --dark-hl-8: #B5CEA8;
-    --light-hl-9: #267F99;
-    --dark-hl-9: #4EC9B0;
+    --light-hl-8: #267F99;
+    --dark-hl-8: #4EC9B0;
+    --light-hl-9: #098658;
+    --dark-hl-9: #B5CEA8;
     --light-hl-10: #000000;
     --dark-hl-10: #C8C8C8;
     --light-code-background: #F5F5F5;

diff --git a/docs/classes/TelegramAPI.html b/docs/classes/TelegramAPI.html
diff --git a/docs/index.html b/docs/index.html
@@ -15,6 +15,21 @@ <h2>Features</h2>
 <li>Speedy and efficient</li>
 <li>Beginner friendly</li>
 </ul>
+<!-- TOC -->
+
+<ul>
+<li><a href="#installation">Installation</a></li>
+<li><a href="#importing">Loading and configuring the module</a></li>
+<li><a href="#getting-started">Getting started</a></li>
+<li><a href="#telegram-events">Events</a></li>
+<li><a href="#examples">Examples</a><ul>
+<li><a href="#sending-files">Sending Files</a></li>
+<li><a href="#inline-keyboards">Inline Keyboards</a></li>
+</ul>
+</li>
+</ul>
+<!-- /TOC -->
+
 
 <a href="#installation" id="installation" style="color: inherit; text-decoration: none;">
   <h2>Installation</h2>
@@ -44,6 +59,44 @@ <h2>Getting started</h2>
 <pre><code class="language-ts"><span class="hl-2">import</span><span class="hl-1"> { </span><span class="hl-0">TelegramAPI</span><span class="hl-1"> } </span><span class="hl-2">from</span><span class="hl-1"> </span><span class="hl-4">&quot;teletron-ts&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-6">telegram</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-7">TelegramAPI</span><span class="hl-1">(</span><span class="hl-4">&quot;token&quot;</span><span class="hl-1">); </span><span class="hl-5">// bot token api</span><br/><br/><span class="hl-5">// listen for the message event</span><br/><br/><span class="hl-0">telegram</span><span class="hl-1">.</span><span class="hl-7">onMessage</span><span class="hl-1">(</span><span class="hl-3">async</span><span class="hl-1"> (</span><span class="hl-0">message</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-2">if</span><span class="hl-1"> (</span><span class="hl-0">message</span><span class="hl-1">.</span><span class="hl-0">text</span><span class="hl-1"> === </span><span class="hl-4">&quot;Hi bot!&quot;</span><span class="hl-1">)</span><br/><span class="hl-1">    </span><span class="hl-2">await</span><span class="hl-1"> </span><span class="hl-0">telegram</span><span class="hl-1">.</span><span class="hl-7">sendMessage</span><span class="hl-1">(</span><span class="hl-0">message</span><span class="hl-1">.</span><span class="hl-0">chat</span><span class="hl-1">.</span><span class="hl-0">id</span><span class="hl-1">, </span><span class="hl-4">&quot;Hi there, human!&quot;</span><span class="hl-1">); </span><span class="hl-5">// sendMessage will return an instance of IMessage</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-5">// OR</span><br/><br/><span class="hl-0">telegram</span><span class="hl-1">.</span><span class="hl-7">on</span><span class="hl-1">(</span><span class="hl-4">&quot;message&quot;</span><span class="hl-1">, </span><span class="hl-3">async</span><span class="hl-1"> (</span><span class="hl-0">message</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-2">if</span><span class="hl-1"> (</span><span class="hl-0">message</span><span class="hl-1">.</span><span class="hl-0">text</span><span class="hl-1"> === </span><span class="hl-4">&quot;Hi bot!&quot;</span><span class="hl-1">)</span><br/><span class="hl-1">    </span><span class="hl-2">await</span><span class="hl-1"> </span><span class="hl-0">telegram</span><span class="hl-1">.</span><span class="hl-7">sendMessage</span><span class="hl-1">(</span><span class="hl-0">message</span><span class="hl-1">.</span><span class="hl-0">chat</span><span class="hl-1">.</span><span class="hl-0">id</span><span class="hl-1">, </span><span class="hl-4">&quot;Hi there, human!&quot;</span><span class="hl-1">); </span><span class="hl-5">// sendMessage will return an instance of IMessage</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-5">// fetch new updates from the api</span><br/><span class="hl-0">telegram</span><span class="hl-1">.</span><span class="hl-7">startPolling</span><span class="hl-1">();</span>
 </code></pre>
 
+<a href="#telegram-events" id="telegram-events" style="color: inherit; text-decoration: none;">
+  <h2>Telegram Events</h2>
+</a>
+<p>Events you can listen to usign <code>teletron-ts</code>:</p>
+<ul>
+<li>message</li>
+<li>edited_message</li>
+<li>edited_channel_post</li>
+<li>channel_post</li>
+<li>inline_query</li>
+<li>chosen_inline_result</li>
+<li>callback_query</li>
+<li>shipping_query</li>
+<li>poll</li>
+<li>poll_answer</li>
+<li>chat_join_request</li>
+</ul>
+<p>Please note that both <code>inline_query</code> and <code>chosen_inline_result</code> only work if you enabled this option by sending <code>/setinline</code> to <code>@BotFather</code></p>
+<p>For more information regarding inline queries visit the telegram docs <a href="https://core.telegram.org/bots/inline">here</a></p>
+
+<a href="#examples" id="examples" style="color: inherit; text-decoration: none;">
+  <h2>Examples</h2>
+</a>
+
+<a href="#sending-files" id="sending-files" style="color: inherit; text-decoration: none;">
+  <h3>Sending Files</h3>
+</a>
+<p>There are 3 ways to send files. You can use the file id of a file that already exist on telegram servers, provide an HTTP URL to the file which then will be downloaded by telegram servers or upload a local file. Lets assume we want to send a photo via the bot:</p>
+<pre><code class="language-ts"><span class="hl-2">import</span><span class="hl-1"> { </span><span class="hl-0">TelegramAPI</span><span class="hl-1"> } </span><span class="hl-2">from</span><span class="hl-1"> </span><span class="hl-4">&quot;teletron-ts&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-6">telegram</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-7">TelegramAPI</span><span class="hl-1">(</span><span class="hl-4">&quot;token&quot;</span><span class="hl-1">); </span><span class="hl-5">// bot token</span><br/><br/><span class="hl-0">telegram</span><span class="hl-1">.</span><span class="hl-7">on</span><span class="hl-1">(</span><span class="hl-4">&quot;message&quot;</span><span class="hl-1">, </span><span class="hl-3">async</span><span class="hl-1"> (</span><span class="hl-0">message</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-5">// First Method: Using an already existing file_id of a file that has been previously uploaded on telegram</span><br/><span class="hl-1">  </span><span class="hl-2">await</span><span class="hl-1"> </span><span class="hl-0">telegram</span><span class="hl-1">.</span><span class="hl-7">sendPhoto</span><span class="hl-1">(</span><br/><span class="hl-1">    </span><span class="hl-0">message</span><span class="hl-1">.</span><span class="hl-0">chat</span><span class="hl-1">.</span><span class="hl-0">id</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-4">&quot;AgADBQADqacxG2gbbxCWBkgvcmeAgxVPyjIABBlug37DKyhDEU0AAgI&quot;</span><br/><span class="hl-1">  );</span><br/><br/><span class="hl-1">  </span><span class="hl-5">// Second Method: Using an HTTP photo url</span><br/><span class="hl-1">  </span><span class="hl-2">await</span><span class="hl-1"> </span><span class="hl-0">telegram</span><span class="hl-1">.</span><span class="hl-7">sendPhoto</span><span class="hl-1">(</span><br/><span class="hl-1">    </span><span class="hl-0">message</span><span class="hl-1">.</span><span class="hl-0">chat</span><span class="hl-1">.</span><span class="hl-0">id</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-4">&quot;https://reshape.sport1.de/c/t/85599615-c80d-47f0-9179-4375d6e4fa93/976x549&quot;</span><br/><span class="hl-1">  );</span><br/><br/><span class="hl-1">  </span><span class="hl-5">// Thrid Method: Using a local file</span><br/><span class="hl-1">  </span><span class="hl-2">await</span><span class="hl-1"> </span><span class="hl-0">telegram</span><span class="hl-1">.</span><span class="hl-7">sendPhoto</span><span class="hl-1">(</span><span class="hl-0">message</span><span class="hl-1">.</span><span class="hl-0">chat</span><span class="hl-1">.</span><span class="hl-0">id</span><span class="hl-1">, { </span><span class="hl-0">file:</span><span class="hl-1"> </span><span class="hl-4">&quot;./anime.jpg&quot;</span><span class="hl-1"> });</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-5">// fetch updates from the api</span><br/><span class="hl-0">telegram</span><span class="hl-1">.</span><span class="hl-7">startPolling</span><span class="hl-1">();</span>
+</code></pre>
+
+<a href="#inline-keyboards" id="inline-keyboards" style="color: inherit; text-decoration: none;">
+  <h3>Inline Keyboards</h3>
+</a>
+<p>Inline keyboards are buttons that will be sent along with the message. These become especially useful if you want to wait for user input to perform certain action!</p>
+<pre><code class="language-ts"><span class="hl-2">import</span><span class="hl-1"> { </span><span class="hl-0">TelegramAPI</span><span class="hl-1"> } </span><span class="hl-2">from</span><span class="hl-1"> </span><span class="hl-4">&quot;teletron-ts&quot;</span><span class="hl-1">;</span><br/><span class="hl-2">import</span><span class="hl-1"> { </span><span class="hl-0">IInlineKeyboardMarkup</span><span class="hl-1"> } </span><span class="hl-2">from</span><span class="hl-1"> </span><span class="hl-4">&quot;teletron-ts&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-6">telegram</span><span class="hl-1"> = </span><span class="hl-3">new</span><span class="hl-1"> </span><span class="hl-7">TelegramAPI</span><span class="hl-1">(</span><span class="hl-4">&quot;token&quot;</span><span class="hl-1">);</span><br/><br/><span class="hl-0">telegram</span><span class="hl-1">.</span><span class="hl-7">on</span><span class="hl-1">(</span><span class="hl-4">&quot;message&quot;</span><span class="hl-1">, </span><span class="hl-3">async</span><span class="hl-1"> (</span><span class="hl-0">m</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-3">const</span><span class="hl-1"> </span><span class="hl-6">inlineKeyboards</span><span class="hl-1">: </span><span class="hl-8">IInlineKeyboardMarkup</span><span class="hl-1"> = {</span><br/><span class="hl-1">    </span><span class="hl-0">inline_keyboard:</span><span class="hl-1"> [</span><br/><span class="hl-1">      [</span><br/><span class="hl-1">        { </span><span class="hl-0">text:</span><span class="hl-1"> </span><span class="hl-4">&quot;Very Good!&quot;</span><span class="hl-1">, </span><span class="hl-0">callback_data:</span><span class="hl-1"> </span><span class="hl-4">&quot;vgood&quot;</span><span class="hl-1"> },</span><br/><span class="hl-1">        { </span><span class="hl-0">text:</span><span class="hl-1"> </span><span class="hl-4">&quot;Fine&quot;</span><span class="hl-1">, </span><span class="hl-0">callback_data:</span><span class="hl-1"> </span><span class="hl-4">&quot;fine&quot;</span><span class="hl-1"> },</span><br/><span class="hl-1">      ],</span><br/><span class="hl-1">      [{ </span><span class="hl-0">text:</span><span class="hl-1"> </span><span class="hl-4">&quot;Amazing&quot;</span><span class="hl-1">, </span><span class="hl-0">callback_data:</span><span class="hl-1"> </span><span class="hl-4">&quot;amazing&quot;</span><span class="hl-1"> }],</span><br/><span class="hl-1">    ],</span><br/><span class="hl-1">  };</span><br/><br/><span class="hl-1">  </span><span class="hl-2">await</span><span class="hl-1"> </span><span class="hl-0">telegram</span><span class="hl-1">.</span><span class="hl-7">sendMessage</span><span class="hl-1">(</span><br/><span class="hl-1">    </span><span class="hl-0">m</span><span class="hl-1">.</span><span class="hl-0">chat</span><span class="hl-1">.</span><span class="hl-0">id</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-4">&quot;Hey there, how are you feeling today?&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">    {</span><br/><span class="hl-1">      </span><span class="hl-0">reply_markup:</span><span class="hl-1"> </span><span class="hl-8">JSON</span><span class="hl-1">.</span><span class="hl-7">stringify</span><span class="hl-1">(</span><span class="hl-0">inlineKeyboards</span><span class="hl-1">),</span><br/><span class="hl-1">    }</span><br/><span class="hl-1">  );</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-0">telegram</span><span class="hl-1">.</span><span class="hl-7">on</span><span class="hl-1">(</span><span class="hl-4">&quot;callback_query&quot;</span><span class="hl-1">, </span><span class="hl-3">async</span><span class="hl-1"> (</span><span class="hl-0">query</span><span class="hl-1">) </span><span class="hl-3">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-2">if</span><span class="hl-1"> (</span><span class="hl-0">query</span><span class="hl-1">.</span><span class="hl-0">data</span><span class="hl-1"> &amp;&amp; </span><span class="hl-0">query</span><span class="hl-1">.</span><span class="hl-0">data</span><span class="hl-1"> === </span><span class="hl-4">&quot;vgood&quot;</span><span class="hl-1">)</span><br/><span class="hl-1">    </span><span class="hl-2">return</span><span class="hl-1"> </span><span class="hl-2">await</span><span class="hl-1"> </span><span class="hl-0">telegram</span><span class="hl-1">.</span><span class="hl-7">sendMessage</span><span class="hl-1">(</span><br/><span class="hl-1">      </span><span class="hl-0">query</span><span class="hl-1">.</span><span class="hl-0">message</span><span class="hl-1">.</span><span class="hl-0">chat</span><span class="hl-1">.</span><span class="hl-0">id</span><span class="hl-1">,</span><br/><span class="hl-1">      </span><span class="hl-4">&quot;I am feeling very good today too!&quot;</span><br/><span class="hl-1">    );</span><br/><span class="hl-1">});</span>
+</code></pre>
+
 <a href="#contributions" id="contributions" style="color: inherit; text-decoration: none;">
   <h2>Contributions</h2>
 </a>