Improve documentation

[eqMFqfFd]

[removed]

[noplanman]

@kenygamer Thanks for posting this issue. It's quite unfortunate that you've removed your comment, I urge you to revert it, so that it can be worked on.

I fully agree that a good documentation is really needed, but as with many open source projects with few (or just 1) people working actively on it, time is a limiting factor.

If you feel happy to revert to your initial comment, I'd be happy to try and correct some of the points you've raised, which are great input!

[eqMFqfFd]

@noplanman I reverted my comment!

[noplanman]

@kenygamer, I've moved this issue to the core repo and will be working on it from here.

To answer some of your questions, which should then be moved to a dedicated documentation for newcomers.

This script gives the following output all time: "Webhook is already set"

The way the webhook works, is that it must be set only once, using set.php from the examples. The webhook then points to a file that handles it, in this case hook.php. For that reason, setting the webhook shouldn't be in the script handling the webhook request.

What are "command configs"

These are configurations that are passed to the commands and can be then be accessed from within the command with $this->getConfig('my_config'). This is very useful for passing API keys or other vital info that you want to define directly in the hook.php.

..."command paths". Why do I specify an entire directory of commands? Shouldn't I just enter the name of the command handler like PingCommand::class?

As it is now, commands are loaded from a folder, so all custom commands from within an assigned folder get loaded. This will change in future, when a proper command management is built, which will then work how you expect it, by adding individual commands by class name or object.

"Input is empty!" What sort of input are you talking to me about? I have no clue what input this is, the error is as generic as it is esoteric to understand.

When defining a webhook, that file should only be accessed by Telegram, which sends data along with the request (the actual "Input"). When calling the file directly, this input is missing. I've already created a PR which improves the error message, thanks for the nudge!

I believe you should also work on a proper documentation, that embraces all your libraries as a whole instead of making this ball harder to untangle than it is.

Couldn't agree more! The near-future plan is to integrate various extras from the telegram-bot-manager project directly into core and have a dedicated CLI tool for managing the bot. The docs have been started, but need lots of love still, you can find them in the dedicated repo here: https://github.com/php-telegram-bot/docs/tree/develop

Hope this clears some things up 😊

[eqMFqfFd]

I'm sorry, but none of your help helps me. Starting from scratch, you tell me to install the core library with composer. I did it, it's perfectly installed. Then,

I install the bot manager library. We have a file structure in which the 'hook.php' file is on the web server, and manager.php, set.php and unset.php (taken from the example library) that are in another directory that is not on the web server.

I make another paragraph for the set.php and unset.php files since they are in the example bot, however the manager.php file has set and unset actions too?

I rename the example configuration to config.php and I set the entries, including the database, the paths, the api key, and the bot username.

I run the manager.php file, even not being the hook.php file:

Imput is empty!

Which contradicts what you just told me since manager.php must be run instead of hook.php and I have the same error that I had with hook.php.

Then I read below. The hook.php file is magically not necessary anymore. That is done by the "getUpdates" method which I understand is a loop.

Then, I can't seem to find the command that starts the bot. I read below, and it tells me that I should run it as:

manager.php action = (??) i = (??) (??)

InvalidActionException

And then,

No command(s) provided!

When I try:

manager.php a=cron g=maintennace, cleanup

At least the error changed.

At first it tells me to use the hook file and I shouldn't use it anymore. Now the manager file that should be in the manager library is in the example bot and I don't even know how I can start it up.

I've been trying to solve this issue for 20+ hours, I think the last straw is that the documentation is so bad. Please try to reply to me soon, since I needed this in 24 hours and it is already 3 weeks. I have a whole project paralyzed for not being able to get a simple Telegram bot working.

[eqMFqfFd]

@noplanman I have managed to get a command working by ignoring the output of manage.php, I am extremely confused with:

Definitions

What is the difference between user command, system command and admin command?

Command execution

