diff --git a/README.md b/README.md index 9f01fa8..18b4cb4 100644 --- a/README.md +++ b/README.md @@ -92,4 +92,4 @@ No - its not less (in)secure as any other Bot written in any other language. But If you feel that there's something missing or if you found a bug, feel free to submit a pull request! -#### $$VERSION$$ v0.6-rc1-11-gba80ec6 +#### $$VERSION$$ v0.60-rc2-0-gc581932 diff --git a/README.txt b/README.txt index 6e04c34..9f84eef 100644 --- a/README.txt +++ b/README.txt @@ -66,6 +66,24 @@ Getting started * 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!* + +_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" ]" Security Considerations ~~~~~~~~~~~~~~~~~~~~~~~ @@ -122,5 +140,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.6-rc1-7-g14eb352 -+++++++++++++++++++++++++++++++++++++++++++ +latexmath:[\[VERSION\]] v0.60-rc2-0-gc581932 +++++++++++++++++++++++++++++++++++++++++++++ diff --git a/bashbot.cron b/bashbot.cron index fc0d5c2..e6057f7 100644 --- a/bashbot.cron +++ b/bashbot.cron @@ -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.6-rc1-7-g14eb352 +#### $$VERSION$$ v0.60-rc2-0-gc581932 SHELL=/bin/sh diff --git a/bashbot.rc b/bashbot.rc index d5e46cd..ba5d15f 100755 --- a/bashbot.rc +++ b/bashbot.rc @@ -1,7 +1,7 @@ #!/bin/sh # description: Start or stop telegram-bash-bot # -#### $$VERSION$$ v0.6-rc1-7-g14eb352 +#### $$VERSION$$ v0.60-rc2-0-gc581932 # shellcheck disable=SC2009 # shellcheck disable=SC2181 diff --git a/bashbot.sh b/bashbot.sh index 8ed4759..8a20945 100755 --- a/bashbot.sh +++ b/bashbot.sh @@ -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.6-rc1-7-g14eb352 +#### $$VERSION$$ v0.60-rc2-0-gc581932 # # Exit Codes: # - 0 sucess (hopefully) diff --git a/calc b/calc index dc626f5..0cada5f 100755 --- a/calc +++ b/calc @@ -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-dev3-7-gf5538ef +#### $$VERSION$$ v0.60-rc2-0-gc581932 # adjust your language setting here # https://github.com/topkecleon/telegram-bot-bash#setting-up-your-environment diff --git a/commands.sh b/commands.sh index 924bea2..f934796 100755 --- a/commands.sh +++ b/commands.sh @@ -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.6-rc1-7-g14eb352 +#### $$VERSION$$ v0.60-rc2-0-gc581932 # # shellcheck disable=SC2154 # shellcheck disable=SC2034 @@ -156,7 +156,7 @@ else if [ "$res" -eq 0 ] ; then killproc && send_message "${CHAT[ID]}" "Command canceled.";else send_message "${CHAT[ID]}" "No command is currently running.";fi ;; *) # forward input to interactive chat if running - if tmux ls | grep -v send | grep -q $copname;then inproc; fi + if tmux ls | grep -v send | grep -q "$copname"; then inproc; fi ;; esac fi diff --git a/doc/1_firstbot.md b/doc/1_firstbot.md index 5ebb490..de5cd35 100644 --- a/doc/1_firstbot.md +++ b/doc/1_firstbot.md @@ -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.6-rc1-11-gba80ec6 +#### $$VERSION$$ v0.60-rc2-0-gc581932 diff --git a/doc/2_usage.md b/doc/2_usage.md index 3415480..607a499 100644 --- a/doc/2_usage.md +++ b/doc/2_usage.md @@ -154,6 +154,6 @@ Allowed values: typing for text messages, upload_photo for photos, record_video send_action "${CHAT[ID]}" "action" ``` -#### $$VERSION$$ v0.6-rc1-11-gba80ec6 +#### $$VERSION$$ v0.60-rc2-0-gc581932 diff --git a/doc/3_advanced.md b/doc/3_advanced.md index 59be5fe..7750a94 100644 --- a/doc/3_advanced.md +++ b/doc/3_advanced.md @@ -153,5 +153,5 @@ To send stickers through an *inline query*: answer_inline_query "$iQUERY_ID" "cached_sticker" "identifier for the sticker" ``` -#### $$VERSION$$ v0.6-rc1-11-gba80ec6 +#### $$VERSION$$ v0.60-rc2-0-gc581932 diff --git a/doc/4_expert.md b/doc/4_expert.md index b9f32e2..f4cbac3 100644 --- a/doc/4_expert.md +++ b/doc/4_expert.md @@ -102,5 +102,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.6-rc1-11-gba80ec6 +#### $$VERSION$$ v0.60-rc2-0-gc581932 diff --git a/doc/5_practice.md b/doc/5_practice.md index 6bdc2f9..e3f5ad4 100644 --- a/doc/5_practice.md +++ b/doc/5_practice.md @@ -112,5 +112,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.6-rc1-11-gba80ec6 +#### $$VERSION$$ v0.60-rc2-0-gc581932 diff --git a/doc/6_reference.md b/doc/6_reference.md index 5478828..11cf58c 100644 --- a/doc/6_reference.md +++ b/doc/6_reference.md @@ -1,4 +1,4 @@ -## Bashbot functions reference +## Bashbot function reference ### Send, forward, delete Messages @@ -15,24 +15,41 @@ send_action "${CHAT[ID]}" "record_audio" ##### send_normal_message -*usage:* +sen_normal_message send text only messages to chat. + +*usage:* send_normal_message "${CHAT[ID]}" "message" *example:* +```bash +send_normal_message "${CHAT[ID]}" "this is a text message" +``` + ##### send_markdown_message -*usage:* +Telegram supports onyl a [reduced set of Markdown](https://core.telegram.org/bots/api#markdown-style) + +*usage:* send_markdown_message "${CHAT[ID]}" "message" *example:* +```bash +send_normal_message "${CHAT[ID]}" "this is a markdown message, next word is *bold*" +send_normal_message "${CHAT[ID]}" "*bold* _italic_ [text](link)" +``` ##### send_html_message -*usage:* +Telegram supports onyl a [reduced set of HTML](https://core.telegram.org/bots/api#html-style) + +*usage:* send_html_message "${CHAT[ID]}" "message" *example:* +```bash +send_normal_message "${CHAT[ID]}" "this is a markdown message, next word is bold" +send_normal_message "${CHAT[ID]}" "bold italic> italic>/em> Text" +``` ##### forward -*usage:* +*usage:* forward "${CHAT[ID]}" "${MESSAGE[ID]}" -*example:* ---- @@ -40,23 +57,26 @@ send_action "${CHAT[ID]}" "record_audio" 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.** -*usage:* +*usage:* send_message "${CHAT[ID]}" "message" *example:* - see [Usage](2_usage.md#send_message) and [Advanced Usage](3_advanced.md#Interactive-Chats) ---- ##### delete_message -*usage:* +If your Bot is Admin in a Chat you can delete every message, if not you can delete only your Bot messages. -*example:* +*usage:* delete_message "${CHAT[ID]}" "${MESSAGE[ID]}" ---- ##### answer_inline_query -*usage:* +Inline Queries allows users to interact with your bot via directly without sending extra commands. +answer_inline_query provide the result to a users Inline Query -*example:* +*usage:* answer_inline_query "$iQUERY_ID" "type" "type arg 1" ... "type arg n" + +*example:* - see [Advanced Usage](3_advanced.md#Inline-queries) ---- @@ -66,21 +86,27 @@ Send Message must (only) used to process the output of interactive chats and bac *usage:* *example:* +```bash +``` ##### send_file -*usage:* +There are some ways to send files (photos, stickers, audio, media, etc.), [see more](https://core.telegram.org/bots/api#sending-files) + +*usage:* send_file "${CHAT[ID]}" "file" "caption" *example:* +```bash +send_file "${CHAT[ID]}" "/home/user/doge.jpg" "Lool" +send_file "${CHAT[ID]}" "https://www.domain,com/something.gif" "Something" +``` ##### send_location -*usage:* +*usage:* send_location "${CHAT[ID]}" "Latitude" "Longitude" -*example:* ##### send_venue -*usage:* +*usage:* send_venue "${CHAT[ID]}" "Latitude" "Longitude" "Title" "Address" "foursquare id (optional)" -*example:* ---- @@ -99,102 +125,188 @@ send_keyboard "${CHAT[ID]}" "[ \"1\" , \"2\" , \"3\" ] , [ \"4\" , \"5\" , \"6\" ##### remove_keyboard *usage:* -*example:* ### Manage users ##### kick_chat_member -*usage:* +If Bot is Admin you can kick and ban a user. + +*usage:* kick_chat_member "${CHAT[ID]}" "${USER[ID]}" -*example:* ##### unban_chat_member -*usage:* +If Bot is Admin you can unban a kicked user. -*example:* +*usage:* unban_chat_member "${CHAT[ID]}" "${USER[ID]}" ##### leave_chat -*usage:* +Bot will leave chat. -*example:* +*usage:* leave_chat "${CHAT[ID]}" + +```bash +if _is_admin ; then + send_markdown_message "${CHAT[ID]}" "*LEAVING CHAT...*" + leave_chat "${CHAT[ID]}" +fi +``` ---- ##### user_is_creator -*usage:* +Returns true (0) if user is creator of chat or chat is a one2one / private chat. -*example:* +*usage:* user_is_creator "${CHAT[ID]}" "${USER[ID]}" + +*alias:* _is_creator ##### user_is_admin -*usage:* +Returns true (0) if user is admin or creator of chat. + +*usage:* user_is_admin "${CHAT[ID]}" "${USER[ID]}" + +*alias:* _is_creator *example:* +```bash +if _is_admin ; then + send_markdown_message "${CHAT[ID]}" "*LEAVING CHAT...*" + leave_chat "${CHAT[ID]}" +fi +``` ##### user_is_botadmin -*usage:* +Returns true (0) if user is owner / admin of bot. +botadmin is stored in file './botadmin' + +*usage:* user_is_botadmin "${CHAT[ID]}" "${USER[ID]}" + +*alias:* _is_botadmin *example:* +```bash + _is_botadmin && send_markdown_message "${CHAT[ID]}" "You are *BOTADMIN*." +``` ##### user_is_allowed -*usage:* +Bahsbot supports User Access Control, see [Advanced Usage](4_advanced.ma) + +*usage:* user_is_allowed "${USER[ID]}" "what" "${CHAT[ID]}" *example:* +```bash +if ! user_is_allowed "${USER[ID]}" "start" "${CHAT[ID]}" ; then + send_normal_message "${CHAT[ID]}" "You are not allowed to start Bot." +fi +``` ### Interactive and backgound jobs ##### startproc -*usage:* +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) + +*usage:* startproc "./script" *example:* +```bash +startproc './calc' +``` ##### checkproc -*usage:* +Returns true (0) if an interactive script is running in chat. + +*usage:* checkprog *example:* +```bash +checkproc +if [ "$res" -gt 0 ] ; then + startproc "./calc" +else + send_normal_message "${CHAT[ID]}" "Calc already running ..." +fi +``` ##### killproc -*usage:* +*usage:* killproc *example:* +```bash +checkprog +if [ "$res" -eq 0 ]; then + killproc && send_message "${CHAT[ID]}" "Command canceled." +else + send_message "${CHAT[ID]}" "Command is not running." +fi +``` ---- ##### background -*usage:* +*usage:* background "./script" "jobname" *example:* +```bash +background "./notify" "notify" +``` ##### checkback -*usage:* +Returns true (0) if an background job is running in chat. + +*usage:* checkback "jobname" *example:* +```bash +checkback "notify" +if [ "$res" -gt 0 ] ; then + send_normal_message "${CHAT[ID]}" "Start notify" + background "./notify" "notify" +else + send_normal_message "${CHAT[ID]}" "Process notify already running." +fi +``` ##### killback -*usage:* +*usage:* killback "jobname" *example:* +```bash +checkback "notify" +if [ "$res" -eq 0 ] ; then + send_normal_message "${CHAT[ID]}" "Kill notify" + killback "notify" +else + send_normal_message "${CHAT[ID]}" "Process notify not run." +fi +``` ### Bashbot internal These functions are for internal use only and must not used in your bot commands. ##### send_text -*usage:* +*usage:* send_text "${CHAT[ID]}" "message" ---- ##### JsonDecode -*usage:* +Outputs decoded string to STDOUT + +*usage:* JsonDecode "string" ##### JsonGetString -*usage:* +Reads JSON fro STDIN and Outputs found String to STDOUT + +*usage:* JsonGetString `"path","to","string"` ##### JsonGetValue -*usage:* +Reads JSON fro STDIN and Outputs found Value to STDOUT + +*usage:* JsonGetValue `"path","to","value"` ---- ##### get_chat_member_status -*usage:* +*usage:* get_chat_member_status "${CHAT[ID]}" "${USER[ID]}" ---- @@ -213,5 +325,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.6-rc1-11-gba80ec6 +#### $$VERSION$$ v0.60-rc2-0-gc581932 diff --git a/notify b/notify index 0a38bdd..72056f2 100755 --- a/notify +++ b/notify @@ -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.6-rc1-7-g14eb352 +#### $$VERSION$$ v0.60-rc2-0-gc581932 # adjust your language setting here # https://github.com/topkecleon/telegram-bot-bash#setting-up-your-environment diff --git a/question b/question index 4050fd5..8f173e5 100755 --- a/question +++ b/question @@ -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.6-rc1-7-g14eb352 +#### $$VERSION$$ v0.60-rc2-0-gc581932 # adjust your language setting here # https://github.com/topkecleon/telegram-bot-bash#setting-up-your-environment diff --git a/version b/version index 367cf74..311b780 100755 --- a/version +++ b/version @@ -1,6 +1,6 @@ #!/bin/bash # -#### $$VERSION$$ v0.6-rc1-7-g14eb352 +#### $$VERSION$$ v0.60-rc2-0-gc581932 # shellcheck disable=SC2016 # # Easy Versioning in git: