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

finalize features and descriptions

Browse Source
This commit is contained in:
Kay Marquardt (Gnadelwartz) 2019-04-16 13:29:49 +02:00
parent 4a944d9089
commit 1bf26b9caf
16 changed files with 201 additions and 166 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
README.md
View File

@ -28,7 +28,7 @@ Elsewhere, consider it released under the [WTFPLv2](http://www.wtfpl.net/txt/cop
3. Change to directory ```telegram-bot.bash```, run ```./bashbot.sh init``` and follow the instructions. At this stage you are asked for your Bots token given by botfather. 3. Change to directory ```telegram-bot.bash```, run ```./bashbot.sh init``` and follow the instructions. At this stage you are asked for your Bots token given by botfather.
## Update bashbot ## Update bashbot
[Download latest update zip from github](https://github.com/topkecleon/telegram-bot-bash/releases) extract all files and copy them to your bashbot dir. Now run ```sudo ./bashbot.sh init``` to setup your environment to the current release. [Download latest update zip from github](https://github.com/topkecleon/telegram-bot-bash/releases), extract all files and copy them to your bashbot dir. Now run ```sudo ./bashbot.sh init``` to setup your environment for the new release.
## Getting started ## Getting started
* [Create Telegram Bot with botfather](doc/1_firstbot.md) * [Create Telegram Bot with botfather](doc/1_firstbot.md)
@ -56,13 +56,13 @@ Elsewhere, consider it released under the [WTFPLv2](http://www.wtfpl.net/txt/cop
To make use of Keyboards easier the keybord format for ```send_keyboard``` and ```send_message "mykeyboardstartshere ..."``` was changed. To make use of Keyboards easier the keybord format for ```send_keyboard``` and ```send_message "mykeyboardstartshere ..."``` was changed.
Keybords are now defined in an JSON Array notation e.g. "[ \\"yes\\" , \\"no\\" ]". Keybords are now defined in an JSON Array notation e.g. "[ \\"yes\\" , \\"no\\" ]".
This has the advantage that you can create any type of keyboard supported by Telegram. This has the advantage that you can create any type of keyboard supported by Telegram.
**This is incompatible change for keyboards used in older bashbot versions** **This is an incompatible change for keyboards used in older bashbot versions.**
*Example Keyboards*: *Example Keyboards*:
- yes no in one row - yes no in one row
- OLD format: "yes" "no" (two strings) - OLD format: "yes" "no" (two strings)
- NEW format: "[ \\"yes\\" , \\"no\\" ]" (one string with array) - NEW format: "[ \\"yes\\" , \\"no\\" ]" (string containing an array)
- new keybord layouts, no possible with old format: - new keybord layouts, no possible with old format:
- Yes No in two rows: "[ \\"yes\\" ] , [ \\"no\\" ]" - Yes No in two rows: "[ \\"yes\\" ] , [ \\"no\\" ]"
- numpad style keyboard: "[ \\"1\\" , \\"2\\" , \\"3\\" ] , [ \\"4\\" , \\"5\\" , \\"6\\" ] , [ \\"7\\" , \\"8\\" , \\"9\\" ] , [ \\"0\\" ]" - numpad style keyboard: "[ \\"1\\" , \\"2\\" , \\"3\\" ] , [ \\"4\\" , \\"5\\" , \\"6\\" ] , [ \\"7\\" , \\"8\\" , \\"9\\" ] , [ \\"0\\" ]"
@ -72,30 +72,30 @@ Running a Telegram Bot means it is conneted to the public and you never know wha
Bash scripts in general are not designed to be bullet proof, so consider this Bot as a proof of concept. More concret examples of security problems is bash's 'quoting hell' and globbing. [Implications of wrong quoting](https://unix.stackexchange.com/questions/171346/security-implications-of-forgetting-to-quote-a-variable-in-bash-posix-shells) Bash scripts in general are not designed to be bullet proof, so consider this Bot as a proof of concept. More concret examples of security problems is bash's 'quoting hell' and globbing. [Implications of wrong quoting](https://unix.stackexchange.com/questions/171346/security-implications-of-forgetting-to-quote-a-variable-in-bash-posix-shells)
Whenever you are processing input from from untrusted sources (messages, files, network) you mustbe be as carefull as possible, e.g. disable globbing (set -f) and quote everthing. Whenever you are processing input from from untrusted sources (messages, files, network) you must be as carefull as possible, e.g. disable globbing (set -f) and quote everthing.
A powerful tool to improve your scripts robustness is [shellcheck](https://www.shellcheck.net/). You can use it online or [install shellcheck locally](https://github.com/koalaman/shellcheck#installing). All bashbot scripts are checked by shellcheck. A powerful tool to improve your scripts robustness is ```shellcheck```. You can [use it online](https://www.shellcheck.net/) or [install shellcheck locally](https://github.com/koalaman/shellcheck#installing). All bashbot scripts are checked by shellcheck.
### Run your Bot as a restricted user ### Run your Bot as a restricted user
It's important to run your bot as a user, with almost no access rights! **It's important to run your bot as a user, with almost no access rights.**
All files your Bot can write are in danger to be overwritten/deleted if your bot can be abused. All files your Bot write access to are in danger to be overwritten/deleted if your bot is hacked.
Every file your Bot can read is in danger of being disclosed for the same reason. For the same reason ervery file your Bot can read is in danger of being disclosed. So please restict your Bots access rigths to the absolute minimum.
**Never run your Bot as root, this is the most dangerous you can do!** Usually the user 'nobody' has almost no rigths on Unix/Linux systems. See Expert use on how to run your Bot as an other user. **Never run your Bot as root, this is the most dangerous you can do!** Usually the user 'nobody' has almost no rigths on Unix/Linux systems. See Expert use on how to run your Bot as an other user.
### Secure your Bot installation ### Secure your Bot installation
You Bot configuration contains data which should not be readable from other users. **Your Bot configuration should not be readable from other users.** If someone can read your Bots token he can act as your Bot and has access to all chats you bot is in!
Everyone who can read your Bot files can extract your Bots secret data. Especially your Bot Token in ```token``` must be protected against other users. No one exept you should have write access to the Bot files. The Bot itself can be restricted to have write access to ```count``` and ```tmp-bot-bash``` only, all other files should be write protected. Everyone with read access to your Bot files can extract your Bots data. Especially your Bot Token in ```token``` must be protected against other users. No one exept you should have write access to the Bot files. The Bot must be restricted to have write access to ```count``` and ```tmp-bot-bash``` only, all other files should be write protected.
To set access rights for your telegram-bot-bash directory to reasonable default values you should run ```sudo ./bashbot.sh init``` after every update or change to your installation directory. To set access rights for your telegram-bot-bash directory to reasonable default values you must run ```sudo ./bashbot.sh init``` after every update or change to your installation directory.
### Is this Bot insecure? ### Is this Bot insecure?
Bashbot is no more insecure as any other Bot written in any other language. But since YOU change the bot commands and run the Bot, you should know about the implications ... Bashbot is no more (in)secure as any other Bot written in any other language. But since YOU change your bots commands and run the Bot, you should know about the implications ...
## That's it! ## That's it!
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.60-rc2-2-g7727608 #### $$VERSION$$ v0.60-rc2-3-g4a944d9

115
README.txt
View File

@ -24,16 +24,14 @@ Install bashbot
~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~
1. Go to the directory you want to install bashbot, e.g. 1. Go to the directory you want to install bashbot, e.g.
* your $HOME directory (install and run with your user-ID) * your $HOME directory (install and run with your user-ID)
* /usr/local if you want to run as service * /usr/local if you want to run as service
2. Clone the repository:
1. Clone the repository:
+ +
.... ....
git clone --recursive https://github.com/topkecleon/telegram-bot-bash git clone --recursive https://github.com/topkecleon/telegram-bot-bash
.... ....
2. Change to directory `telegram-bot.bash`, run `./bashbot.sh init` and 3. Change to directory `telegram-bot.bash`, run `./bashbot.sh init` and
follow the instructions. At this stage you are asked for your Bots token follow the instructions. At this stage you are asked for your Bots token
given by botfather. given by botfather.
@ -41,54 +39,58 @@ Update bashbot
~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~
https://github.com/topkecleon/telegram-bot-bash/releases[Download latest https://github.com/topkecleon/telegram-bot-bash/releases[Download latest
update zip from github] and copy all files to bashbot dir. run update zip from github], extract all files and copy them to your bashbot
`sudo ./bashbot.sh init`. dir. Now run `sudo ./bashbot.sh init` to setup your environment for the
new release.
Getting started Getting started
~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~
* link:doc/1_firstbot.md[Create your first telegram bot] * link:doc/1_firstbot.md[Create Telegram Bot with botfather]
* link:doc/2_usage.md[Make your own Bot] * link:doc/2_usage.md[Getting Started]
* Managing your own Bot ** Managing your Bot
* Recieve data ** Recieve data
* Send Messages ** Send Messages
* Send files, location etc. ** Send files, location etc.
* link:doc/3_advanced.md[Advanced Features] * link:doc/3_advanced.md[Advanced Features]
* Access Control ** Access Control
* Interactive Chats ** Interactive Chats
* Background Jobs ** Background Jobs
* Inline queries ** Inline queries
* link:doc/4_expert.md[Expert Use] * link:doc/4_expert.md[Expert Use]
* Handling UTF-8 ** Handling UTF-8
* Run as other user or system service ** Run as other user or system service
* Scedule bashbot from Cron ** Scedule bashbot from Cron
* link:doc/5_practice.md[Best Practices] * link:doc/5_practice.md[Best Practices]
* Customizing commands.sh ** Customizing commands.sh
* Seperate Bot logic from command ** Seperate Bot logic from command
* Test your Bot with shellcheck ** Test your Bot with shellcheck
* link:doc/6_reference.md[Bashbot functions reference] * link:doc/6_reference.md[Bashbot functions reference]
Note on Keyboards Note on Keyboards
~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~
To make use of Keyboards easyer we changed the format of `send_keyboard` To make use of Keyboards easier the keybord format for `send_keyboard`
and `send_message "mykeyboardstartshere ..."`. Now you must provide the and `send_message "mykeyboardstartshere ..."` was changed. Keybords are
keyboards in Telegram JSON Array style "[ "yes" , "no" ]". The advantage now defined in an JSON Array notation e.g. "[ \"yes\" , \"no\" ]". This
is that you can create every type of keyboard without relying on bashbot has the advantage that you can create any type of keyboard supported by
`send_keyboard` functionality. *This is incompatible with keyboards in Telegram. *This is an incompatible change for keyboards used in older
bashbot versions older than 0.6!* bashbot versions.*
_Example Keyboards_: _Example Keyboards_:
* Yes No in one row: "[ "yes" , "no" ]" * yes no in one row
* Yes No ind two rows: "[ "yes" ] , [ "no" ]" ** OLD format: "yes" "no" (two strings)
* numpad keyboard: "[ "1" , "2" , "3" ] , [ "4" , "5" , "6" ] , [ "7" , ** NEW format: "[ \"yes\" , \"no\" ]" (string containing an array)
"8" , "9" ] , [ "0" ]" * new keybord layouts, no possible with old format:
** Yes No in two rows: "[ \"yes\" ] , [ \"no\" ]"
** numpad style keyboard: "[ \"1\" , \"2\" , \"3\" ] , [ \"4\" , \"5\" ,
\"6\" ] , [ \"7\" , \"8\" , \"9\" ] , [ \"0\" ]"
Security Considerations Security Considerations
~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~
Running a Telegram Bot means you are conneted to the public, you never Running a Telegram Bot means it is conneted to the public and you never
know whats send to your Bot. know whats send to your Bot.
Bash scripts in general are not designed to be bullet proof, so consider Bash scripts in general are not designed to be bullet proof, so consider
@ -97,42 +99,53 @@ problems is bash's 'quoting hell' and globbing.
https://unix.stackexchange.com/questions/171346/security-implications-of-forgetting-to-quote-a-variable-in-bash-posix-shells[Implications https://unix.stackexchange.com/questions/171346/security-implications-of-forgetting-to-quote-a-variable-in-bash-posix-shells[Implications
of wrong quoting] of wrong quoting]
Whenever you are processing input from outside your bot you should Whenever you are processing input from from untrusted sources (messages,
disable globbing (set -f) and carefully quote everthing. files, network) you must be as carefull as possible, e.g. disable
globbing (set -f) and quote everthing.
To improve you scripts we recommend to lint them with A powerful tool to improve your scripts robustness is `shellcheck`. You
https://www.shellcheck.net/[shellcheck]. This can be done online or you can https://www.shellcheck.net/[use it online] or
can https://github.com/koalaman/shellcheck#installing[install shellcheck https://github.com/koalaman/shellcheck#installing[install shellcheck
locally]. bashbot itself is also linted by shellcheck. locally]. All bashbot scripts are checked by shellcheck.
Run your Bot as a restricted user Run your Bot as a restricted user
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Every file your bot can write is in danger to be overwritten/deleted, In *It's important to run your bot as a user, with almost no access
case of bad handling of user input every file your Bot can read is in rights.*
danger of being disclosed.
Never run your Bot as root, this is the most dangerous you can do! All files your Bot write access to are in danger to be
overwritten/deleted if your bot is hacked. For the same reason ervery
file your Bot can read is in danger of being disclosed. So please
restict your Bots access rigths to the absolute minimum.
*Never run your Bot as root, this is the most dangerous you can do!*
Usually the user 'nobody' has almost no rigths on Unix/Linux systems. Usually the user 'nobody' has almost no rigths on Unix/Linux systems.
See Expert use on how to run your Bot as an other user. See Expert use on how to run your Bot as an other user.
Secure your Bot installation Secure your Bot installation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Everyone who can read your Bot files can extract your Bots data. *Your Bot configuration should not be readable from other users.* If
someone can read your Bots token he can act as your Bot and has access
to all chats you bot is in!
Everyone with read access to your Bot files can extract your Bots data.
Especially your Bot Token in `token` must be protected against other Especially your Bot Token in `token` must be protected against other
users. No one exept you should have write access to the Bot files. The users. No one exept you should have write access to the Bot files. The
Bot itself need write access to `count` and `tmp-bot-bash` only, all Bot must be restricted to have write access to `count` and
other files should be write protected. `tmp-bot-bash` only, all other files should be write protected.
Runing `./bashbot.sh init` sets the Bot permissions to reasonable To set access rights for your telegram-bot-bash directory to reasonable
default values as a starting point. default values you must run `sudo ./bashbot.sh init` after every update
or change to your installation directory.
Is this Bot insecure? Is this Bot insecure?
^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^
No - its not less (in)secure as any other Bot written in any other Bashbot is no more (in)secure as any other Bot written in any other
language. But you should know about the implications ... language. But since YOU change your bots commands and run the Bot, you
should know about the implications ...
That's it! That's it!
~~~~~~~~~~ ~~~~~~~~~~
@ -140,5 +153,5 @@ That's it!
If you feel that there's something missing or if you found a bug, feel If you feel that there's something missing or if you found a bug, feel
free to submit a pull request! free to submit a pull request!
latexmath:[\[VERSION\]] v0.60-rc2-0-gc581932 latexmath:[\[VERSION\]] v0.60-rc2-3-g4a944d9
++++++++++++++++++++++++++++++++++++++++++++ ++++++++++++++++++++++++++++++++++++++++++++

