https://github.com/immmdreza/flamingoframework
Flamingo is a framework to build Telegram bots using .NET as easy as possible!
https://github.com/immmdreza/flamingoframework
csharp csharp-library dotnet telegram telegram-bot telegram-bot-api
Last synced: 3 months ago
JSON representation
Flamingo is a framework to build Telegram bots using .NET as easy as possible!
- Host: GitHub
- URL: https://github.com/immmdreza/flamingoframework
- Owner: immmdreza
- License: apache-2.0
- Created: 2021-06-28T09:58:51.000Z (almost 4 years ago)
- Default Branch: Flamingo-Adult
- Last Pushed: 2021-08-24T05:58:21.000Z (almost 4 years ago)
- Last Synced: 2025-01-20T06:45:10.258Z (5 months ago)
- Topics: csharp, csharp-library, dotnet, telegram, telegram-bot, telegram-bot-api
- Language: C#
- Homepage:
- Size: 2.11 MB
- Stars: 4
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Flamingo 🦩
Flamingo is a framework to build Telegram bots using .NET as easy as possible!
## To what purpose?
As you can see, Flamingo uses [Telegram.Bot](https://github.com/TelegramBots/Telegram.Bot) and [Telegram.Bot.Extensions.Polling](https://github.com/TelegramBots/Telegram.Bot.Extensions.Polling) (Just in case) as dependencies. so by installing this package you have pure packages for telegram bots in .NET.
But this one serves as a Top layer created over **TelegramBot** library to help you setup your bot in most easiest and also pro way! The very first and important purpose of Flamingo is simplicity, save time and cleaner code when writing telegram bots with .NET
**Remember that flamingo is just getting started**. it can grows with your support and help (help and support to an almost a large community)
In my turn, i tried to put all my experience here but there are a lot to go. lock into examples and you can examine the advantages of Flamingo ( at least in basic )
## Install
**Flamingo** is available in [Nuget](https://www.nuget.org/packages/Flamingo)
_⚠ Please consider this as a beta version yet!_
## How to use
Below there are some sources you can use
### Features ⭐️
Read more about some [features of Flamingo](https://github.com/immmdreza/FlamingoFramework/wiki/Features-%E2%AD%90%EF%B8%8F)
### Contribute
If you're interested to contribute ( as i hope so ) you can take look at [Contribute](https://github.com/immmdreza/FlamingoFramework/wiki/Contribute)
**Please read [WIKI](https://github.com/immmdreza/FlamingoFramework/wiki)**
Basic usage
_After installing Flamingo through Nuget package manager, you can use it like example below:_
#### 1- First of all Create an instance of `FlamingoCore` class into your program main method
```cs
static async Task Main()
{
var flamingo = await new FlamingoCore()
}
```
#### 2- Now is the time to initialize your bot. in order to do that you need a bot token
(You can make a new bot and get api token for it from [@BotFather](https://t.me/BotFather))
- bot token is something like: `123443536:Akhkhpoue_DLkhejbdkeaiDHJKFkjbjs_D`
- Use method InitBot to initialize the bot like below:
```cs
// Pass your bot token to the method
await flamingo.InitBot("123443536:Akhkhpoue_DLkhejbdkeaiDHJKFkjbjs_D")
```
_Remember, most of this library methods are `async`. meaning that you should `await` them and use them in an async function ( like `Main()` here )_
#### 3- Let's make our first handler. handlers are what you handle and process inComing updates the way you like.
- To quickly build a handler we Use `SimpleInComing`. where T is update type like messages, callback queries, inline queries and etc.
- To make handler for incoming messages, The `T` is `Message` ( like `SimpleInComing` )
#### 4- Every incoming handler has 2 important parts: **Filter** and **Callback function**
- Filters job is obvious: filter incoming updates to receive exact update you want
- Callback function: this function is where you decide how to process incoming update that passed filters.
### Filters
Here we use two filters:
- ChatTypeFilter: to make sure the update is coming from private chat
- CommandFilter: to handle specified bot command like `/start`
- To Combine filters we bitwise operator `&` Meaning `AND`!
Your filters should be like below:
```cs
var chatFilter = new ChatTypeFilter(FlamingoChatType.Private);
var commandFilter new CommandFilter("start");
```
Later we'll combine them!
### Callback function
Callback function should take an `ICondiment` which contain everything you need to handle your updates, and should return a boolean as Task ( awaitable method )
Method structure should be like this:
```cs
private static async Task CallbackFunc(ICondiment cdmt)
{
await cdmt.ReplyText("Just started!");
return true;
}
```
We decided to reply to use command with a text message: `"Just started!"`.
`cdmt.ReplyText()` dose that for us. it's an extension method of `ICondiment`
#### 5- Now that our filters and callback function is ready, we should pass them to handler instance (3)
```cs
var startHandler = new SimpleInComing(CallbackFunc,
chatFilter & commandFilter);
```
As you see we combined two filters with &, meaning both of them should pass!
#### 6- Now add your handler to the Flamingo
```cs
flamingo.AddInComing(startHandler);
```
#### 7- Start listening to updates
```cs
await flamingo.Fly();
```
Your `Program.cs` file should be like below:
```cs
using Flamingo;
using Flamingo.Condiments;
using Flamingo.Condiments.Extensions;
using Flamingo.Filters.MessageFilters;
using Flamingo.Filters.SharedFilters;
using Flamingo.Fishes.InComingFishes.SimpleInComings;
using Flamingo.Helpers.Types.Enums;
using System.Threading.Tasks;
using Telegram.Bot.Types;
namespace SimpleFlamingo
{
class Program
{
static async Task Main()
{
var flamingo = new FlamingoCore();
await flamingo.InitBot("1820608649:AAF_rimZO_y_RlYnTX2WnifXldL1GiIcxt4");
var chatFilter = new ChatTypeFilter(FlamingoChatType.Private);
var commandFilter = new CommandFilter("start");
var startHandler = new SimpleInComing(CallbackFunc,
chatFilter & commandFilter);
flamingo.AddInComing(startHandler);
await flamingo.Fly();
}
private static async Task CallbackFunc(ICondiment cdmt)
{
await cdmt.ReplyText("Just started!");
return true;
}
}
}
```
#### 8- Send command `/start` to your bot and see what happens
#### You can write all of these using Attributes even more quicker
- [See SimpleFlamingo](https://github.com/immmdreza/FlamingoFramework/blob/master/Examples/SimpleFlamingo/Program.cs)
## Await-able InComing Handlers
Wait for user respond!
[Read Wiki](https://github.com/immmdreza/FlamingoFramework/wiki/Await-able-InComing-handlers)
## More to go
There are some example projects that may help you for now.
Full explanation example with a lot of comments:
[FlamingoProduction](https://github.com/immmdreza/FlamingoFramework/tree/master/FlamingoProduction)
## Examples
### Simple Flamingo
An example of how to create a simple Flamingo app + simple Attribute handlers usage:
- [SimpleFlamingo](https://github.com/immmdreza/FlamingoFramework/tree/master/Examples/SimpleFlamingo)
### FillForm Flamingo
See how to use await-able incoming handlers to wait for user answers and fill a sign up form
- [FillFormFlamingo](https://github.com/immmdreza/FlamingoFramework/tree/master/Examples/FillFormFlamingo)
**Extremely advise you to take a look at `FillFormHelper` example**
_It has a lot of simplifiers that helps you ask form and validate them!_
- [FillFormHelper Example](https://github.com/immmdreza/FlamingoFramework/blob/master/FlamingoProduction/InComings/Messages/MyAdvMessageInComing.cs)
### DeepInside Flamingo
In this example we show you how to go deep inside flamingo and create your own handlers and condiments. so you can use any custom properties in your handlers and even control lifecycle of db objects and etc.
- [DeepInsideFlamingo](https://github.com/immmdreza/FlamingoFramework/tree/master/Examples/DeepInsideFlamingo)
### Fun Flamingo
A fun example that only flamingo allows you to build!
- [FunFlamingo](https://github.com/immmdreza/FlamingoFramework/tree/master/Examples/FunFlamingo)
### DeepLinking Flamingo
Learn how to setup deep linking in your bot
- [DeepLinkingFlamingo](https://github.com/immmdreza/FlamingoFramework/tree/master/Examples/DeepLinkingFlamingo)
### Keyboards Flamingo
Example to work with keyboards
- [KeyboardsFlamingo](https://github.com/immmdreza/FlamingoFramework/tree/master/Examples/KeyboardsFlamingo)