Feature #3147
Updated by Gregory Magarshak 9 months ago
Please read this: https://issues.qbix.com/projects/telegram/wiki/Wiki
This is the homework I gave to Andrey: https://issues.qbix.com/issues/3146
At the end of this homework, he will have implemented a simple Telegram plugin inside Qbix, that will handle updates.
Telegram bots / apps will be handled similarly to "web3" or "facebook" platform apps. The xid of a user is their userId on telegram. The appId of a bot might just be its username (because it's pretty constant, unlike a user's ID).
The Telegram plugin adds a hook to installer script which will call @setWebhook@ for each app inside "Users/apps/telegram/..." config.
The endpoint that will be hit will be @{{baseUrl}}/telegram.php@, similar to @{{baseUrl}}/index.php@ and will call @Telegram_Dispatcher::dispatch($update)@ similar to @Q_Dispatcher::dispatch($uri)@
so that you can implement event handlers in PHP for events such as:
* @Telegram/update/$PluginOrApp/message@
* @Telegram/update/$PluginOrApp/edited_message@
* @Telegram/update/$PluginOrApp/callback_query@
h2. What to do
Please clone https://repo.qbix.com/plugin/Telegram into @Q/platform/plugins/Telegram@ and add the usual folders like @handlers@ and @classes@. Make @classes/Telegram/Bot.php@ class and implement a bunch of static methods like @sendMessage(array $params)@ and @sendVideo(array $params)@. Document them with YUIDoc how I usually do elsewhere, by copying the documentation from https://core.telegram.org/bots/api#sendmessage . Feel free to copypaste this html into ChatGPT with a line on top instructing it to spit out the docs:
!clipboard-202408280257-nfd6r.png!
While Andrey works on this, you can IMPLEMENT and practice calling other methods, including:
* @Telegram_Bot::sendMessage($params)@ with parameter "@reply_markup@":https://core.telegram.org/bots/api#sendmessage containing a "@ForceReply@ structure":https://core.telegram.org/bots/api#forcereply
* @Telegram_Bot::sendMessage()@ with inline keyboards, which you can adapt from the code here: https://issues.qbix.com/projects/telegram/wiki/Lesson_1_Code
* @Telegram_Bot::sendMessage()@ with "reply keyboards":https://core.telegram.org/bots/api#replykeyboardmarkup
* I recommend creating three static methods @Telegram_Bot::forceReply($forceReply, $inputFieldPlaceholder = null, $selective = false)@ @Telegram_Bot::replyKeyboard()@ and @Telegram_Bot::inlineKeyboard()@ methods and again, copypaste the documentation into ChatGPT to spit out the YUIDoc. These methods should return an @array()@ of arrays, that can be json-encoded, and passed to parameters inside @sendMessage@.
* Implement @Telegram_Bot::answerCallbackQuery()@ function with the chatgpt-generated copypaste "from the docs here":https://core.telegram.org/bots/api#replykeyboardmarkup
* @$result = Telegram_Bot::sendVideo()@ and @sendAudio@ with actual mp4 and mp3 files on the web. You can find some on our own server under @/live/ITR/web/Q/uploads/...@ and their URLs are @https://intercoin.app/Q/uploads/...@
After Andrey implements the above framework, please help him test the above 3 events, using the code you wrote.
h2. Already uploaded files to Telegram
Practice creating a Qbix installer file like this: @plugins/Telegram/scripts/Telegram/0.1-Telegram.mysql@ which will create a table:
<pre>
CREATE TABLE {{prefix}}file
url VARCHAR(255) COMMENT "the url of the original file"
id VARCHAR(255) COMMENT "the id of the uploaded file on telegram",
status state ENUM('uploading', 'processing', 'ready')
ADD INDEX ('id') // not unique index
ADD INDEX ('url') // not unique index
</pre>
Run this installer, and then call `scripts/Q/models.php --plugin Telegram` to generate the models in the `Telegram/classes` folder. All the files along with the code files you wrote, to version control, to be checked in.
Store the URLs in this table, in a format like literal strings: "{{Users}}/foo/bar.mp4" or "{{baseUrl}}/foo/bar.mp4" and not "https://hardcoded.url.here/foo/bar.mp4" so the app can be migrated to other domains.
When you @sendVideo()@ you should first check if the file `url` already exists (replacing @Q_Request::baseUrl()@ with '{{baseUrl}}' before calling `Telegram_File::select()->where(compact('url'))`) . If it exists, then use the file id. Otherwise, use the URL, but if the method indicates success, then save the new row with `Telegram_File::insert()` or better yet: `(new Telegram_File($params))->save()`.