octoleo
/
telegram-bot-bash
mirror of https://github.com/octoleo/telegram-bot-bash.git
1
1
Fork 0
Code Issues Projects Releases Wiki Activity

finalize features and descriptions

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.
## 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
* [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.
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 is incompatible change for keyboards used in older bashbot versions**
**This is an incompatible change for keyboards used in older bashbot versions.**
*Example Keyboards*:
- yes no in one row
- 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:
- Yes No in two rows: "[ \\"yes\\" ] , [ \\"no\\" ]"
- 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)
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
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.
Every file your Bot can read is in danger of being disclosed for the same reason.
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. See Expert use on how to run your Bot as an other user.
### 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?
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!
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.
* your $HOME directory (install and run with your user-ID)
* /usr/local if you want to run as service
1. Clone the repository:
2. Clone the repository:
+
....
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
given by botfather.
@ -41,54 +39,58 @@ Update bashbot
~~~~~~~~~~~~~~
https://github.com/topkecleon/telegram-bot-bash/releases[Download latest
update zip from github] and copy all files to bashbot dir. run
`sudo ./bashbot.sh init`.
update zip from github], 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
~~~~~~~~~~~~~~~
* link:doc/1_firstbot.md[Create your first telegram bot]
* link:doc/2_usage.md[Make your own Bot]
* Managing your own Bot
* Recieve data
* Send Messages
* Send files, location etc.
* link:doc/1_firstbot.md[Create Telegram Bot with botfather]
* link:doc/2_usage.md[Getting Started]
** Managing your Bot
** Recieve data
** Send Messages
** Send files, location etc.
* link:doc/3_advanced.md[Advanced Features]
* Access Control
* Interactive Chats
* Background Jobs
* Inline queries
** Access Control
** Interactive Chats
** Background Jobs
** Inline queries
* link:doc/4_expert.md[Expert Use]
* Handling UTF-8
* Run as other user or system service
* Scedule bashbot from Cron
** Handling UTF-8
** Run as other user or system service
** Scedule bashbot from Cron
* link:doc/5_practice.md[Best Practices]
* Customizing commands.sh
* Seperate Bot logic from command
* Test your Bot with shellcheck
** Customizing commands.sh
** Seperate Bot logic from command
** Test your Bot with shellcheck
* link:doc/6_reference.md[Bashbot functions reference]
Note on Keyboards
~~~~~~~~~~~~~~~~~
To make use of Keyboards easyer we changed the format of `send_keyboard`
and `send_message "mykeyboardstartshere ..."`. Now you must provide the
keyboards in Telegram JSON Array style "[ "yes" , "no" ]". The advantage
is that you can create every type of keyboard without relying on bashbot
`send_keyboard` functionality. *This is incompatible with keyboards in
bashbot versions older than 0.6!*
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\" ]". This
has the advantage that you can create any type of keyboard supported by
Telegram. *This is an incompatible change for keyboards used in older
bashbot versions.*
_Example Keyboards_:
* Yes No in one row: "[ "yes" , "no" ]"
* Yes No ind two rows: "[ "yes" ] , [ "no" ]"
* numpad keyboard: "[ "1" , "2" , "3" ] , [ "4" , "5" , "6" ] , [ "7" ,
"8" , "9" ] , [ "0" ]"
* 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\" ]"
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.
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
of wrong quoting]
Whenever you are processing input from outside your bot you should
disable globbing (set -f) and carefully 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.
To improve you scripts we recommend to lint them with
https://www.shellcheck.net/[shellcheck]. This can be done online or you
can https://github.com/koalaman/shellcheck#installing[install shellcheck
locally]. bashbot itself is also linted by shellcheck.
A powerful tool to improve your scripts robustness is `shellcheck`. You
can https://www.shellcheck.net/[use it online] or
https://github.com/koalaman/shellcheck#installing[install shellcheck
locally]. All bashbot scripts are checked by shellcheck.
Run your Bot as a restricted user
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Every file your bot can write is in danger to be overwritten/deleted, In
case of bad handling of user input every file your Bot can read is in
danger of being disclosed.
*It's important to run your bot as a user, with almost no access
rights.*
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.
See Expert use on how to run your Bot as an other user.
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
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
other files should be write protected.
Bot must be restricted to have write access to `count` and
`tmp-bot-bash` only, all other files should be write protected.
Runing `./bashbot.sh init` sets the Bot permissions to reasonable
default values as a starting point.
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?
^^^^^^^^^^^^^^^^^^^^^
No - its not less (in)secure as any other Bot written in any other
language. But 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!
~~~~~~~~~~
@ -140,5 +153,5 @@ That's it!
If you feel that there's something missing or if you found a bug, feel
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.
# 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

2
bashbot.rc
View File

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

8
bashbot.sh
View File