This is my biggest problem because I have managed to have my first GenericCommand working. After seeing how this command was done, it actually runs with non-existent commands and when using /generic.

Explain to me what the "version" command is, and why this matters.

Explain to me why, once I send a flood of about 20 messages, why is Telegram not reflecting the changes in my command handler file?

Why when I read the update.log it fills up every like 2 minutes with a bunch of commands that were 15 minutes ago? (comparing execution date in logs). Why is the update not instantaneous?

Explain to me how polls are sent, for example, since according to the Telegram documentation to which we are referred, it says that I must send a response with parameters. Your $this->sendPoll() method admits an array which I suppose means that is the parameters? Well, I have passed in the chat parameter $this->getFrom()->getId(), and I have encoded the response array in json, I don't have any log back, instead the only thing I get (right now) is a bunch of update logs (every once in a while, like 2 minutes instead of being instant) of commands that I run a while ago.
(The message_id is always the same)

It is not showing any new command that is running at this minute, nor should it be some rate limit because my config has limiter.enable set to true?

[noplanman]

Hi @kenygamer, I'm sorry this is giving you so much trouble 😕

As mentioned in the example-bot repo, using the core directly (with hook.php) and using the manager (with manager.php) are 2 distinct ways of using the library. The manager is a wrapper that bakes in a few extra features on top of the core library (like pulling the webhook setting/unsetting in too).

When using the manager, setting the webhook can be done with CLI using php manager.php a=set, as opposed to executing the set.php script from the core library. In the background, the same thing happens though!
Same thing applies for unsetting and handling updates.

Note: The webhook must only ever be called by Telegram itself, not you or any script on your server.

What is the difference between user command, system command and admin command?

User: Can be executed by any user of your bot.
Admin: Can be executed by admin users.
System: Are meant to only be executed internally, not by a user.

Explain to me what the "version" command is, and why this matters.

What do you mean by this? Do you mean the $version parameter in the commands?

Explain to me why, once I send a flood of about 20 messages, why is Telegram not reflecting the changes in my command handler file?

Seems like your webhook isn't set correctly or isn't being handled properly. With the webhook set and handled correctly, sent messages should be handled instantly. Maybe it's a server problem?

Explain to me how polls are sent ... method admits an array which I suppose means that is the parameters?

Exactly! As with all Request::sendXYZ methods, the array parameter is the list of parameters as defined in the official Telegram Bot API docs. You can check the return value by using $response = Request::sendXYZ($data); and then checking the $response variable. That will also tell you if there was any error, like malformed parameters or whatever.

It is not showing any new command that is running at this minute, nor should it be some rate limit because my config has limiter.enable set to true?

No, that shouldn't be the case! The limiter only kicks in when a LOT of messages are being sent in short succession, to prevent API limits being reached.

Then, I can't seem to find the command that starts the bot.

When the webhook is set, that's it! Telegram then sends updates directly to your webhook, which are then handled accordingly.
If you choose to use the getUpdates method, which is polls the Telegram servers for updates and then handles them, you need to kick that off with php manager.php a=handle. The output should then show how many and which updates were handled.

manager.php a=cron g=maintennace, cleanup

Note here that there must not be a space for the comma separated list of groups, so it should be (with typo corrected):
manager.php a=cron g=maintenance,cleanup

[eqMFqfFd]

Whenever I run manager.php a=cron g=maintenance,cleanup, I get this output:

 Longman\TelegramBot\Exception\TelegramException: No command(s) provided!

It seems like no server issue, as I found an undefined method in my code.
I fixed it and then it sent a wave of responses to Telegram.

Is there a logger for this because otherwise it would lose countless hours debugging (for some of the large commands I need to work on)?

[eqMFqfFd]

@noplanman PS: Yes, I don't know what $version is, I see different version numbers in the example commands too, why is this needed?

[eqMFqfFd]

@noplanman Do you also know how can I do dropdowns, or select boxes? For example the native Telegram select boxes when you DM @Botfather