octoleo/telegram-bot-bash
1
1
Fork 0
mirror of https://github.com/octoleo/telegram-bot-bash.git synced 2024-11-26 01:07:34 +00:00
Code Issues Projects Releases Wiki Activity

improve documentation

Browse Source
This commit is contained in:
Kay Marquardt (Gnadelwartz) 2019-04-25 22:17:24 +02:00
parent 034274c8d9
commit d88d422fdd
3 changed files with 49 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/2_usage.md
View File

@ -1,7 +1,7 @@
#### [Home](../README.md) #### [Home](../README.md)
## Gettting Started ## Gettting Started
The Bots standard commands are in ```commands.sh``` file. You must not add your commands to 'commands.sh', instead place them in ```mycommands.sh```, there you also find examples how to process messages and send out text. The Bots standard commands are in ```commands.sh``` file. You must not add your commands to 'commands.sh', instead place them in ```mycommands.sh```, there you also find examples how to process messages and send out text. See [Best practices](5_practice.md) for more information.
Once you're done with editing 'mycommands.sh' start the Bot with ```./bashbot.sh start```. Once you're done with editing 'mycommands.sh' start the Bot with ```./bashbot.sh start```.
If some thing doesn't work as it should, debug with ```bash -x bashbot.sh```. To stop the Bot run ```./bashbot.sh kill``` If some thing doesn't work as it should, debug with ```bash -x bashbot.sh```. To stop the Bot run ```./bashbot.sh kill```
@ -166,5 +166,5 @@ send_action "${CHAT[ID]}" "action"
#### [Prev Create Bot](1_firstbot.md) #### [Prev Create Bot](1_firstbot.md)
#### [Next Advanced Usage](3_advanced.md) #### [Next Advanced Usage](3_advanced.md)
#### $$VERSION$$ v0.70-dev2-27-g2da31c1 #### $$VERSION$$ v0.70-dev3-6-g034274c

26
doc/3_advanced.md
View File