2
bashbot.cron
View File

@ -7,7 +7,7 @@
# This file is public domain in the USA and all free countries. # This file is public domain in the USA and all free countries.
# Elsewhere, consider it to be WTFPLv2. (wtfpl.net/txt/copying) # Elsewhere, consider it to be WTFPLv2. (wtfpl.net/txt/copying)
# #
#### $$VERSION$$ v0.60-rc2-0-gc581932 #### $$VERSION$$ v0.60-rc2-3-g4a944d9
SHELL=/bin/sh SHELL=/bin/sh

2
bashbot.rc
View File

@ -1,7 +1,7 @@
#!/bin/sh #!/bin/sh
# description: Start or stop telegram-bash-bot # description: Start or stop telegram-bash-bot
# #
#### $$VERSION$$ v0.60-rc2-0-gc581932 #### $$VERSION$$ v0.60-rc2-3-g4a944d9
# shellcheck disable=SC2009 # shellcheck disable=SC2009
# shellcheck disable=SC2181 # shellcheck disable=SC2181

8
bashbot.sh
View File

@ -10,7 +10,7 @@
# This file is public domain in the USA and all free countries. # This file is public domain in the USA and all free countries.
# Elsewhere, consider it to be WTFPLv2. (wtfpl.net/txt/copying) # Elsewhere, consider it to be WTFPLv2. (wtfpl.net/txt/copying)
# #
#### $$VERSION$$ v0.60-rc2-0-gc581932 #### $$VERSION$$ v0.60-rc2-3-g4a944d9
# #
# Exit Codes: # Exit Codes:
# - 0 sucess (hopefully) # - 0 sucess (hopefully)
@ -439,11 +439,13 @@ send_venue() {
} }
forward() { forward_message() {
[ "$3" = "" ] && return [ "$3" = "" ] && return
res="$(curl -s "$FORWARD_URL" -F "chat_id=$1" -F "from_chat_id=$2" -F "message_id=$3")" res="$(curl -s "$FORWARD_URL" -F "chat_id=$1" -F "from_chat_id=$2" -F "message_id=$3")"
} }
forward() { # backward compatibility
forward_message "$@" || return
}
background() { background() {
echo "${CHAT[ID]}:$2:$1" >"${TMPDIR:-.}/${copname}$2-back.cmd" echo "${CHAT[ID]}:$2:$1" >"${TMPDIR:-.}/${copname}$2-back.cmd"

13
calc
View File

@ -3,7 +3,7 @@
# This file is public domain in the USA and all free countries. # This file is public domain in the USA and all free countries.
# Elsewhere, consider it to be WTFPLv2. (wtfpl.net/txt/copying) # Elsewhere, consider it to be WTFPLv2. (wtfpl.net/txt/copying)
#### $$VERSION$$ v0.60-rc2-0-gc581932 #### $$VERSION$$ v0.60-rc2-3-g4a944d9
# adjust your language setting here # adjust your language setting here
# https://github.com/topkecleon/telegram-bot-bash#setting-up-your-environment # https://github.com/topkecleon/telegram-bot-bash#setting-up-your-environment
@ -23,11 +23,12 @@ echo 'Select Operation: mykeyboardstartshere [ "Addition" , "Subtraction" , "Mul
read -r opt read -r opt
echo -n 'Result: ' echo -n 'Result: '
case $opt in case $opt in
'add'* | 'Add'* ) expr $A + $B ;; 'add'* | 'Add'* ) res="$(( A + B ))" ;;
'sub'* | 'Sub'* ) expr $A - $B ;; 'sub'* | 'Sub'* ) res="$(( A - B ))" ;;
'mul'* | 'Mul'* ) expr $A \* $B ;; 'mul'* | 'Mul'* ) res="$(( A * B ))" ;;
'div'* | 'Div'* ) expr $A / $B ;; 'div'* | 'Div'* ) res="$(( A / B ))" ;;
'can'* | 'Can'* ) echo "abort!" ;; 'can'* | 'Can'* ) res="abort!" ;;
* ) echo "unknown operator!";; * ) echo "unknown operator!";;
esac esac
echo "$res"
echo "Bye .." echo "Bye .."

