provide bashbot function reference
This commit is contained in:
Kay Marquardt (Gnadelwartz)
parent
c581932d07
commit
e29924706d
|
|
@ -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
|
||||
|
|
|
|||
22
README.txt
22
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
|
||||
++++++++++++++++++++++++++++++++++++++++++++
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
2
calc
2
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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <b>bold</b>"
|
||||
send_normal_message "${CHAT[ID]}" "<b>bold</b> <i>italic><i> <em>italic>/em> <a href="link">Text</a>"
|
||||
```
|
||||
|
||||
##### 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
|
||||
|
||||
|
|
|
|||
2
notify
2
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
|
||||
|
|
|
|||
2
question
2
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
|
||||
|
|
|
|||
Loading…
Reference in New Issue