@ -2,7 +2,7 @@
## Advanced Features ## Advanced Features
### Access control ### Access control
Bashbot offers functions to check what Telegram capabilities like chat admin or chat creator the given user has: Bashbot offers functions to check what Telegram capabilities like 'chat admin' or 'chat creator' the given user has:
```bash ```bash
# return true if user is admin/owner of the bot # return true if user is admin/owner of the bot
@ -21,7 +21,7 @@ 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*." user_is_admin "${CHAT[ID]}" "${USER[ID]}" && send_markdown_message "${CHAT[ID]}" "You are *CHATADMIN*."
``` ```
In addition you can check individual capabilities of users as defined in the ```./botacl``` file: In addition you can check individual capabilities of users as you must define in the file ```./botacl```:
```bash ```bash
# file: botacl # file: botacl
# a user not listed here, will return false from 'user_is_allowed' # a user not listed here, will return false from 'user_is_allowed'
@ -44,7 +44,7 @@ In addition you can check individual capabilities of users as defined in the ```
*:start:* *:start:*
*:*:98979695 *:*:98979695
``` ```
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: You must 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 ```bash
case "$MESSAGE" in case "$MESSAGE" in
'/start') '/start')
@ -58,8 +58,14 @@ you have to use the function ```user_is_allowed``` to check if a user has the ca
``` ```
### Interactive Chats ### Interactive Chats
To create interactive chats, write (or edit the exmaples/question.sh script) a normal bash (or C or python) script, chmod +x it and then change the argument of the startproc function to match the command you usually use to start the script. To create interactive chats, write *(or edit the 'exmaples/question.sh' script)* a bash *(or C or python)* script, make it executable
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 (as long as it's running or until the user kills it with /cancel). and then use the 'startproc' function to start the script.
The output of the script will be sent to the user and user input will be sent to the script.
To stop the script use the function 'killprog'
The output of the script will be processed by 'send_messages' to enable you to not only send text, but also keyboards, files, locations and more.
Each newline in the output will start an new message to the user, to have line breaks in your message you can use 'mynewlinestartshere'.
To open up a keyboard in an interactive script, print out the keyboard layout in the following way: To open up a keyboard in an interactive script, print out the keyboard layout in the following way:
```bash ```bash
echo "Text that will appear in chat? mykeyboardstartshere [ \"Yep, sure\" , \"No, highly unlikely\" ]" echo "Text that will appear in chat? mykeyboardstartshere [ \"Yep, sure\" , \"No, highly unlikely\" ]"
@ -90,11 +96,11 @@ Note: Interactive Chats run independent from main bot and continue running until
### Background Jobs ### Background Jobs
A background job is similar to an interactive chat, but runs in the background and does only output massages instead of processing input from the user. In contrast to interactive chats it's possible to run multiple background jobs. To create a background job write a script or edit the examples/notify.sh script and use the funtion ```background``` to start it: A background job is similar to an interactive chat, but runs in the background and does only output massages and does not get user input. In contrast to interactive chats it's possible to run multiple background jobs. To create a background job write a script or edit 'examples/notify.sh' script and use the funtion ```background``` to start it:
```bash ```bash
background "examples/notify.sh" "jobname" background "examples/notify.sh" "jobname"
``` ```
All output of the script will be sent to the user or chat. To stop a background job use: All output of the script will be sent to the user, to stop a background job use:
```bash ```bash
killback "jobname" killback "jobname"
``` ```
@ -109,7 +115,7 @@ If you want to kill all background jobs permantly run:
./bashbot.sh killback ./bashbot.sh killback
``` ```
Note: Background Jobs run independent from main bot and continue running until your script exits or you stop if from your Bot. Backgound Jobs will continue running if your Bot is stoped (kill)!. Note: Background Jobs run independent from main bot and continue running until your script exits or you stop if from your Bot. Backgound Jobs will continue running if your Bot is stopeda and must be terminated, e.g. by ```bashbot.sh killback```
### Inline queries ### Inline queries
The following commands allows users to interact with your bot via *inline queries*. The following commands allows users to interact with your bot via *inline queries*.
@ -153,8 +159,8 @@ To send stickers through an *inline query*:
```bash ```bash
answer_inline_query "$iQUERY_ID" "cached_sticker" "identifier for the sticker" answer_inline_query "$iQUERY_ID" "cached_sticker" "identifier for the sticker"
``` ```
#### [Prev Advanced Usage](3_advanced.md) #### [Prev Getting started](2_usage.md)
#### [Next Expert Use](4_expert.md) #### [Next Expert Use](4_expert.md)
#### $$VERSION$$ v0.70-dev2-27-g2da31c1 #### $$VERSION$$ v0.70-dev3-6-g034274c

60
doc/6_reference.md
View File

@ -125,23 +125,24 @@ send_keyboard "${CHAT[ID]}" "Enter digit" "[ \\"1\\" , \\"2\\" , \\"3\\" ] , [ \
##### remove_keyboard ##### remove_keyboard
*usage:* remove_keybord "$CHAT[ID]" "message" *usage:* remove_keybord "$CHAT[ID]" "message"
#### send_inline_button ##### send_inline_button
*usage:* send_inine_button "chat-id" "message" "Button text" "Buttton URL" *usage:* send_inine_button "chat-id" "message" "text" "URL"
*alias:* _inline_button "Button text" "Buttton URL" *alias:* _inline_button "text" "URL"
*example:* *example:*
```bash ```bash
send_inline_button "${CHAT[ID]}" "MAKE MONEY FAST!!!" "Visit my Shop" "https://dealz.rrr.de" send_inline_button "${CHAT[ID]}" "MAKE MONEY FAST!!!" "Visit my Shop" "https://dealz.rrr.de"
``` ```
#### send_inline_keyboard ##### send_inline_keyboard
An inline keyboard is used to place multiple inline buttons in a row. The inline buttons must specified as a JSON array in the following format. Each button consists of a text for the button and an URL to got to if the button is clicked, button definitions This allows to place multiple inline buttons in a row. The inline buttons must specified as a JSON array in the following format:
are sourrounded by a pair of '**{ }**' and seperated by a '**,**'.
```[ {"text":"text1", "url":"url1"}, ... {"text":"textN", "url":"urlN"} ]``` ```[ {"text":"text1", "url":"url1"}, ... {"text":"textN", "url":"urlN"} ]```
*usage:* send_inline_keyboard "chat-id" "message" "[{"text":"text", "url":"url"} ...]" Each button consists of a pair of text and URL values, sourrounded by '**{ }**', multiple buttons are seperated by '**,**' and everthing is wrapped in '**[ ]**'.
*usage:* send_inline_keyboard "chat-id" "message" "[ {"text":"text", "url":"url"} ...]"
*alias:* _inline_keyboard "[{"text":"text", "url":"url"} ...]" *alias:* _inline_keyboard "[{"text":"text", "url":"url"} ...]"
@ -157,21 +158,21 @@ send_inline_keyboard "${CHAT[ID]}" "" '[{"text":"b 1", url"":"u 1"}, {"text":"b
### Manage users ### Manage users
##### kick_chat_member ##### kick_chat_member
If your Bot is Admin of a chat he can kick and ban a user. If your Bot is a chat admin he can kick and ban a user.
*usage:* kick_chat_member "${CHAT[ID]}" "${USER[ID]}" *usage:* kick_chat_member "${CHAT[ID]}" "${USER[ID]}"
*alias:* _kick_user "${USER[ID]}" *alias:* _kick_user "${USER[ID]}"
##### unban_chat_member ##### unban_chat_member
If your Bot is Admin of a chat he can unban a kicked user. If your Bot is a chat admine can unban a kicked user.
*usage:* unban_chat_member "${CHAT[ID]}" "${USER[ID]}" *usage:* unban_chat_member "${CHAT[ID]}" "${USER[ID]}"
*alias:* _unban "${USER[ID]}" *alias:* _unban "${USER[ID]}"
##### leave_chat ##### leave_chat
Bot will leave given chat. Your Bot will leave the chat.
*usage:* leave_chat "${CHAT[ID]}" *usage:* leave_chat "${CHAT[ID]}"
@ -189,8 +190,7 @@ fi
### User Access Control ### User Access Control
##### user_is_botadmin ##### user_is_botadmin
Return true (0) if user is owner / admin of bot. Return true (0) if user is admin of bot, user id if botadmin is read from file './botadmin'.
Name or ID botadmin must be placed in './botadmin' file.
*usage:* user_is_botadmin "${USER[ID]}" *usage:* user_is_botadmin "${USER[ID]}"
@ -238,21 +238,21 @@ fi
---- ----
### Aliases - shortcuts for often used funtions ### Aliases - shortcuts for often used funtions
You must use ```source modules/aliases.sh``` in commands.sh or mycommands.sh to have the following functions availible. You must not disable ```source modules/aliases.sh``` in 'commands.sh' to have the following functions availible.
#### _is_botadmin ##### _is_botadmin
*usage:* _is_botadmin *usage:* _is_botadmin
*alias for:* user_is_botadmin "${USER[ID]}" *alias for:* user_is_botadmin "${USER[ID]}"
#### _is_admin ##### _is_admin
*usage:* _is_admin *usage:* _is_admin
*alias for:* user_is_admin "${CHAT[ID]}" "${USER[ID]}" *alias for:* user_is_admin "${CHAT[ID]}" "${USER[ID]}"
#### _is_allowed ##### _is_allowed
*usage:* _is_allowed "what" *usage:* _is_allowed "what"
@ -260,19 +260,19 @@ You must use ```source modules/aliases.sh``` in commands.sh or mycommands.sh to
---- ----
##### kick_chat_member ##### _kick_user
*usage:* _kick_user "${USER[ID]}" *usage:* _kick_user "${USER[ID]}"
*alias for:* kick_chat_member "${CHAT[ID]}" "${USER[ID]}" *alias for:* kick_chat_member "${CHAT[ID]}" "${USER[ID]}"
##### unban_chat_member ##### _unban
*usage:* _unban "${USER[ID]}" *usage:* _unban "${USER[ID]}"
*alias for:* unban_chat_member "${CHAT[ID]}" "${USER[ID]}" *alias for:* unban_chat_member "${CHAT[ID]}" "${USER[ID]}"
##### leave_chat ##### _leave
*usage:* _leave *usage:* _leave
@ -280,25 +280,25 @@ You must use ```source modules/aliases.sh``` in commands.sh or mycommands.sh to
---- ----
#### _message ##### _message
*usage:* _message "message" *usage:* _message "message"
*alias for:* send_normal_message "${CHAT[ID]}" "message" *alias for:* send_normal_message "${CHAT[ID]}" "message"
#### _normal_message ##### _normal_message
*usage:* _normal_message "message" *usage:* _normal_message "message"
*alias for:* send_normal_message "${CHAT[ID]}" "message" *alias for:* send_normal_message "${CHAT[ID]}" "message"
#### _html_message ##### _html_message
*usage:* _html_message "message" *usage:* _html_message "message"
*alias for:* send_html_message "${CHAT[ID]}" "message" *alias for:* send_html_message "${CHAT[ID]}" "message"
#### _markdown_message ##### _markdown_message
*usage:* _markdown_message "message" *usage:* _markdown_message "message"
@ -307,10 +307,10 @@ You must use ```source modules/aliases.sh``` in commands.sh or mycommands.sh to
---- ----
### Interactive and backgound jobs ### Interactive and backgound jobs
You must use ```source modules/background.sh``` in commands.sh or mycommands.sh to have the following functions availible. You must not disable ```source modules/background.sh``` in 'commands.sh' to have the following functions availible.
##### startproc ##### startproc
```startproc``` starts a script (or C or python program etc.) running in parallel to your Bot. The text that the script outputs is sent to the user or chat, user input will be sent back to the script. see [Advanced Usage](3_advanced.md#Interactive-Chats) ```startproc``` starts a script, the output of the script is sent 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" *usage:* startproc "script"
@ -320,7 +320,7 @@ startproc 'examples/calc.sh'
``` ```
##### checkproc ##### checkproc
Return true (0) if an interactive script active in the given chat. Return true (0) if an interactive script is running in the chat.
*usage:* checkprog *usage:* checkprog
@ -335,6 +335,8 @@ fi
``` ```
##### killproc ##### killproc
Kill the interactive script running in the chat
*usage:* killproc *usage:* killproc
*example:* *example:*
@ -350,7 +352,7 @@ fi
---- ----
##### background ##### 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. Starts a script 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. 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.
@ -406,7 +408,7 @@ The main use case for send_message is to process the output of interactive chats
### Helper functions ### Helper functions
#### _is_function ##### _is_function
Returns true if the given function exist, can be used to check if a module is loaded. Returns true if the given function exist, can be used to check if a module is loaded.
*usage* _is_function function *usage* _is_function function
@ -471,5 +473,5 @@ Send Input from Telegram to waiting Interactive Chat.
#### [Prev Best Practice](5_practice.md) #### [Prev Best Practice](5_practice.md)
#### [Next Notes for Developers](7_develop.md) #### [Next Notes for Developers](7_develop.md)
#### $$VERSION$$ v0.70-dev3-4-g8f4b168 #### $$VERSION$$ v0.70-dev3-6-g034274c