2
commands.sh
View File

@ -4,7 +4,7 @@
# This file is public domain in the USA and all free countries. # This file is public domain in the USA and all free countries.
# Elsewhere, consider it to be WTFPLv2. (wtfpl.net/txt/copying) # Elsewhere, consider it to be WTFPLv2. (wtfpl.net/txt/copying)
# #
#### $$VERSION$$ v0.60-rc2-0-gc581932 #### $$VERSION$$ v0.60-rc2-3-g4a944d9
# #
# shellcheck disable=SC2154 # shellcheck disable=SC2154
# shellcheck disable=SC2034 # shellcheck disable=SC2034

2
doc/1_firstbot.md
View File

@ -70,5 +70,5 @@ git clone --recursive https://github.com/topkecleon/telegram-bot-bash
``` ```
3. Change to directory ```telegram-bot.bash```, run ```./bashbot.sh init``` and follow the instructions. At this stage you are asked for your Bots token given by botfather. 3. Change to directory ```telegram-bot.bash```, run ```./bashbot.sh init``` and follow the instructions. At this stage you are asked for your Bots token given by botfather.
#### $$VERSION$$ v0.60-rc2-2-g7727608 #### $$VERSION$$ v0.60-rc2-3-g4a944d9

72
doc/2_usage.md
View File

