octoleo/telegram-bot-bash
1
1
Fork 0
mirror of https://github.com/octoleo/telegram-bot-bash.git synced 2024-11-29 10:43:53 +00:00
Code Issues Projects Releases Wiki Activity

improve doc

Browse Source
This commit is contained in:
Kay Marquardt (Gnadelwartz) 2020-06-11 12:17:07 +02:00
parent b6e9f9ed16
commit e663979206
5 changed files with 30 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
README.html
View File

@ -118,6 +118,7 @@ Written by Drew (@topkecleon), Daniil Gentili (@danogentili), and Kay M (@gnadel
<li>Interactive Chats</li> <li>Interactive Chats</li>
<li>Background Jobs</li> <li>Background Jobs</li>
<li>Inline queries</li> <li>Inline queries</li>
<li>Send message errors</li>
</ul></li> </ul></li>
<li><a href="doc/4_expert.md">Expert Use</a> <li><a href="doc/4_expert.md">Expert Use</a>
<ul> <ul>
@ -245,6 +246,6 @@ It features background tasks and interactive chats, and can serve as an interfac
<p>@Gnadelwartz</p> <p>@Gnadelwartz</p>
<h2>That's it!</h2> <h2>That's it!</h2>
<p>If you feel that there's something missing or if you found a bug, feel free to submit a pull request!</p> <p>If you feel that there's something missing or if you found a bug, feel free to submit a pull request!</p>
<h4>$$VERSION$$ v0.96-pre-13-ga71d68e</h4> <h4>$$VERSION$$ v0.96-pre-39-gb6e9f9e</h4>
</body> </body>
</html> </html>

3
README.md
View File

@ -37,6 +37,7 @@ Bashbot [Documentation](https://github.com/topkecleon/telegram-bot-bash) and [Do
* Interactive Chats * Interactive Chats
* Background Jobs * Background Jobs
* Inline queries * Inline queries
* Send message errors
* [Expert Use](doc/4_expert.md) * [Expert Use](doc/4_expert.md)
* Handling UTF-8 character sets * Handling UTF-8 character sets
* Run as other user or system service * Run as other user or system service
@ -218,4 +219,4 @@ This may happen if to many wrong requests are sent to api.telegram.org, e.g. usi
If you feel that there's something missing or if you found a bug, feel free to submit a pull request! If you feel that there's something missing or if you found a bug, feel free to submit a pull request!
#### $$VERSION$$ v0.96-pre-13-ga71d68e #### $$VERSION$$ v0.96-pre-39-gb6e9f9e

3
README.txt
View File

@ -50,6 +50,7 @@ availible on www.github.com
* Interactive Chats * Interactive Chats
* Background Jobs * Background Jobs
* Inline queries * Inline queries
* Send message errors
* [Expert Use](doc/4_expert.md) * [Expert Use](doc/4_expert.md)
* Handling UTF-8 character sets * Handling UTF-8 character sets
* Run as other user or system service * Run as other user or system service
@ -304,4 +305,4 @@ in 'mycommands.sh' as example.
If you feel that there's something missing or if you found a bug, feel free to If you feel that there's something missing or if you found a bug, feel free to
submit a pull request! submit a pull request!
#### $$VERSION$$ v0.96-pre-13-ga71d68e #### $$VERSION$$ v0.96-pre-39-gb6e9f9e

26
doc/3_advanced.md
View File

@ -206,27 +206,30 @@ See also [answer_inline_multi, answer_inline_compose](6_reference.md#answer_inli
### Handle send message errors ### Handle send message errors
Usually the exmaples do not care if an error happen while sending a message, this is because bashbot detects if a message is Our examples usually do not care about errors happening while sending a message, this is OK as long your bot does not send an
not sent and try to recover when possible, e.g. resend on throttling. massive aoumnt of messages. By default bashbot detects if a message is not sent and try to recover when possible,
e.g. resend on throttling. In addtion every send error is logged in logs/ERROR.log
In addition on every transmission to telegram the results are provided as bash in bash variables.
#### Trasmission results #### Trasmission results
On every message send to telgram (transmission) the results are provided in bash variables, like its done when a new message
is received.
**Note**: the values of the variables contains always the result of the LAST transmission to telegram, **Note**: the values of the variables contains always the result of the LAST transmission to telegram,
everey send action will overwrite them! every send action will overwrite them!
* ```$BOTSENT```: This array contains the parsed results from the last transmission to telegram. * ```$BOTSENT```: This array contains the parsed results from the last transmission to telegram.
* ```${BOTSENT[OK]}```: contain's the string 'true' after a successful transmission * ```${BOTSENT[OK]}```: contains the string ```true```: after a successful transmission
* ```${BOTSENT[ERROR]}```: Error code if OK is not true * ```${BOTSENT[ERROR]}```: Error code if an error occured
* ```${BOTSENT[DESC]}```: Description text for error * ```${BOTSENT[DESC]}```: Description text for error
* ```${BOTSENT[RETRY]}```: Seconds to wait ifntelegram requests throtteling. * ```${BOTSENT[RETRY]}```: Seconds to wait if telegram requests throtteling.
* ```$res```: temporary variable containing the full transmission result, may be overwritten by any bashbot function. * ```$res```: temporary variable containing the full transmission result, may be overwritten by any bashbot function.
By default you don't have to care about retry, as bashbot resend the message after the requested time automatically. By default you don't have to care about retry, as bashbot resend the message after the requested time automatically.
Only if the retry fails also an error is returned. The downside is that send_message functions will wait until resend is done. Only if the retry fails also an error is returned. The downside is that send_message functions will wait until resend is done.
If you want to disbale all automtic error processing and handle all errors manually (or don't care) If you want to disable automtic error processing and handle all errors manually (or don't care)
set ```BASHBOT_RETRY``` to any no zero value. set ```BASHBOT_RETRY``` to any no zero value.
[Telegram API error codes](https://core.telegram.org/api/errors) [Telegram API error codes](https://core.telegram.org/api/errors)
@ -235,12 +238,13 @@ set ```BASHBOT_RETRY``` to any no zero value.
#### Detect bot blocked #### Detect bot blocked
If the we can't connect to telegram, e.g. blocked from telegram server but also any other reason, If the we can't connect to telegram, e.g. blocked from telegram server but also any other reason,
bashbot set ```BOTSENT[ERROR]``` to '999'. bashbot set ```BOTSENT[ERROR]``` to ```999```.
To get a notification on every connection problem create a function named ```bashbotBlockRecover``` and handle blocks there. To get a notification on every connection problem create a function named ```bashbotBlockRecover``` and handle blocks there.
If the function returns true (0 or no value) bashbot will retry once and then return to the calling function. If the function returns true (0 or no value) bashbot will retry once and then return to the calling function.
In case you return any non 0 value bashbot will return to the calling function without retry. In case you return any non 0 value bashbot will return to the calling function without retry.
Note: If you disable automatic retry, se above, you disable also connection problem notification.
```bash ```bash
# somewhere in myfunctions.sh ... # somewhere in myfunctions.sh ...
@ -249,7 +253,7 @@ In case you return any non 0 value bashbot will return to the calling function w
function bashbotBlockRecover() { function bashbotBlockRecover() {
# ups, we are blocked! # ups, we are blocked!
(( MYBLOCKED++ )) (( MYBLOCKED++ ))
# log what we gotr # log what we got
printf "%s: Blocked %d times: %s\n" "$(date)" "${MYBLOCKED}" "$*" >>"${ERRORLOG}" printf "%s: Blocked %d times: %s\n" "$(date)" "${MYBLOCKED}" "$*" >>"${ERRORLOG}"
if [ "${MYBLOCKED}" -gt 10 ]; then if [ "${MYBLOCKED}" -gt 10 ]; then
@ -270,5 +274,5 @@ In case you return any non 0 value bashbot will return to the calling function w
#### [Prev Getting started](2_usage.md) #### [Prev Getting started](2_usage.md)
#### [Next Expert Use](4_expert.md) #### [Next Expert Use](4_expert.md)
#### $$VERSION$$ v0.96-pre-37-g6c02bab #### $$VERSION$$ v0.96-pre-39-gb6e9f9e

16
doc/7_develop.md
View File

@ -56,7 +56,7 @@ Note: For the same reason event function MUST return immediately! Time consuming
##### SEND RECEIVE events ##### SEND RECEIVE events
executed when a Message is received, same iQuery / Message variables are avalible as in commands.sh An RECEIVE event is executed when a Message is received, same iQuery / Message variables are avalible as in commands.sh
* BASHBOT_EVENT_INLINE an inline query is received * BASHBOT_EVENT_INLINE an inline query is received
@ -89,6 +89,8 @@ example_echo() {
} }
``` ```
An SEND event is executed when a Message is send tomtelegram.
* BASHBOT_EVENT_SEND is exceuted if data is send or uploaded to Telegram server * BASHBOT_EVENT_SEND is exceuted if data is send or uploaded to Telegram server
In contrast to other events, BASHBOT_EVENT_SEND is excecuted in a subshell, so there is no need to spawn In contrast to other events, BASHBOT_EVENT_SEND is excecuted in a subshell, so there is no need to spawn
@ -117,7 +119,7 @@ example_log(){
##### TIMER events ##### TIMER events
Important: The timer tick is diabled by default and must be enabled by setting BASHBOT_START_TIMER to any value not zero. Important: Bashbot timer tick is diabled by default and must be enabled by setting BASHBOT_START_TIMER to any value not zero.
* BAHSBOT_EVENT_TIMER executed every minute and can be used in 3 variants: oneshot, once a minute, every X minutes. * BAHSBOT_EVENT_TIMER executed every minute and can be used in 3 variants: oneshot, once a minute, every X minutes.
@ -133,9 +135,9 @@ This means if you register an every 5 minutes callback first execution may < 5 M
* 0 ignored * 0 ignored
* 1 execute once every minute * 1 execute once every minute
* x execute every x minutes * x execute every x minutes
* -x execute ONCE in (next) x minutes * * -x execute once WHITHIN the next x Minutes (10=between now and 10 Minutes)
*\* if you really want "in x minutes" you must use ```-(EVENT_TIMER+x)```* Note: If you want exact "in x minutes" use "EVENT_TIMER plus x" as time: ```-(EVENT_TIMER + x)```
*Example:* *Example:*
```bash ```bash
@ -151,10 +153,10 @@ example_everymin() {
# register other callback: # register other callback:
BAHSBOT_EVENT_TIMER["example_every5","5"]="example_every5min" BAHSBOT_EVENT_TIMER["example_every5","5"]="example_every5min"
# execute once in the next 10 minutes # execute once in the next 1 to 10 minutes
BAHSBOT_EVENT_TIMER["example_10min","-10"]="example_in10min" BAHSBOT_EVENT_TIMER["example_10min","-10"]="example_in10min"
# once in 10 minutes # once in exact 10 minutes
BAHSBOT_EVENT_TIMER["example_10min","$(( (EVENT_TIMER+10) * -1 ))"]="example_in10min" BAHSBOT_EVENT_TIMER["example_10min","$(( (EVENT_TIMER+10) * -1 ))"]="example_in10min"
``` ```
@ -336,5 +338,5 @@ fi
#### [Prev Function Reference](6_reference.md) #### [Prev Function Reference](6_reference.md)
#### $$VERSION$$ v0.96-pre-36-g81c8771 #### $$VERSION$$ v0.96-pre-39-gb6e9f9e