provide bashbot function reference

This commit is contained in:
Kay Marquardt (Gnadelwartz) 2019-04-15 21:06:29 +02:00
parent c581932d07
commit e29924706d
16 changed files with 187 additions and 57 deletions

View File

@ -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! 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

View File

@ -66,6 +66,24 @@ Getting started
* 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]
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 Security Considerations
~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~
@ -122,5 +140,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.6-rc1-7-g14eb352 latexmath:[\[VERSION\]] v0.60-rc2-0-gc581932
+++++++++++++++++++++++++++++++++++++++++++ ++++++++++++++++++++++++++++++++++++++++++++

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.6-rc1-7-g14eb352 #### $$VERSION$$ v0.60-rc2-0-gc581932
SHELL=/bin/sh SHELL=/bin/sh

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.6-rc1-7-g14eb352 #### $$VERSION$$ v0.60-rc2-0-gc581932
# shellcheck disable=SC2009 # shellcheck disable=SC2009
# shellcheck disable=SC2181 # shellcheck disable=SC2181

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.6-rc1-7-g14eb352 #### $$VERSION$$ v0.60-rc2-0-gc581932
# #
# Exit Codes: # Exit Codes:
# - 0 sucess (hopefully) # - 0 sucess (hopefully)

2
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-dev3-7-gf5538ef #### $$VERSION$$ v0.60-rc2-0-gc581932
# 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

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.6-rc1-7-g14eb352 #### $$VERSION$$ v0.60-rc2-0-gc581932
# #
# shellcheck disable=SC2154 # shellcheck disable=SC2154
# shellcheck disable=SC2034 # 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 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 *) # 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 esac
fi fi

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.6-rc1-11-gba80ec6 #### $$VERSION$$ v0.60-rc2-0-gc581932

View File

@ -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.6-rc1-11-gba80ec6 #### $$VERSION$$ v0.60-rc2-0-gc581932

View File

@ -153,5 +153,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.6-rc1-11-gba80ec6 #### $$VERSION$$ v0.60-rc2-0-gc581932

View File

@ -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``` - 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

View File

@ -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! 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.6-rc1-11-gba80ec6 #### $$VERSION$$ v0.60-rc2-0-gc581932

View File

@ -1,4 +1,4 @@
## Bashbot functions reference ## Bashbot function reference
### Send, forward, delete Messages ### Send, forward, delete Messages
@ -15,24 +15,41 @@ send_action "${CHAT[ID]}" "record_audio"
##### send_normal_message ##### send_normal_message
*usage:* sen_normal_message send text only messages to chat.
*usage:* send_normal_message "${CHAT[ID]}" "message"
*example:* *example:*
```bash
send_normal_message "${CHAT[ID]}" "this is a text message"
```
##### send_markdown_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:* *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 ##### 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:* *example:*
```bash
send_normal_message "${CHAT[ID]}" "this is a markdown message, next word is <b>bold</b>"
send_normal_message "${CHAT[ID]}" "<b>bold</b> <i>italic><i> <em>italic>/em> <a href="link">Text</a>"
```
##### forward ##### 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. 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.** **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) *example:* - see [Usage](2_usage.md#send_message) and [Advanced Usage](3_advanced.md#Interactive-Chats)
---- ----
##### delete_message ##### 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 ##### 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:* *usage:*
*example:* *example:*
```bash
```
##### send_file ##### 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:* *example:*
```bash
send_file "${CHAT[ID]}" "/home/user/doge.jpg" "Lool"
send_file "${CHAT[ID]}" "https://www.domain,com/something.gif" "Something"
```
##### send_location ##### send_location
*usage:* *usage:* send_location "${CHAT[ID]}" "Latitude" "Longitude"
*example:*
##### send_venue ##### 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 ##### remove_keyboard
*usage:* *usage:*
*example:*
### Manage users ### Manage users
##### kick_chat_member ##### 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 ##### 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 ##### 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 ##### 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 ##### 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:* *example:*
```bash
if _is_admin ; then
send_markdown_message "${CHAT[ID]}" "*LEAVING CHAT...*"
leave_chat "${CHAT[ID]}"
fi
```
##### user_is_botadmin ##### 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:* *example:*
```bash
_is_botadmin && send_markdown_message "${CHAT[ID]}" "You are *BOTADMIN*."
```
##### user_is_allowed ##### 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:* *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 ### Interactive and backgound jobs
##### startproc ##### 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:* *example:*
```bash
startproc './calc'
```
##### checkproc ##### checkproc
*usage:* Returns true (0) if an interactive script is running in chat.
*usage:* checkprog
*example:* *example:*
```bash
checkproc
if [ "$res" -gt 0 ] ; then
startproc "./calc"
else
send_normal_message "${CHAT[ID]}" "Calc already running ..."
fi
```
##### killproc ##### killproc
*usage:* *usage:* killproc
*example:* *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 ##### background
*usage:* *usage:* background "./script" "jobname"
*example:* *example:*
```bash
background "./notify" "notify"
```
##### checkback ##### checkback
*usage:* Returns true (0) if an background job is running in chat.
*usage:* checkback "jobname"
*example:* *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 ##### killback
*usage:* *usage:* killback "jobname"
*example:* *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 ### Bashbot internal
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
*usage:* *usage:* send_text "${CHAT[ID]}" "message"
---- ----
##### JsonDecode ##### JsonDecode
*usage:* Outputs decoded string to STDOUT
*usage:* JsonDecode "string"
##### JsonGetString ##### JsonGetString
*usage:* Reads JSON fro STDIN and Outputs found String to STDOUT
*usage:* JsonGetString `"path","to","string"`
##### JsonGetValue ##### JsonGetValue
*usage:* Reads JSON fro STDIN and Outputs found Value to STDOUT
*usage:* JsonGetValue `"path","to","value"`
---- ----
##### get_chat_member_status ##### 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 ##### inproc
Send Input from Telegram to waiting Interactive Chat. Send Input from Telegram to waiting Interactive Chat.
#### $$VERSION$$ v0.6-rc1-11-gba80ec6 #### $$VERSION$$ v0.60-rc2-0-gc581932

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.6-rc1-7-g14eb352 #### $$VERSION$$ v0.60-rc2-0-gc581932
# 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

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.6-rc1-7-g14eb352 #### $$VERSION$$ v0.60-rc2-0-gc581932
# 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

View File

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