@ -36,50 +36,50 @@ To send a broadcast to all of users that ever used the bot run the following com
## Recieve data ## Recieve data
Evertime a Message is recieved, you can read incoming data using the following variables: Evertime a Message is recieved, you can read incoming data using the following variables:
* ```$MESSAGE```: Incoming messages * ```${MESSAGE}```: Current incoming messages
* ```${MESSAGE[ID]}```: ID of incoming message * ```${MESSAGE[ID]}```: ID of current message
* ```$CAPTION```: Captions * ```$CAPTION```: Captions
* ```$REPLYTO```: Original message wich was replied to * ```$REPLYTO```: Original message wich was replied to
* ```$USER```: This array contains the First name, last name, username and user id of the sender of the current message. * ```$USER```: This array contains the First name, last name, username and user id of the sender of the current message.
- ```${USER[ID]}```: User id * ```${USER[ID]}```: User id
- ```${USER[FIRST_NAME]}```: User's first name * ```${USER[FIRST_NAME]}```: User's first name
- ```${USER[LAST_NAME]}```: User's last name * ```${USER[LAST_NAME]}```: User's last name
- ```${USER[USERNAME]}```: Username * ```${USER[USERNAME]}```: Username
* ```$CHAT```: This array contains the First name, last name, username, title and user id of the chat of the current message. * ```$CHAT```: This array contains the First name, last name, username, title and user id of the chat of the current message.
- ```${CHAT[ID]}```: Chat id * ```${CHAT[ID]}```: Chat id
- ```${CHAT[FIRST_NAME]}```: Chat's first name * ```${CHAT[FIRST_NAME]}```: Chat's first name
- ```${CHAT[LAST_NAME]}```: Chat's last name * ```${CHAT[LAST_NAME]}```: Chat's last name
- ```${CHAT[USERNAME]}```: Username * ```${CHAT[USERNAME]}```: Username
- ```${CHAT[TITLE]}```: Title * ```${CHAT[TITLE]}```: Title
- ```${CHAT[TYPE]}```: Type * ```${CHAT[TYPE]}```: Type
- ```${CHAT[ALL_MEMBERS_ARE_ADMINISTRATORS]}```: All members are administrators (true if true) * ```${CHAT[ALL_MEMBERS_ARE_ADMINISTRATORS]}```: All members are administrators (true if true)
* ```$REPLYTO```: This array contains the First name, last name, username and user id of the ORIGINAL sender of the message REPLIED to. * ```$REPLYTO```: This array contains the First name, last name, username and user id of the ORIGINAL sender of the message REPLIED to.
- ```${REPLYTO[ID]}```: ID of message wich was replied to * ```${REPLYTO[ID]}```: ID of message wich was replied to
- ```${REPLYTO[UID]}```: Original user's id * ```${REPLYTO[UID]}```: Original user's id
- ```${REPLYTO[FIRST_NAME]}```: Original user's first name * ```${REPLYTO[FIRST_NAME]}```: Original user's first name
- ```${REPLYTO[LAST_NAME]}```: Original user's' last name * ```${REPLYTO[LAST_NAME]}```: Original user's' last name
- ```${REPLYTO[USERNAME]}```: Original user's username * ```${REPLYTO[USERNAME]}```: Original user's username
* ```$FORWARD```: This array contains the First name, last name, username and user id of the ORIGINAL sender of the FORWARDED message. * ```$FORWARD```: This array contains the First name, last name, username and user id of the ORIGINAL sender of the FORWARDED message.
- ```${FORWARD[ID]}```: Same as MESSAGE[ID] if message is forwarded * ```${FORWARD[ID]}```: Same as MESSAGE[ID] if message is forwarded
- ```${FORWARD[UID]}```: Original user's id * ```${FORWARD[UID]}```: Original user's id
- ```${FORWARD[FIRST_NAME]}```: Original user's first name * ```${FORWARD[FIRST_NAME]}```: Original user's first name
- ```${FORWARD[LAST_NAME]}```: Original user's' last name * ```${FORWARD[LAST_NAME]}```: Original user's' last name
- ```${FORWARD[USERNAME]}```: Original user's username * ```${FORWARD[USERNAME]}```: Original user's username
* ```$URLS```: This array contains documents, audio files, stickers, voice recordings and stickers stored in the form of URLs. * ```$URLS```: This array contains documents, audio files, stickers, voice recordings and stickers stored in the form of URLs.
- ```${URLS[AUDIO]}```: Audio files * ```${URLS[AUDIO]}```: Audio files
- ```${URLS[VIDEO]}```: Videos * ```${URLS[VIDEO]}```: Videos
- ```${URLS[PHOTO]}```: Photos (maximum quality) * ```${URLS[PHOTO]}```: Photos (maximum quality)
- ```${URLS[VOICE]}```: Voice recordings * ```${URLS[VOICE]}```: Voice recordings
- ```${URLS[STICKER]}```: Stickers * ```${URLS[STICKER]}```: Stickers
- ```${URLS[DOCUMENT]}```: Any other file * ```${URLS[DOCUMENT]}```: Any other file
* ```$CONTACT```: This array contains info about contacts sent in a chat. * ```$CONTACT```: This array contains info about contacts sent in a chat.
- ```${CONTACT[NUMBER]}```: Phone number * ```${CONTACT[NUMBER]}```: Phone number
- ```${CONTACT[FIRST_NAME]}```: First name * ```${CONTACT[FIRST_NAME]}```: First name
- ```${CONTACT[LAST_NAME]}```: Last name * ```${CONTACT[LAST_NAME]}```: Last name
- ```${CONTACT[ID]}```: User id * ```${CONTACT[ID]}```: User id
* ```$LOCATION```: This array contains info about locations sent in a chat. * ```$LOCATION```: This array contains info about locations sent in a chat.
- ```${LOCATION[LONGITUDE]}```: Longitude * ```${LOCATION[LONGITUDE]}```: Longitude
- ```${LOCATION[LATITUDE]}```: Latitude * ```${LOCATION[LATITUDE]}```: Latitude
## Usage of bashbot functions ## Usage of bashbot functions
@ -154,6 +154,6 @@ Allowed values: typing for text messages, upload_photo for photos, record_video
send_action "${CHAT[ID]}" "action" send_action "${CHAT[ID]}" "action"
``` ```
#### $$VERSION$$ v0.60-rc2-2-g7727608 #### $$VERSION$$ v0.60-rc2-3-g4a944d9

