Re: PureTelegram (framework for using the Telegram API)
Posted: Tue Feb 02, 2021 1:48 pm
The framework is now too big to fit in a forum post so I have uploaded it to Mediafire. (Link in OP.) I have also given it the name PureTelegram - after all, why not?
Other changes:
Now, handling updates...
Some things you need to understand about Telegram's API.
Another way to use it is to call GetNewUpdates() with a maximum wait time, in which case it will "long poll" Telegram and get updated as soon as an event occurs. Obviously, long polling is something you only want to do in a threaded program.
Note that you could interact with multiple bots in the same program:
This will probably be the final version of this framework, unless Telegram expand their API with more functions that I want to use. I haven't coded for everything that is already in the API, just what I personally felt like doing. If anyone who uses PureTelegram feels that something important is missing, let me know and I'll see about adding it. Likewise, if you write any generic components that could be useful, please post them here and I will add them to the PBI.
Anyway, this little project has been a pleasure to work on, and I hope that the framework gives people ideas for new ways they could interact with what seems to be very much an up-and-coming messaging platform.
Other changes:
First, a note about Telegram's unusual ways for referring to users:Added: PostVenue()
Added: PostLocation()
Added: PostContact()
Renamed: CreatePoll() to PostPoll()
Changed: PostAlbum() now returns a 1-based array of "message ID" integers
Added: GetStickerSet()
Added: UploadStickerFile()
Added: CreateNewStickerSet()
Added: AddStickerToSet()
Added: SetStickerPositionInSet()
Added: DeleteStickerFromSet()
Added: SetStickerSetThumb()
Added: SetChatStickerSet()
Added: DeleteChatStickerSet()
Added: a system for handling updates
- user_id
An integer identifier which is unique and never changes. As such, this is the sensible way to refer to the user throughout your code, and the only way they can be referred to in API calls. - username (possibly blank)
A string which the user can change whenever they want, and might choose to keep blank. If it is non-blank, then their Telegram profile has a URL which can be used on the Internet, for example https://t.me/username. Also, they can be linked to within Telegram like this: "Please welcome @username to the group." - first_name
A string which the user can change whenever they want - last_name (possibly blank)
A string which the user can change whenever they want, and might choose to keep blank.
Now, handling updates...
Some things you need to understand about Telegram's API.
- An "update" describes a single event (a message has been posted, a message has been edited, etc.). Each time you ask the API for updates, it will deliver a maximum of 100. You can make multiple calls until the API runs out of updates to give you. All of this is wrapped into a single procedure in PureTelegram, which makes multiple calls to the server and then delivers all new available updates, in a structured list.
- The Telegram API endpoint is called GetUpdates, but the PureTelegram procedure is called GetNewUpdates(). Here's why. The API might only deliver a particular update once, then immediately "forget" it and never pass it to you again. It is impossible to know how long an update will persist after being sent, so I've written this framework to assume that any updates sent have already been "forgotten" by the API and to only request updates newer than the last one sent. To clarify the situation, I have named the procedure GetNewUpdates().
- An update will be one of eleven different types, depending on the type of event it is describing.
- PureTelegram uses two txt files in order to keep up with things. The first file is a bot-independent ledger of Telegram users and their names, so that you can work with that data outside of these GetNewUpdates() calls. Set this file using Telegram_InstantiateLedger(). The second file enables PureTelegram to "remember" the number of the last update it received from each bot. Set this file using Telegram_InstantiateBot(). You will need to call these two procedures once, before calling GetNewUpdates().
- Telegram's API delivers all structured data as JSON, which results in very unwieldly structuring, with pointlessly repeated fields all over the place. It is NOT elegant. PureTelegram creates a few generic custom variables in an attempt to make the data handling a bit easier. For each update, regardless of the type, it will automatically fill in the following additional top-level fields:
- id.i
- type.s
- group_or_channel.s (if the update relates to one)
- user.i (if the update relates to a particular user) - this will be their unique, unchanging ID number, as described above
Code: Select all
#BotAPIToken = ""
Telegram_InstantiateLedger("D:\tg_user_ledger.txt")
Telegram_InstantiateBot(@MyTG.TG_BotInstance,#BotAPIToken,"D:\tgbot_update_counter.txt")
Repeat
Telegram_GetNewUpdates(@MyTG)
ForEach MyTG\update()
With MyTG\update()
If \type = #TU_Type_MessagePosted
ss.s = "purebasic"
If FindString(\message\text+" "+\message\caption,ss,#PB_String_NoCase)
txt.s = Telegram_UserDisplayName(\user)+" said "+Chr(34)+ss+Chr(34)+"."+Chr(13)+Chr(10)+Telegram_MessageURLFromStructure(@\message)
MessageRequester("Telegram Report",txt)
EndIf
EndIf
EndWith
Next
Delay(30000) ; wait 30 seconds
ForEverCode: Select all
Telegram_GetNewUpdates(@MyTG,60) ; wait a maximum of 1 minute for Telegram to send updatesCode: Select all
Telegram_InstantiateLedger("D:\tg_user_ledger.txt")
Telegram_InstantiateBot(@MyBot1.TG_BotInstance,#Bot1APIToken,"D:\bot1_update_counter.txt")
Telegram_InstantiateBot(@MyBot2.TG_BotInstance,#Bot2APIToken,"D:\bot2_update_counter.txt")
Telegram_InstantiateBot(@MyBot3.TG_BotInstance,#Bot3APIToken,"D:\bot3_update_counter.txt")
Anyway, this little project has been a pleasure to work on, and I hope that the framework gives people ideas for new ways they could interact with what seems to be very much an up-and-coming messaging platform.
