mirror of
https://github.com/octoleo/telegram-bot-bash.git
synced 2024-12-28 12:50:44 +00:00
improve documentation
This commit is contained in:
Kay Marquardt (Gnadelwartz)
parent
034274c8d9
commit
d88d422fdd
@ -1,7 +1,7 @@
|
||||
#### [Home](../README.md)
|
||||
## 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```.
|
||||
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)
|
||||
#### [Next Advanced Usage](3_advanced.md)
|
||||
|
||||
#### $$VERSION$$ v0.70-dev2-27-g2da31c1
|
||||
#### $$VERSION$$ v0.70-dev3-6-g034274c
|
||||
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
## Advanced Features
|
||||
|
||||
### 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
|
||||
# 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*."
|
||||
|
||||
```
|
||||
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
|
||||
# file: botacl
|
||||
# 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:*
|
||||
*:*: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
|
||||
case "$MESSAGE" in
|
||||
'/start')
|
||||
@ -58,8 +58,14 @@ you have to use the function ```user_is_allowed``` to check if a user has the ca
|
||||
```
|
||||
|
||||
### 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.
|
||||
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).
|
||||
To create interactive chats, write *(or edit the 'exmaples/question.sh' script)* a bash *(or C or python)* script, make it executable
|
||||
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:
|
||||
```bash
|
||||
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
|
||||
|
||||
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
|
||||
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
|
||||
killback "jobname"
|
||||
```
|
||||
@ -109,7 +115,7 @@ If you want to kill all background jobs permantly run:
|
||||
./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
|
||||
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
|
||||
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)
|
||||
|
||||
#### $$VERSION$$ v0.70-dev2-27-g2da31c1
|
||||
#### $$VERSION$$ v0.70-dev3-6-g034274c
|
||||
|
||||
|
||||
@ -125,23 +125,24 @@ send_keyboard "${CHAT[ID]}" "Enter digit" "[ \\"1\\" , \\"2\\" , \\"3\\" ] , [ \
|
||||
##### remove_keyboard
|
||||
*usage:* remove_keybord "$CHAT[ID]" "message"
|
||||
|
||||
#### send_inline_button
|
||||
*usage:* send_inine_button "chat-id" "message" "Button text" "Buttton URL"
|
||||
##### send_inline_button
|
||||
*usage:* send_inine_button "chat-id" "message" "text" "URL"
|
||||
|
||||
*alias:* _inline_button "Button text" "Buttton URL"
|
||||
*alias:* _inline_button "text" "URL"
|
||||
|
||||
*example:*
|
||||
```bash
|
||||
send_inline_button "${CHAT[ID]}" "MAKE MONEY FAST!!!" "Visit my Shop" "https://dealz.rrr.de"
|
||||
```
|
||||
|
||||
#### 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
|
||||
are sourrounded by a pair of '**{ }**' and seperated by a '**,**'.
|
||||
##### send_inline_keyboard
|
||||
This allows to place multiple inline buttons in a row. The inline buttons must specified as a JSON array in the following format:
|
||||
|
||||
```[ {"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"} ...]"
|
||||
|
||||
@ -157,21 +158,21 @@ send_inline_keyboard "${CHAT[ID]}" "" '[{"text":"b 1", url"":"u 1"}, {"text":"b
|
||||
### Manage users
|
||||
|
||||
##### 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]}"
|
||||
|
||||
*alias:* _kick_user "${USER[ID]}"
|
||||
|
||||
##### 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]}"
|
||||
|
||||
*alias:* _unban "${USER[ID]}"
|
||||
|
||||
##### leave_chat
|
||||
Bot will leave given chat.
|
||||
Your Bot will leave the chat.
|
||||
|
||||
*usage:* leave_chat "${CHAT[ID]}"
|
||||
|
||||
@ -189,8 +190,7 @@ fi
|
||||
### User Access Control
|
||||
|
||||
##### user_is_botadmin
|
||||
Return true (0) if user is owner / admin of bot.
|
||||
Name or ID botadmin must be placed in './botadmin' file.
|
||||
Return true (0) if user is admin of bot, user id if botadmin is read from file './botadmin'.
|
||||
|
||||
*usage:* user_is_botadmin "${USER[ID]}"
|
||||
|
||||
@ -238,21 +238,21 @@ fi
|
||||
----
|
||||
|
||||
### 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
|
||||
|
||||
*alias for:* user_is_botadmin "${USER[ID]}"
|
||||
|
||||
#### _is_admin
|
||||
##### _is_admin
|
||||
|
||||
*usage:* _is_admin
|
||||
|
||||
*alias for:* user_is_admin "${CHAT[ID]}" "${USER[ID]}"
|
||||
|
||||
#### _is_allowed
|
||||
##### _is_allowed
|
||||
|
||||
*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]}"
|
||||
|
||||
*alias for:* kick_chat_member "${CHAT[ID]}" "${USER[ID]}"
|
||||
|
||||
##### unban_chat_member
|
||||
##### _unban
|
||||
|
||||
*usage:* _unban "${USER[ID]}"
|
||||
|
||||
*alias for:* unban_chat_member "${CHAT[ID]}" "${USER[ID]}"
|
||||
|
||||
##### leave_chat
|
||||
##### _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"
|
||||
|
||||
*alias for:* send_normal_message "${CHAT[ID]}" "message"
|
||||
|
||||
#### _normal_message
|
||||
##### _normal_message
|
||||
|
||||
*usage:* _normal_message "message"
|
||||
|
||||
*alias for:* send_normal_message "${CHAT[ID]}" "message"
|
||||
|
||||
#### _html_message
|
||||
##### _html_message
|
||||
|
||||
*usage:* _html_message "message"
|
||||
|
||||
*alias for:* send_html_message "${CHAT[ID]}" "message"
|
||||
|
||||
#### _markdown_message
|
||||
##### _markdown_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
|
||||
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``` 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"
|
||||
|
||||
@ -320,7 +320,7 @@ startproc 'examples/calc.sh'
|
||||
```
|
||||
|
||||
##### 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
|
||||
|
||||
@ -335,6 +335,8 @@ fi
|
||||
```
|
||||
|
||||
##### killproc
|
||||
Kill the interactive script running in the chat
|
||||
|
||||
*usage:* killproc
|
||||
|
||||
*example:*
|
||||
@ -350,7 +352,7 @@ fi
|
||||
----
|
||||
|
||||
##### 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.
|
||||
|
||||
@ -406,7 +408,7 @@ The main use case for send_message is to process the output of interactive chats
|
||||
|
||||
### Helper functions
|
||||
|
||||
#### _is_function
|
||||
##### _is_function
|
||||
Returns true if the given function exist, can be used to check if a module is loaded.
|
||||
|
||||
*usage* _is_function function
|
||||
@ -471,5 +473,5 @@ Send Input from Telegram to waiting Interactive Chat.
|
||||
#### [Prev Best Practice](5_practice.md)
|
||||
#### [Next Notes for Developers](7_develop.md)
|
||||
|
||||
#### $$VERSION$$ v0.70-dev3-4-g8f4b168
|
||||
#### $$VERSION$$ v0.70-dev3-6-g034274c
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user