15
doc/3_advanced.md
View File

@ -1,7 +1,9 @@
## Advanced Features ## Advanced Features
### Access control ### Access control
Bashbot offers functions to check if a has Telegram capabilities like chat admin or chat creator: Bashbot offers functions to check what Telegram capabilities like chat admin or chat creator the given user has:
```bash ```bash
# return true if user is admin/owner of the bot # return true if user is admin/owner of the bot
# -> botadmin is stored in file './botadmin' # -> botadmin is stored in file './botadmin'
@ -19,10 +21,10 @@ user_is_botadmin "${USER[ID]}" && send_markdown_message "${CHAT[ID]}" "You are *
user_is_admin "${CHAT[ID]}" "${USER[ID]}" && send_markdown_message "${CHAT[ID]}" "You are *CHATADMIN*." user_is_admin "${CHAT[ID]}" "${USER[ID]}" && send_markdown_message "${CHAT[ID]}" "You are *CHATADMIN*."
``` ```
In addtion you can configure individual capabilities for users in the file ```./botacl```: In addtion the bot can check individual capabilities of users as defined in the ```./botacl``` file:
```bash ```bash
# botacl # file: botacl
# if a user is not listed here, function 'user_is_allowed' will always return false # a user not listed here, will return false from 'user_is_allowed'
# #
# Format: # Format:
# user:ressource:chat # user:ressource:chat
@ -42,8 +44,7 @@ In addtion you can configure individual capabilities for users in the file ```./
*:start:* *:start:*
*:*:98979695 *:*:98979695
``` ```
you have to check yourself if a user is allowed to to something by calling function ```user_is_allowed```. you have to use the function ```user_is_allowed``` to check if a user has the capability to do something. Example check if user has capability to start bot:
example to check if a user is allowed to start bot:
```bash ```bash
case "$MESSAGE" in case "$MESSAGE" in
'/start') '/start')
@ -153,5 +154,5 @@ To send stickers through an *inline query*:
answer_inline_query "$iQUERY_ID" "cached_sticker" "identifier for the sticker" answer_inline_query "$iQUERY_ID" "cached_sticker" "identifier for the sticker"
``` ```
#### $$VERSION$$ v0.60-rc2-2-g7727608 #### $$VERSION$$ v0.60-rc2-3-g4a944d9

15
doc/4_expert.md
View File

@ -8,7 +8,7 @@ two bytes for encoding and covers almost all ```Latin``` alphabets, also ```Gree
```Hebrew```, ```Arabic``` and more. See [Wikipedia](https://en.wikipedia.org/wiki/UTF-8) for more deatils. ```Hebrew```, ```Arabic``` and more. See [Wikipedia](https://en.wikipedia.org/wiki/UTF-8) for more deatils.
#### Setting up your Environment #### Setting up your Environment
In general ```bash``` and ```GNU``` utitities are UTF-8 aware, but you have to setup your environment In general ```bash``` and ```GNU``` utitities are UTF-8 aware if you to setup your environment
and your scripts accordingly: and your scripts accordingly:
1. Your Terminal and Editor must support UTF-8: 1. Your Terminal and Editor must support UTF-8:
@ -36,15 +36,16 @@ export 'LANGUAGE=den_US.UTF-8'
To display all availible locales on your system run ```locale -a | more```. [Gentoo Wiki](https://wiki.gentoo.org/wiki/UTF-8) To display all availible locales on your system run ```locale -a | more```. [Gentoo Wiki](https://wiki.gentoo.org/wiki/UTF-8)
#### UTF-8 Support #### Bashbot UTF-8 Support
Telegram send JSON messages with all characters not fitting in one byte (<256 bit) escaped as sequences of ```\uxxxx``` to be regular Bashbot handles all messages transparently, regardless what charset is used. One exception is the conversation from JSON data to strings.
one byte ASCII. Multibyte UTF-8 characters, e.g. Emoticons and Arabic characters, are send in UTF-16 notation.
Telegram use JSON to send / recieve data. Characters not ASCII *(>127)* are escaped as sequences of ```\uxxxx``` to be regular ASCII. In addition multibyte characters, *e.g. Emoticons or Arabic characters*, are send in double byte UTF-16 notation.
The Emoticons ``` 😁 😘 ❤️ 😊 👍 ``` are encoded as: ``` \uD83D\uDE01 \uD83D\uDE18 \u2764\uFE0F \uD83D\uDE0A \uD83D\uDC4D ``` The Emoticons ``` 😁 😘 ❤️ 😊 👍 ``` are encoded as: ``` \uD83D\uDE01 \uD83D\uDE18 \u2764\uFE0F \uD83D\uDE0A \uD83D\uDC4D ```
**This mixed JSON encoding can not decoded from** ```echo -e``` or ```printf '%s\\n'```, this works only for single byte characters! **This mixed JSON encoding needs special handling and can not decoded from** ```echo -e``` or ```printf '%s\\n'```
To to fully support decoding of multibyte characters you need a working python2 installation on your system. To to fully support decoding of multibyte characters you need a working python2 installation on your system.
If no python is detected bashbot falls back to a **slow, pure bash solution which may not work for some corner cases**. If no python is detected bashbot falls back to a **internal pure bash implementaion which may not work for some corner cases**.
### Run as other user or system service ### Run as other user or system service
@ -102,5 +103,5 @@ An example crontab is provided in ```bashbot.cron```.
- if you run bashbot as an other user or a system service edit ```bashbot.cron``` to fit your needs and replace username```nobody``` with the username you want to run bashbot. copy the modified file to ```/etc/cron.d/bashbot``` - if you run bashbot as an other user or a system service edit ```bashbot.cron``` to fit your needs and replace username```nobody``` with the username you want to run bashbot. copy the modified file to ```/etc/cron.d/bashbot```
#### $$VERSION$$ v0.60-rc2-2-g7727608 #### $$VERSION$$ v0.60-rc2-3-g4a944d9

30
doc/5_practice.md
View File

@ -1,9 +1,8 @@
## Best Practices ## Best Practices
### Customizing commands.sh ### Customize commands.sh only
To ease Updates never change ```bashbot.sh```, all changes should be done in ```commands.sh``` . To ease Updates never change ```bashbot.sh```, instead individual commands should go to ```commands.sh``` . Insert your Bot commands in the ```case ... esac``` block:
Insert your own Bot commands in the ```case ... esac``` block in commands.sh:
```bash ```bash
case "$MESSAGE" in case "$MESSAGE" in
'/echo') # my first own command, echo MESSAGE '/echo') # my first own command, echo MESSAGE
@ -17,19 +16,17 @@ Insert your own Bot commands in the ```case ... esac``` block in commands.sh:
;; ;;
esac esac
``` ```
after editing commands.sh restart Bot.
### Seperate logic from command block ### Seperate logic from commands
If your Bot command needs more than 2-3 lines of code I recommend to factor it out to a function to keep the command block small. If a command need more than 2-3 lines of code, you should use a function to seperate logic from command. Place your functions in a seperate file, e.g. ```mycommands.inc.sh``` and source it from bashbot.sh. Example:
Place the functions in a file, e.g. ```mybotcommands.inc.sh``` and source it from bashbot.sh.
```process_message``` is an example for a function hiding complex logic in a bash funtcion.
```bash ```bash
source mybotcommands.inc.sh source "mycommands.inc.sh"
case "$MESSAGE" in case "$MESSAGE" in
'/report') # logic for /report is done in process_message '/process') # logic for /report is done in process_message
send_normal_message "${CHAT[ID]}" "$(process_message "$MESSAGE")" result="$(process_message "$MESSAGE")
send_normal_message "${CHAT[ID]}" "$result"
;; ;;
################################################ ################################################
@ -43,15 +40,15 @@ Place the functions in a file, e.g. ```mybotcommands.inc.sh``` and source it fro
;; ;;
esac esac
``` ```
Example function ```process_message``` in file ```mybotcommands.inc.sh```:
```bash ```bash
#!/bin/bash #!/bin/bash
# # file: mycommands.inc.sh
process_message() { process_message() {
local ARGS="${1#/* }" # remove command /* local ARGS="${1#/* }" # remove command
local TEXT OUTPUT="" local TEXT OUTPUT=""
# process every word in MESSAGE, avoid globbing from MESSAGE # process every word in MESSAGE, avoid globbing
set -f set -f
for WORD in $ARGS for WORD in $ARGS
do do
@ -75,7 +72,6 @@ process_message() {
} }
``` ```
Doing it this way keeps commands.sh small and clean, while allowing complex tasks to be done in the included function.
### Test your Bot with shellcheck ### Test your Bot with shellcheck
Shellcheck is a static linter for shell scripts providing excellent tips and hints for shell coding pittfalls. You can [use it online](https://www.shellcheck.net/) or [install it on your system](https://github.com/koalaman/shellcheck#installing). Shellcheck is a static linter for shell scripts providing excellent tips and hints for shell coding pittfalls. You can [use it online](https://www.shellcheck.net/) or [install it on your system](https://github.com/koalaman/shellcheck#installing).
@ -112,5 +108,5 @@ In bashbot.sh line 490:
Here are two warnings in bashbots scripts. The first is a hint you may use shell substitions instead of sed, this is really possible and much faster! Here are two warnings in bashbots scripts. The first is a hint you may use shell substitions instead of sed, this is really possible and much faster!
The second warning is about an unused variable, this is true because in our examples CONTACT is not used but assigned in case you want to use it :-) The second warning is about an unused variable, this is true because in our examples CONTACT is not used but assigned in case you want to use it :-)
#### $$VERSION$$ v0.60-rc2-2-g7727608 #### $$VERSION$$ v0.60-rc2-3-g4a944d9