@ -10,7 +10,7 @@
# This file is public domain in the USA and all free countries.
# Elsewhere, consider it to be WTFPLv2. (wtfpl.net/txt/copying)
#
#### $$VERSION$$ v0.60-rc2-0-gc581932
#### $$VERSION$$ v0.60-rc2-3-g4a944d9
#
# Exit Codes:
# - 0 sucess (hopefully)
@ -439,11 +439,13 @@ send_venue() {
}
forward() {
forward_message() {
[ "$3" = "" ] && return
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() {
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.
# 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
# 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
echo -n 'Result: '
case $opt in
'add'* | 'Add'* ) expr $A + $B ;;
'sub'* | 'Sub'* ) expr $A - $B ;;
'mul'* | 'Mul'* ) expr $A \* $B ;;
'div'* | 'Div'* ) expr $A / $B ;;
'can'* | 'Can'* ) echo "abort!" ;;
'add'* | 'Add'* ) res="$(( A + B ))" ;;
'sub'* | 'Sub'* ) res="$(( A - B ))" ;;
'mul'* | 'Mul'* ) res="$(( A * B ))" ;;
'div'* | 'Div'* ) res="$(( A / B ))" ;;
'can'* | 'Can'* ) res="abort!" ;;
* ) echo "unknown operator!";;
esac
echo "$res"
echo "Bye .."

2
commands.sh
View File

@ -4,7 +4,7 @@
# This file is public domain in the USA and all free countries.
# 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=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.
#### $$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
Evertime a Message is recieved, you can read incoming data using the following variables:
* ```$MESSAGE```: Incoming messages
* ```${MESSAGE[ID]}```: ID of incoming message
* ```${MESSAGE}```: Current incoming messages
* ```${MESSAGE[ID]}```: ID of current message
* ```$CAPTION```: Captions
* ```$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[ID]}```: User id
- ```${USER[FIRST_NAME]}```: User's first name
- ```${USER[LAST_NAME]}```: User's last name
- ```${USER[USERNAME]}```: Username
* ```${USER[ID]}```: User id
* ```${USER[FIRST_NAME]}```: User's first name
* ```${USER[LAST_NAME]}```: User's last name
* ```${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[ID]}```: Chat id
- ```${CHAT[FIRST_NAME]}```: Chat's first name
- ```${CHAT[LAST_NAME]}```: Chat's last name
- ```${CHAT[USERNAME]}```: Username
- ```${CHAT[TITLE]}```: Title
- ```${CHAT[TYPE]}```: Type
- ```${CHAT[ALL_MEMBERS_ARE_ADMINISTRATORS]}```: All members are administrators (true if true)
* ```${CHAT[ID]}```: Chat id
* ```${CHAT[FIRST_NAME]}```: Chat's first name
* ```${CHAT[LAST_NAME]}```: Chat's last name
* ```${CHAT[USERNAME]}```: Username
* ```${CHAT[TITLE]}```: Title
* ```${CHAT[TYPE]}```: Type
* ```${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[ID]}```: ID of message wich was replied to
- ```${REPLYTO[UID]}```: Original user's id
- ```${REPLYTO[FIRST_NAME]}```: Original user's first name
- ```${REPLYTO[LAST_NAME]}```: Original user's' last name
- ```${REPLYTO[USERNAME]}```: Original user's username
* ```${REPLYTO[ID]}```: ID of message wich was replied to
* ```${REPLYTO[UID]}```: Original user's id
* ```${REPLYTO[FIRST_NAME]}```: Original user's first name
* ```${REPLYTO[LAST_NAME]}```: Original user's' last name
* ```${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[ID]}```: Same as MESSAGE[ID] if message is forwarded
- ```${FORWARD[UID]}```: Original user's id
- ```${FORWARD[FIRST_NAME]}```: Original user's first name
- ```${FORWARD[LAST_NAME]}```: Original user's' last name
- ```${FORWARD[USERNAME]}```: Original user's username
* ```${FORWARD[ID]}```: Same as MESSAGE[ID] if message is forwarded
* ```${FORWARD[UID]}```: Original user's id
* ```${FORWARD[FIRST_NAME]}```: Original user's first name
* ```${FORWARD[LAST_NAME]}```: Original user's' last name
* ```${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[AUDIO]}```: Audio files
- ```${URLS[VIDEO]}```: Videos
- ```${URLS[PHOTO]}```: Photos (maximum quality)
- ```${URLS[VOICE]}```: Voice recordings
- ```${URLS[STICKER]}```: Stickers
- ```${URLS[DOCUMENT]}```: Any other file
* ```${URLS[AUDIO]}```: Audio files
* ```${URLS[VIDEO]}```: Videos
* ```${URLS[PHOTO]}```: Photos (maximum quality)
* ```${URLS[VOICE]}```: Voice recordings
* ```${URLS[STICKER]}```: Stickers
* ```${URLS[DOCUMENT]}```: Any other file
* ```$CONTACT```: This array contains info about contacts sent in a chat.
- ```${CONTACT[NUMBER]}```: Phone number
- ```${CONTACT[FIRST_NAME]}```: First name
- ```${CONTACT[LAST_NAME]}```: Last name
- ```${CONTACT[ID]}```: User id
* ```${CONTACT[NUMBER]}```: Phone number
* ```${CONTACT[FIRST_NAME]}```: First name
* ```${CONTACT[LAST_NAME]}```: Last name
* ```${CONTACT[ID]}```: User id
* ```$LOCATION```: This array contains info about locations sent in a chat.
- ```${LOCATION[LONGITUDE]}```: Longitude
- ```${LOCATION[LATITUDE]}```: Latitude
* ```${LOCATION[LONGITUDE]}```: Longitude
* ```${LOCATION[LATITUDE]}```: Latitude
## 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"
```
#### $$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
### 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
# return true if user is admin/owner of the bot
# -> 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*."
```
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
# botacl
# if a user is not listed here, function 'user_is_allowed' will always return false
# file: botacl
# a user not listed here, will return false from 'user_is_allowed'
#
# Format:
# user:ressource:chat
@ -42,8 +44,7 @@ In addtion you can configure individual capabilities for users in the file ```./
*:start:*
*:*:98979695
```
you have to check yourself if a user is allowed to to something by calling function ```user_is_allowed```.
example to check if a user is allowed to start bot:
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:
```bash
case "$MESSAGE" in
'/start')
@ -153,5 +154,5 @@ To send stickers through an *inline query*:
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.
#### 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:
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)
#### 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
one byte ASCII. Multibyte UTF-8 characters, e.g. Emoticons and Arabic characters, are send in UTF-16 notation.
#### Bashbot UTF-8 Support
Bashbot handles all messages transparently, regardless what charset is used. One exception is the conversation from JSON data to strings.
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 ```
**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.
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
@ -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```
#### $$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
### Customizing commands.sh
### Customize commands.sh only
To ease Updates never change ```bashbot.sh```, all changes should be done in ```commands.sh``` .
Insert your own Bot commands in the ```case ... esac``` block 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:
```bash
case "$MESSAGE" in
'/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
```
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.
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.
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:
```bash
source mybotcommands.inc.sh
source "mycommands.inc.sh"
case "$MESSAGE" in
'/report') # logic for /report is done in process_message
send_normal_message "${CHAT[ID]}" "$(process_message "$MESSAGE")"
'/process') # logic for /report is done in process_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
```
Example function ```process_message``` in file ```mybotcommands.inc.sh```:
```bash
#!/bin/bash
#
# file: mycommands.inc.sh
process_message() {
local ARGS="${1#/* }" # remove command /*
local ARGS="${1#/* }" # remove command
local TEXT OUTPUT=""
# process every word in MESSAGE, avoid globbing from MESSAGE
# process every word in MESSAGE, avoid globbing
set -f
for WORD in $ARGS
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
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!
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
### Send, forward, delete Messages
### Send, forward, delete messages
##### 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"
*"action":* ```typing```, ```upload_photo```, ```record_video```, ```upload_video```, ```record_audio```, ```upload_audio```, ```upload_document```, ```find_location```.
*example:*
```bash
send_action "${CHAT[ID]}" "typing"
@ -15,7 +18,7 @@ send_action "${CHAT[ID]}" "record_audio"
##### 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"
@ -26,9 +29,10 @@ send_normal_message "${CHAT[ID]}" "this is a text 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:*
```bash
@ -37,9 +41,10 @@ send_normal_message "${CHAT[ID]}" "*bold* _italic_ [text](link)"
```
##### 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:*
```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>"
```
##### forward
*usage:* forward "${CHAT[ID]}" "${MESSAGE[ID]}"
##### forward_message
```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 must (only) used to process the output of interactive chats and background jobs.
**For your commands I reccommend the more dedicated send_xxx_message() functions above.**
```send_message``` sends any type of message to the given chat. Type of output is steered by keywords within the message.
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"
@ -64,7 +73,7 @@ Send Message must (only) used to process the output of interactive chats and bac
----
##### 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]}"
@ -111,7 +120,15 @@ send_file "${CHAT[ID]}" "https://www.domain,com/something.gif" "Something"
----
##### 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"
@ -154,7 +171,7 @@ fi
----
##### 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]}"
@ -203,7 +220,7 @@ fi
### Interactive and backgound jobs
##### 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"
@ -213,7 +230,7 @@ startproc './calc'
```
##### 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
@ -243,6 +260,10 @@ fi
----
##### 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"
*example:*
@ -251,7 +272,7 @@ background "./notify" "notify"
```
##### 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"
@ -280,7 +301,7 @@ else
fi
```
### Bashbot internal
### Bashbot internal functions
These functions are for internal use only and must not used in your bot commands.
##### send_text
@ -325,5 +346,5 @@ The name of your bot is availible as bash variable "$ME", there is no need to ca
##### inproc
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.
# 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
# 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.
# 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
# https://github.com/topkecleon/telegram-bot-bash#setting-up-your-environment

2
version
View File

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