From 51df0a9b9295e5e461029aa8b69c33eabe1a573a Mon Sep 17 00:00:00 2001 From: "Kay Marquardt (Gnadelwartz)" Date: Mon, 25 Mar 2019 14:16:03 +0100 Subject: [PATCH 1/3] explain usage of send_xxx_message --- README.md | 117 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 72 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index f0deee7..abdaf15 100644 --- a/README.md +++ b/README.md @@ -86,57 +86,64 @@ git clone --recursive https://github.com/topkecleon/telegram-bot-bash 3. Change to directory ```telegram-bot.bash``` and run ```./bashbot.sh init``` and follow the instructions. -Then start editing the commands.sh. +Then start editing the ```commands.sh``` file. + +## Programming your own Bot + +All Commands for the Bot are at the end the ```commands.sh``` file. Here you ifind some exmples how to process messages and send out text. +The default commands like /info, /start, /help /cancel should't changed. ### Receive data -You can read incoming data using the following variables: +Evertime a Message is recived, you can read incoming data using the following variables: * ```$MESSAGE```: Incoming messages * ```${MESSAGE[ID]}```: ID of incoming 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 +### Usage of bashbot functions + +#### Send_messages To send messages use the ```send_message``` function: ``` send_message "${CHAT[ID]}" "lol" @@ -152,6 +159,25 @@ This function also allows a third parameter that disables additional function pa ``` send_message "${CHAT[ID]}" "lol" "safe" ``` +To forward messages use the ```forward``` function: +``` +forward "${CHAT[ID]}" "from_chat_id" "message_id" +``` +*For safety and performance reasoms I recommend to use send_xxxx_message direct and not the universal send_message function.* +To send regular text without any markdown use: +``` +send_text_message "${CHAT[ID]}" "lol" +``` +To send text with markdown: +``` +send_markdown_message "${CHAT[ID]}" "lol *bold*" +``` +To send text with html: +``` +send_html_message "${CHAT[ID]}" "lol bold +``` + +#### Send files etc. To send images, videos, voice files, photos ecc use the ```send_photo``` function (remember to change the safety Regex @ line 14 of command.sh to allow sending files only from certain directories): ``` send_file "${CHAT[ID]}" "/home/user/doge.jpg" "Lool" @@ -168,10 +194,6 @@ To send venues use the ```send_venue``` function: ``` send_venue "${CHAT[ID]}" "Latitude" "Longitude" "Title" "Address" "optional foursquare id" ``` -To forward messages use the ```forward``` function: -``` -forward "${CHAT[ID]}" "from_chat_id" "message_id" -``` 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. ``` @@ -284,14 +306,18 @@ If some thing doesn't work as it should, debug with ```bash -x bashbot.sh```. To use the functions provided in this script in other scripts simply source bashbot: ```source bashbot.sh``` -## User count +## Managing your Bot + +### Start / Stop + + +### User count To count the total number of users that ever used the bot run the following command: ``` bash bashbot.sh count ``` - -## Sending broadcasts to all users +### Sending broadcasts to all users To send a broadcast to all of users that ever used the bot run the following command: ``` bash bashbot.sh broadcast "Hey! I just wanted to let you know that the bot's been updated!" @@ -326,7 +352,7 @@ export LANGUAGE=den_US.UTF-8 ``` 3. make shure your bot scripts use the correct settings, eg. include the lines above at the beginning of your scripts -To display all availible locales on your system run ```locale -a | more```. +To display all availible locales on your system run ```locale -a | more```. [Gentoo Wiki](https://wiki.gentoo.org/wiki/UTF-8) ### UTF-8 in Telegram and Bash ```UTF-8``` is a variable length encoding of Unicode. UTF-8 is recommended as the default encoding in JSON, XML and HTML, also Telegram make use of it. @@ -341,7 +367,8 @@ E.g. the Emoticons ``` 😁 😘 ❤️ 😊 👍 ``` are encoded as: \uD83D\uDE01 \uD83D\uDE18 \u2764\uFE0F \uD83D\uDE0A \uD83D\uDC4D ``` -'\uXXXX' and '\UXXXXXXXX' escaped endocings are supported by zsh, bash, ksh93, mksh and FreeBSD sh, GNU 'printf' and GNU 'echo -e', see this [excelent Answer](https://unix.stackexchange.com/questions/252286/how-to-convert-an-emoticon-specified-by-a-uxxxxx-code-to-utf-8/252295#252295) for more information. +'\uXXXX' and '\UXXXXXXXX' escaped endocings are supported by zsh, bash, ksh93, mksh and FreeBSD sh, GNU 'printf' and GNU 'echo -e', see [this Stackexchange Answer](https://unix.stackexchange.com/questions/252286/how-to-convert-an-emoticon-specified-by-a-uxxxxx-code-to-utf-8/252295#252295) for more information. + ## That's it! From a4374e1d334cf67561e77ea9f1423b8faf23811a Mon Sep 17 00:00:00 2001 From: "Kay Marquardt (Gnadelwartz)" Date: Mon, 25 Mar 2019 15:12:13 +0100 Subject: [PATCH 2/3] Expert use: Run as system service or from cron --- README.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 54 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index abdaf15..9d61da3 100644 --- a/README.md +++ b/README.md @@ -83,18 +83,18 @@ group. This step is up to you actually. ``` git clone --recursive https://github.com/topkecleon/telegram-bot-bash ``` -3. Change to directory ```telegram-bot.bash``` and run ```./bashbot.sh init``` and follow the instructions. +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. Then start editing the ```commands.sh``` file. ## Programming your own Bot -All Commands for the Bot are at the end the ```commands.sh``` file. Here you ifind some exmples how to process messages and send out text. +All Commands for the Bot are at the end the ```commands.sh``` file. Here you find some examples how to process messages and send out text. The default commands like /info, /start, /help /cancel should't changed. ### Receive data -Evertime a Message is recived, 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[ID]}```: ID of incoming message @@ -143,7 +143,7 @@ Evertime a Message is recived, you can read incoming data using the following va ### Usage of bashbot functions -#### Send_messages +#### send_message To send messages use the ```send_message``` function: ``` send_message "${CHAT[ID]}" "lol" @@ -163,7 +163,8 @@ To forward messages use the ```forward``` function: ``` forward "${CHAT[ID]}" "from_chat_id" "message_id" ``` -*For safety and performance reasoms I recommend to use send_xxxx_message direct and not the universal send_message function.* + +#### For safety and performance reasoms I recommend to use send_xxxx_message direct and not the universal send_message function.* To send regular text without any markdown use: ``` send_text_message "${CHAT[ID]}" "lol" @@ -174,10 +175,17 @@ send_markdown_message "${CHAT[ID]}" "lol *bold*" ``` To send text with html: ``` -send_html_message "${CHAT[ID]}" "lol bold +send_html_message "${CHAT[ID]}" "lol bold" ``` -#### Send files etc. +If your Bot is Admin in a Chat you can delete every message, if not you can delete only messages. + +To delete a message with a known ${MESSAGE[ID]} you can simple use: +``` +delete_message "${CHAT[ID]}" "${MESSAGE[ID]}" +``` + +#### Send files, location etc. To send images, videos, voice files, photos ecc use the ```send_photo``` function (remember to change the safety Regex @ line 14 of command.sh to allow sending files only from certain directories): ``` send_file "${CHAT[ID]}" "/home/user/doge.jpg" "Lool" @@ -307,9 +315,16 @@ To use the functions provided in this script in other scripts simply source bash ## Managing your Bot +####Note: running bashbot as root is highly danger and not recommended. See Expert useage below. ### Start / Stop - +Start or Stop your Bot use the following commands: +``` +bash bashbot.sh start +``` +``` +bash bashbot.sh kill +``` ### User count To count the total number of users that ever used the bot run the following command: @@ -370,6 +385,37 @@ E.g. the Emoticons ``` 😁 😘 ❤️ 😊 👍 ``` are encoded as: '\uXXXX' and '\UXXXXXXXX' escaped endocings are supported by zsh, bash, ksh93, mksh and FreeBSD sh, GNU 'printf' and GNU 'echo -e', see [this Stackexchange Answer](https://unix.stackexchange.com/questions/252286/how-to-convert-an-emoticon-specified-by-a-uxxxxx-code-to-utf-8/252295#252295) for more information. +## Expert Usage +Bashbot is desingned to run manually by the user who installed it. Nevertheless it's possible to run it e.g. by an other user-ID, as a system service or sceduled from cron. This is onyl recommended for an experiend linux user. + +### Run as other user or system service +Running bashbot as an other user is only possible (and strongly recommended) for root. + +Edit the example rc file ```bashbot.rc``` and set the value ```runas``` to the user you want to run bashbot. Uncomment the ```runcmd``` availible on your system and fill the name of your Bot in ```name```. Now you can start ans stop your bot by bashbot.rc + +To start your bot use: +``` +./bashbot.rc start +``` +Now type ```ps -ef | grep bashbot``` to verify your Bot is running as the desired user. + +If you use bashbot.rc to start your Bot as an other user your must use bashbot.rc to manage your Bot! The following commands are availible: +``` +./bashbot.rc start +./bashbot.rc stop +./bashbot.rc status +./bashbot.rc suspendback +./bashbot.rc resumeback +./bashbot.rc killback +`` +To use bashbot as a system servive include your working ```bashbot.rc``` in your init system (systemd, /etc/init.d). + +### Scedule bashbot from Cron +An example crontab is provided in ```bashbot.cron```. + +- If you are running bashbot with your local user-ID, copy the examples to your crontab and remove username ```www```. +- if you run crontab as an other user or a system service edit ```bashbot.cron``` to fit your needs and replace username````www``` with the username you want to run bashbot. copy the modified file to /etc/cron.d + ## That's it! If you feel that there's something missing or if you found a bug, feel free to submit a pull request! From df930b77820ff385424bdd7c0fe24b26f0fe9178 Mon Sep 17 00:00:00 2001 From: "Kay Marquardt (Gnadelwartz)" Date: Mon, 25 Mar 2019 15:22:28 +0100 Subject: [PATCH 3/3] fix typo's in readme --- README.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 9d61da3..cb84c3d 100644 --- a/README.md +++ b/README.md @@ -164,7 +164,7 @@ To forward messages use the ```forward``` function: forward "${CHAT[ID]}" "from_chat_id" "message_id" ``` -#### For safety and performance reasoms I recommend to use send_xxxx_message direct and not the universal send_message function.* +#### For safety and performance reasoms I recommend to use send_xxxx_message direct and not the universal send_message function. To send regular text without any markdown use: ``` send_text_message "${CHAT[ID]}" "lol" @@ -178,15 +178,14 @@ To send text with html: send_html_message "${CHAT[ID]}" "lol bold" ``` -If your Bot is Admin in a Chat you can delete every message, if not you can delete only messages. - +If your Bot is Admin in a Chat you can delete every message, if not you can delete only your messages. To delete a message with a known ${MESSAGE[ID]} you can simple use: ``` delete_message "${CHAT[ID]}" "${MESSAGE[ID]}" ``` #### Send files, location etc. -To send images, videos, voice files, photos ecc use the ```send_photo``` function (remember to change the safety Regex @ line 14 of command.sh to allow sending files only from certain directories): +To send images, videos, voice files, photos etc. use the ```send_photo``` function (remember to change the safety Regex @ line 14 of command.sh to allow sending files only from certain directories): ``` send_file "${CHAT[ID]}" "/home/user/doge.jpg" "Lool" ``` @@ -260,6 +259,7 @@ If you want to kill all background jobs permantly run: ./bashbot.sh killback ``` +Note: If your run bashbot as an other user or system service, see Expert use. #### Inline queries The following commands allows users to interact with your bot via *inline queries*. @@ -315,7 +315,7 @@ To use the functions provided in this script in other scripts simply source bash ## Managing your Bot -####Note: running bashbot as root is highly danger and not recommended. See Expert useage below. +#### Note: running bashbot as root is highly danger and not recommended. See Expert usage below. ### Start / Stop Start or Stop your Bot use the following commands: @@ -386,7 +386,7 @@ E.g. the Emoticons ``` 😁 😘 ❤️ 😊 👍 ``` are encoded as: ## Expert Usage -Bashbot is desingned to run manually by the user who installed it. Nevertheless it's possible to run it e.g. by an other user-ID, as a system service or sceduled from cron. This is onyl recommended for an experiend linux user. +Bashbot is desingned to run manually by the user who installed it. Nevertheless it's possible to run it e.g. by an other user-ID, as a system service or sceduled from cron. This is onyl recommended for experiend linux users. ### Run as other user or system service Running bashbot as an other user is only possible (and strongly recommended) for root. @@ -397,9 +397,9 @@ To start your bot use: ``` ./bashbot.rc start ``` -Now type ```ps -ef | grep bashbot``` to verify your Bot is running as the desired user. +Type ```ps -ef | grep bashbot``` to verify your Bot is running as the desired user. -If you use bashbot.rc to start your Bot as an other user your must use bashbot.rc to manage your Bot! The following commands are availible: +If you started bashbot by bashbot.rc you must use bashbot.rc also to manage your Bot! The following commands are availible: ``` ./bashbot.rc start ./bashbot.rc stop @@ -407,14 +407,14 @@ If you use bashbot.rc to start your Bot as an other user your must use bashbot. ./bashbot.rc suspendback ./bashbot.rc resumeback ./bashbot.rc killback -`` +``` To use bashbot as a system servive include your working ```bashbot.rc``` in your init system (systemd, /etc/init.d). ### Scedule bashbot from Cron An example crontab is provided in ```bashbot.cron```. - If you are running bashbot with your local user-ID, copy the examples to your crontab and remove username ```www```. -- if you run crontab as an other user or a system service edit ```bashbot.cron``` to fit your needs and replace username````www``` with the username you want to run bashbot. copy the modified file to /etc/cron.d +- if you run bashbot as an other user or a system service edit ```bashbot.cron``` to fit your needs and replace username````www``` with the username you want to run bashbot. copy the modified file to /etc/cron.d ## That's it!