59
doc/6_reference.md
View File

@ -1,12 +1,15 @@
## Bashbot function reference ## Bashbot function reference
### Send, forward, delete Messages ### Send, forward, delete messages
##### send_action ##### send_action
To send a chat action use the send_action function. Allowed values: ```typing``` for text messages, ```upload_photo``` for photos, ```record_video``` or ```upload_video``` for videos, ```record_audio``` or ```upload_audio``` for audio files, ```upload_document``` for general files, ```find_location``` for locations. ```send_action``` shows users what your bot is currently doing.
*usage:* send_action "${CHAT[ID]}" "action" *usage:* send_action "${CHAT[ID]}" "action"
*"action":* ```typing```, ```upload_photo```, ```record_video```, ```upload_video```, ```record_audio```, ```upload_audio```, ```upload_document```, ```find_location```.
*example:* *example:*
```bash ```bash
send_action "${CHAT[ID]}" "typing" send_action "${CHAT[ID]}" "typing"
@ -15,7 +18,7 @@ send_action "${CHAT[ID]}" "record_audio"
##### send_normal_message ##### send_normal_message
sen_normal_message send text only messages to chat. ```send_normal_message``` sends text only messages to the given chat.
*usage:* send_normal_message "${CHAT[ID]}" "message" *usage:* send_normal_message "${CHAT[ID]}" "message"
@ -26,9 +29,10 @@ send_normal_message "${CHAT[ID]}" "this is a text message"
##### send_markdown_message ##### send_markdown_message
Telegram supports only a [reduced set of Markdown](https://core.telegram.org/bots/api#markdown-style) ```send_markdown_message``` sends markdown style messages to the given chat.
Telegram supports a [reduced set of Markdown](https://core.telegram.org/bots/api#markdown-style) only
*usage:* send_markdown_message "${CHAT[ID]}" "message" *usage:* send_markdown_message "${CHAT[ID]}" "markdown message"
*example:* *example:*
```bash ```bash
@ -37,9 +41,10 @@ send_normal_message "${CHAT[ID]}" "*bold* _italic_ [text](link)"
``` ```
##### send_html_message ##### send_html_message
Telegram supports only a [reduced set of HTML](https://core.telegram.org/bots/api#html-style) ```send_html_message``` sends HTML style messages to the given chat.
Telegram supports a [reduced set of HTML](https://core.telegram.org/bots/api#html-style) only
*usage:* send_html_message "${CHAT[ID]}" "message" *usage:* send_html_message "${CHAT[ID]}" "html message"
*example:* *example:*
```bash ```bash
@ -47,15 +52,19 @@ send_normal_message "${CHAT[ID]}" "this is a markdown message, next word is <b>
send_normal_message "${CHAT[ID]}" "<b>bold</b> <i>italic><i> <em>italic>/em> <a href="link">Text</a>" send_normal_message "${CHAT[ID]}" "<b>bold</b> <i>italic><i> <em>italic>/em> <a href="link">Text</a>"
``` ```
##### forward ##### forward_message
*usage:* forward "${CHAT[ID]}" "${MESSAGE[ID]}" ```forward_mesage``` forwards a messsage to the given chat.
*usage:* forward_message "chat_to" "chat_from" "${MESSAGE[ID]}"
*alias:* forward "${CHAT[ID]}" "$FROMCHAT" "${MESSAGE[ID]}"
---- ----
##### send_message ##### send_message
Send Message must (only) used to process the output of interactive chats and background jobs. ```send_message``` sends any type of message to the given chat. Type of output is steered by keywords within the message.
**For your commands I reccommend the more dedicated send_xxx_message() functions above.**
The main use case for send_message is to process the output of interactive chats and background jobs. **For regular Bot commands I recommend using of the dedicated send_xxx_message() functions from above.**
*usage:* send_message "${CHAT[ID]}" "message" *usage:* send_message "${CHAT[ID]}" "message"
@ -64,7 +73,7 @@ Send Message must (only) used to process the output of interactive chats and bac
---- ----
##### delete_message ##### delete_message
If your Bot is Admin in a Chat you can delete every message, if not you can delete only your Bot messages. If your Bot is admin of a Chat he can delete every message, if not he can delete only his messages.
*usage:* delete_message "${CHAT[ID]}" "${MESSAGE[ID]}" *usage:* delete_message "${CHAT[ID]}" "${MESSAGE[ID]}"
@ -111,7 +120,15 @@ send_file "${CHAT[ID]}" "https://www.domain,com/something.gif" "Something"
---- ----
##### send_keyboard ##### send_keyboard
Note: since version 0.6 send_keyboard was changed to use native "JSON Array" notation as used from Telegram. Eexample Keybord Array definitions: Note: since version 0.6 send_keyboard was changed to use native "JSON Array" notation as used from Telegram. Example Keybord Array definitions:
- yes no in one row
- OLD format: "yes" "no" (two strings)
- NEW format: "[ \\"yes\\" , \\"no\\" ]" (string containing an array)
- new keybord layouts, no possible with old format:
- Yes No in two rows: "[ \\"yes\\" ] , [ \\"no\\" ]"
- numpad style keyboard: "[ \\"1\\" , \\"2\\" , \\"3\\" ] , [ \\"4\\" , \\"5\\" , \\"6\\" ] , [ \\"7\\" , \\"8\\" , \\"9\\" ] , [ \\"0\\" ]"
*usage:* send_keyboard "chat-id" "keyboard" *usage:* send_keyboard "chat-id" "keyboard"
@ -154,7 +171,7 @@ fi
---- ----
##### user_is_creator ##### user_is_creator
Returns true (0) if user is creator of chat or chat is a one2one / private chat. Returns true (0) if user is creator of chat or chat is a private chat.
*usage:* user_is_creator "${CHAT[ID]}" "${USER[ID]}" *usage:* user_is_creator "${CHAT[ID]}" "${USER[ID]}"
@ -203,7 +220,7 @@ fi
### Interactive and backgound jobs ### Interactive and backgound jobs
##### startproc ##### startproc
With ```startproc``` you can start scrips (or C or python program etc.). The text that the script will output will be sent in real time to the user, and all user input will be sent to the script. see [Advanced Usage](3_advanced.md#Interactive-Chats) ```startproc``` tarts a script (or C or python program etc.) running in parallel to your Bot. The text that the script outputs is sent time to the user or chat, user input will be sent back to the script. see [Advanced Usage](3_advanced.md#Interactive-Chats)
*usage:* startproc "./script" *usage:* startproc "./script"
@ -213,7 +230,7 @@ startproc './calc'
``` ```
##### checkproc ##### checkproc
Returns true (0) if an interactive script is running in chat. Returns true (0) if an interactive script active in the given chat.
*usage:* checkprog *usage:* checkprog
@ -243,6 +260,10 @@ fi
---- ----
##### background ##### background
```background``` starts a script / programm as a background job and attaches a jobname to it. All output from a background job is sent to the associated chat.
In contrast to interactive chats, background jobs do not recieve user input and can run forever. In addition you can suspend and restart running jobs, e.g. after reboot.
*usage:* background "./script" "jobname" *usage:* background "./script" "jobname"
*example:* *example:*
@ -251,7 +272,7 @@ background "./notify" "notify"
``` ```
##### checkback ##### checkback
Returns true (0) if an background job is running in chat. Returns true (0) if an background job is active in the given chat.
*usage:* checkback "jobname" *usage:* checkback "jobname"
@ -280,7 +301,7 @@ else
fi fi
``` ```
### Bashbot internal ### Bashbot internal functions
These functions are for internal use only and must not used in your bot commands. These functions are for internal use only and must not used in your bot commands.
##### send_text ##### send_text
@ -325,5 +346,5 @@ The name of your bot is availible as bash variable "$ME", there is no need to ca
##### inproc ##### inproc
Send Input from Telegram to waiting Interactive Chat. Send Input from Telegram to waiting Interactive Chat.
#### $$VERSION$$ v0.60-rc2-2-g7727608 #### $$VERSION$$ v0.60-rc2-3-g4a944d9

2
notify
View File

@ -2,7 +2,7 @@
# This file is public domain in the USA and all free countries. # This file is public domain in the USA and all free countries.
# Elsewhere, consider it to be WTFPLv2. (wtfpl.net/txt/copying) # Elsewhere, consider it to be WTFPLv2. (wtfpl.net/txt/copying)
#### $$VERSION$$ v0.60-rc2-0-gc581932 #### $$VERSION$$ v0.60-rc2-3-g4a944d9
# adjust your language setting here # adjust your language setting here
# https://github.com/topkecleon/telegram-bot-bash#setting-up-your-environment # https://github.com/topkecleon/telegram-bot-bash#setting-up-your-environment

2
question
View File

@ -3,7 +3,7 @@
# This file is public domain in the USA and all free countries. # This file is public domain in the USA and all free countries.
# Elsewhere, consider it to be WTFPLv2. (wtfpl.net/txt/copying) # Elsewhere, consider it to be WTFPLv2. (wtfpl.net/txt/copying)
#### $$VERSION$$ v0.60-rc2-0-gc581932 #### $$VERSION$$ v0.60-rc2-3-g4a944d9
# adjust your language setting here # adjust your language setting here
# https://github.com/topkecleon/telegram-bot-bash#setting-up-your-environment # https://github.com/topkecleon/telegram-bot-bash#setting-up-your-environment

2
version
View File

@ -1,6 +1,6 @@
#!/bin/bash #!/bin/bash
# #
#### $$VERSION$$ v0.60-rc2-0-gc581932 #### $$VERSION$$ v0.60-rc2-3-g4a944d9
# shellcheck disable=SC2016 # shellcheck disable=SC2016
# #
# Easy Versioning in git: # Easy Versioning in git: