telegram-bot-bash/doc/6_reference.md

476 lines
12 KiB
Markdown
Raw Normal View History

2019-04-16 18:43:54 +00:00
#### [Home](../README.md)
2019-04-15 19:06:29 +00:00
## Bashbot function reference
2019-04-15 09:49:13 +00:00
2019-04-16 11:29:49 +00:00
### Send, forward, delete messages
2019-04-15 09:49:13 +00:00
2019-04-15 10:52:38 +00:00
##### send_action
2019-04-16 11:29:49 +00:00
```send_action``` shows users what your bot is currently doing.
2019-04-15 17:13:39 +00:00
*usage:* send_action "${CHAT[ID]}" "action"
2019-04-15 09:49:13 +00:00
2019-04-16 11:29:49 +00:00
*"action":* ```typing```, ```upload_photo```, ```record_video```, ```upload_video```, ```record_audio```, ```upload_audio```, ```upload_document```, ```find_location```.
2019-04-15 10:52:38 +00:00
*example:*
2019-04-15 17:13:39 +00:00
```bash
send_action "${CHAT[ID]}" "typing"
send_action "${CHAT[ID]}" "record_audio"
```
2019-04-15 09:49:13 +00:00
2019-04-15 10:52:38 +00:00
##### send_normal_message
2019-04-16 11:29:49 +00:00
```send_normal_message``` sends text only messages to the given chat.
2019-04-15 19:06:29 +00:00
*usage:* send_normal_message "${CHAT[ID]}" "message"
2019-04-15 09:49:13 +00:00
2019-04-15 10:52:38 +00:00
*example:*
2019-04-15 19:06:29 +00:00
```bash
send_normal_message "${CHAT[ID]}" "this is a text message"
```
2019-04-15 09:49:13 +00:00
2019-04-15 10:52:38 +00:00
##### send_markdown_message
2019-04-16 11:29:49 +00:00
```send_markdown_message``` sends markdown style messages to the given chat.
Telegram supports a [reduced set of Markdown](https://core.telegram.org/bots/api#markdown-style) only
2019-04-15 19:06:29 +00:00
2019-04-16 11:29:49 +00:00
*usage:* send_markdown_message "${CHAT[ID]}" "markdown message"
2019-04-15 10:52:38 +00:00
*example:*
2019-04-15 19:06:29 +00:00
```bash
2019-04-25 14:59:17 +00:00
send_markdown_message "${CHAT[ID]}" "this is a markdown message, next word is *bold*"
send_markdown_message "${CHAT[ID]}" "*bold* _italic_ [text](link)"
2019-04-15 19:06:29 +00:00
```
2019-04-15 10:52:38 +00:00
##### send_html_message
2019-04-16 11:29:49 +00:00
```send_html_message``` sends HTML style messages to the given chat.
Telegram supports a [reduced set of HTML](https://core.telegram.org/bots/api#html-style) only
2019-04-15 19:06:29 +00:00
2019-04-16 11:29:49 +00:00
*usage:* send_html_message "${CHAT[ID]}" "html message"
2019-04-15 10:52:38 +00:00
*example:*
2019-04-15 19:06:29 +00:00
```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>"
```
2019-04-15 10:52:38 +00:00
2019-04-16 11:29:49 +00:00
##### forward_message
```forward_mesage``` forwards a messsage to the given chat.
2019-04-15 10:52:38 +00:00
2019-04-16 11:29:49 +00:00
*usage:* forward_message "chat_to" "chat_from" "${MESSAGE[ID]}"
2019-04-24 08:07:46 +00:00
*old call:* forward "${CHAT[ID]}" "$FROMCHAT" "${MESSAGE[ID]}"
2019-04-15 09:49:13 +00:00
----
2019-04-15 10:52:38 +00:00
##### delete_message
2019-04-16 11:29:49 +00:00
If your Bot is admin of a Chat he can delete every message, if not he can delete only his messages.
2019-04-15 10:52:38 +00:00
2019-04-15 19:06:29 +00:00
*usage:* delete_message "${CHAT[ID]}" "${MESSAGE[ID]}"
2019-04-15 09:49:13 +00:00
----
2019-04-15 10:52:38 +00:00
##### answer_inline_query
2019-04-15 19:13:08 +00:00
Inline Queries allows users to interact with your bot directly without sending extra commands.
2019-04-15 19:06:29 +00:00
answer_inline_query provide the result to a users Inline Query
2019-04-15 10:52:38 +00:00
2019-04-15 19:06:29 +00:00
*usage:* answer_inline_query "$iQUERY_ID" "type" "type arg 1" ... "type arg n"
*example:* - see [Advanced Usage](3_advanced.md#Inline-queries)
2019-04-15 09:49:13 +00:00
----
2019-04-17 07:34:02 +00:00
### File, Location, Venue, Keyboard
2019-04-15 09:49:13 +00:00
2019-04-15 10:52:38 +00:00
##### send_file
2019-04-15 19:13:08 +00:00
send_file allows you to send different type's of files, e.g. photos, stickers, audio, media, etc. [see more](https://core.telegram.org/bots/api#sending-files)
2019-04-15 19:06:29 +00:00
*usage:* send_file "${CHAT[ID]}" "file" "caption"
2019-04-15 09:49:13 +00:00
2019-04-15 10:52:38 +00:00
*example:*
2019-04-15 19:06:29 +00:00
```bash
send_file "${CHAT[ID]}" "/home/user/doge.jpg" "Lool"
send_file "${CHAT[ID]}" "https://www.domain,com/something.gif" "Something"
```
2019-04-15 09:49:13 +00:00
2019-04-15 10:52:38 +00:00
##### send_location
2019-04-15 19:06:29 +00:00
*usage:* send_location "${CHAT[ID]}" "Latitude" "Longitude"
2019-04-15 10:52:38 +00:00
##### send_venue
2019-04-15 19:06:29 +00:00
*usage:* send_venue "${CHAT[ID]}" "Latitude" "Longitude" "Title" "Address" "foursquare id (optional)"
2019-04-15 10:52:38 +00:00
2019-04-15 09:49:13 +00:00
----
2019-04-15 10:52:38 +00:00
##### send_keyboard
2019-04-16 11:29:49 +00:00
Note: since version 0.6 send_keyboard was changed to use native "JSON Array" notation as used from Telegram. Example Keybord Array definitions:
2019-04-18 08:35:18 +00:00
- yes no in two rows:
- OLD format: 'yes' 'no' (two strings)
- NEW format: '[ "yes" ] , [ "no" ]' (two arrays with a string)
- new layouts made easy with NEW format:
- Yes No in one row: '[ "yes" , "no" ]'
- Yes No plus Maybe in 2.row: '[ "yes" , "no" ] , [ "maybe" ]'
2019-04-16 18:43:54 +00:00
- numpad style keyboard: '[ "1" , "2" , "3" ] , [ "4" , "5" , "6" ] , [ "7" , "8" , "9" ] , [ "0" ]'
2019-04-16 11:29:49 +00:00
2019-04-17 07:34:02 +00:00
*usage:* send_keyboard "chat-id" "message" "keyboard"
2019-04-15 10:52:38 +00:00
*example:*
2019-04-15 17:13:39 +00:00
```bash
2019-04-17 07:34:02 +00:00
send_keyboard "${CHAT[ID]}" "Say yes or no" "[ \\"yes\" , \\"no\" ]""
send_keyboard "${CHAT[ID]}" "Say yes or no" "[ \\"yes\\" ] , [ \\"no\\" ]"
send_keyboard "${CHAT[ID]}" "Enter digit" "[ \\"1\\" , \\"2\\" , \\"3\\" ] , [ \\"4\\" , \\"5\\" , \\"6\\" ] , [ \\"7\\" , \\"8\\" , \\"9\\" ] , [ \\"0\\" ]"
2019-04-15 17:13:39 +00:00
```
2019-04-15 10:52:38 +00:00
##### remove_keyboard
2019-04-17 07:34:02 +00:00
*usage:* remove_keybord "$CHAT[ID]" "message"
2019-04-15 09:49:13 +00:00
2019-04-25 14:59:17 +00:00
#### send_inline_button
*usage:* send_inine_button "chat-id" "message" "Button text" "Buttton URL"
*alias:* _inline_button "Button text" "Buttton 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 '**,**'.
```[ {"text":"text1", "url":"url1"}, ... {"text":"textN", "url":"urlN"} ]```
*usage:* send_inline_keyboard "chat-id" "message" "[{"text":"text", "url":"url"} ...]"
*alias:* _inline_keyboard "[{"text":"text", "url":"url"} ...]"
*example:*
```bash
send_inline_keyboard "${CHAT[ID]}" "MAKE MONEY FAST!!!" '[{"text":"Visit my Shop", url"":"https://dealz.rrr.de"}]'
send_inline_keyboard "${CHAT[ID]}" "" '[{"text":"button 1", url"":"url 1"}, {"text":"button 2", url"":"url 2"} ]'
send_inline_keyboard "${CHAT[ID]}" "" '[{"text":"b 1", url"":"u 1"}, {"text":"b 2", url"":"u 2"}, {"text":"b 2", url"":"u 2"} ]'
```
2019-04-24 08:07:46 +00:00
----
2019-04-15 09:49:13 +00:00
### Manage users
2019-04-15 10:52:38 +00:00
##### kick_chat_member
2019-04-15 19:13:08 +00:00
If your Bot is Admin of a chat he can kick and ban a user.
2019-04-15 19:06:29 +00:00
*usage:* kick_chat_member "${CHAT[ID]}" "${USER[ID]}"
2019-04-15 09:49:13 +00:00
2019-04-25 14:59:17 +00:00
*alias:* _kick_user "${USER[ID]}"
2019-04-15 09:49:13 +00:00
2019-04-15 10:52:38 +00:00
##### unban_chat_member
2019-04-16 14:45:26 +00:00
If your Bot is Admin of a chat he can unban a kicked user.
2019-04-15 10:52:38 +00:00
2019-04-15 19:06:29 +00:00
*usage:* unban_chat_member "${CHAT[ID]}" "${USER[ID]}"
2019-04-15 10:52:38 +00:00
2019-04-25 14:59:17 +00:00
*alias:* _unban "${USER[ID]}"
2019-04-15 10:52:38 +00:00
##### leave_chat
2019-04-16 14:45:26 +00:00
Bot will leave given chat.
2019-04-15 10:52:38 +00:00
2019-04-15 19:06:29 +00:00
*usage:* leave_chat "${CHAT[ID]}"
2019-04-25 14:59:17 +00:00
*alias:* _leave
2019-04-15 19:06:29 +00:00
```bash
if _is_admin ; then
send_markdown_message "${CHAT[ID]}" "*LEAVING CHAT...*"
leave_chat "${CHAT[ID]}"
fi
```
2019-04-15 09:49:13 +00:00
----
2019-04-24 08:07:46 +00:00
2019-04-23 13:48:58 +00:00
### 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.
*usage:* user_is_botadmin "${USER[ID]}"
2019-04-24 08:07:46 +00:00
*modules/alias:* _is_botadmin
2019-04-23 13:48:58 +00:00
*example:*
```bash
_is_botadmin && send_markdown_message "${CHAT[ID]}" "You are *BOTADMIN*."
```
2019-04-15 09:49:13 +00:00
2019-04-15 10:52:38 +00:00
##### user_is_creator
2019-04-16 14:45:26 +00:00
Return true (0) if user is creator of given chat or chat is a private chat.
2019-04-15 10:52:38 +00:00
2019-04-15 19:06:29 +00:00
*usage:* user_is_creator "${CHAT[ID]}" "${USER[ID]}"
2019-04-24 08:07:46 +00:00
*modules/alias:* _is_creator
2019-04-15 09:49:13 +00:00
2019-04-15 10:52:38 +00:00
##### user_is_admin
2019-04-16 14:45:26 +00:00
Return true (0) if user is admin or creator of given chat.
2019-04-15 19:06:29 +00:00
*usage:* user_is_admin "${CHAT[ID]}" "${USER[ID]}"
2019-04-24 08:07:46 +00:00
*modules/alias:* _is_admin
2019-04-15 09:49:13 +00:00
2019-04-15 10:52:38 +00:00
*example:*
2019-04-15 19:06:29 +00:00
```bash
if _is_admin ; then
send_markdown_message "${CHAT[ID]}" "*LEAVING CHAT...*"
leave_chat "${CHAT[ID]}"
fi
```
2019-04-15 09:49:13 +00:00
2019-04-15 10:52:38 +00:00
##### user_is_allowed
2019-04-15 19:06:29 +00:00
Bahsbot supports User Access Control, see [Advanced Usage](4_advanced.ma)
*usage:* user_is_allowed "${USER[ID]}" "what" "${CHAT[ID]}"
2019-04-15 10:52:38 +00:00
*example:*
2019-04-15 19:06:29 +00:00
```bash
if ! user_is_allowed "${USER[ID]}" "start" "${CHAT[ID]}" ; then
send_normal_message "${CHAT[ID]}" "You are not allowed to start Bot."
fi
```
2019-04-15 09:49:13 +00:00
2019-04-24 08:07:46 +00:00
----
### 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.
#### _is_botadmin
*usage:* _is_botadmin
2019-04-25 14:59:17 +00:00
*alias for:* user_is_botadmin "${USER[ID]}"
2019-04-24 08:07:46 +00:00
#### _is_admin
*usage:* _is_admin
2019-04-25 14:59:17 +00:00
*alias for:* user_is_admin "${CHAT[ID]}" "${USER[ID]}"
2019-04-24 08:07:46 +00:00
#### _is_allowed
*usage:* _is_allowed "what"
2019-04-25 14:59:17 +00:00
*alias for:* user_is_allowed "${USER[ID]}" "what" "${CHAT[ID]}"
2019-04-24 08:07:46 +00:00
----
##### kick_chat_member
*usage:* _kick_user "${USER[ID]}"
2019-04-25 14:59:17 +00:00
*alias for:* kick_chat_member "${CHAT[ID]}" "${USER[ID]}"
##### unban_chat_member
*usage:* _unban "${USER[ID]}"
2019-04-25 14:59:17 +00:00
*alias for:* unban_chat_member "${CHAT[ID]}" "${USER[ID]}"
##### leave_chat
*usage:* _leave
2019-04-25 14:59:17 +00:00
*alias for:* leave_chat "${CHAT[ID]}"
----
2019-04-24 08:07:46 +00:00
#### _message
*usage:* _message "message"
2019-04-25 14:59:17 +00:00
*alias for:* send_normal_message "${CHAT[ID]}" "message"
2019-04-24 08:07:46 +00:00
#### _normal_message
*usage:* _normal_message "message"
2019-04-25 14:59:17 +00:00
*alias for:* send_normal_message "${CHAT[ID]}" "message"
2019-04-24 08:07:46 +00:00
#### _html_message
*usage:* _html_message "message"
2019-04-25 14:59:17 +00:00
*alias for:* send_html_message "${CHAT[ID]}" "message"
2019-04-24 08:07:46 +00:00
#### _markdown_message
*usage:* _markdown_message "message"
2019-04-25 14:59:17 +00:00
*alias for:* send_markdown_message "${CHAT[ID]}" "message"
2019-04-24 08:07:46 +00:00
----
2019-04-15 09:49:13 +00:00
### Interactive and backgound jobs
2019-04-24 08:07:46 +00:00
You must use ```source modules/background.sh``` in commands.sh or mycommands.sh to have the following functions availible.
2019-04-15 09:49:13 +00:00
2019-04-15 10:52:38 +00:00
##### startproc
2019-04-16 14:45:26 +00:00
```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)
2019-04-15 19:06:29 +00:00
2019-04-19 09:28:12 +00:00
*usage:* startproc "script"
2019-04-15 10:52:38 +00:00
*example:*
2019-04-15 19:06:29 +00:00
```bash
2019-04-19 09:28:12 +00:00
startproc 'examples/calc.sh'
2019-04-15 19:06:29 +00:00
```
2019-04-15 10:52:38 +00:00
##### checkproc
2019-04-16 14:45:26 +00:00
Return true (0) if an interactive script active in the given chat.
2019-04-15 19:06:29 +00:00
*usage:* checkprog
2019-04-15 09:49:13 +00:00
2019-04-15 10:52:38 +00:00
*example:*
2019-04-15 19:06:29 +00:00
```bash
checkproc
if [ "$res" -gt 0 ] ; then
2019-04-19 09:28:12 +00:00
startproc "examples/calc.sh"
2019-04-15 19:06:29 +00:00
else
send_normal_message "${CHAT[ID]}" "Calc already running ..."
fi
```
2019-04-15 09:49:13 +00:00
2019-04-15 10:52:38 +00:00
##### killproc
2019-04-15 19:06:29 +00:00
*usage:* killproc
2019-04-15 10:52:38 +00:00
*example:*
2019-04-15 19:06:29 +00:00
```bash
checkprog
if [ "$res" -eq 0 ]; then
killproc && send_message "${CHAT[ID]}" "Command canceled."
else
send_message "${CHAT[ID]}" "Command is not running."
fi
```
2019-04-15 09:49:13 +00:00
----
2019-04-15 10:52:38 +00:00
##### background
2019-04-16 11:29:49 +00:00
```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.
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.
2019-04-19 09:28:12 +00:00
*usage:* background "script" "jobname"
2019-04-15 10:52:38 +00:00
*example:*
2019-04-15 19:06:29 +00:00
```bash
2019-04-19 09:28:12 +00:00
background "examples/notify.sh" "notify"
2019-04-15 19:06:29 +00:00
```
2019-04-15 10:52:38 +00:00
##### checkback
2019-04-16 14:45:26 +00:00
Return true (0) if an background job is active in the given chat.
2019-04-15 19:06:29 +00:00
*usage:* checkback "jobname"
2019-04-15 10:52:38 +00:00
*example:*
2019-04-15 19:06:29 +00:00
```bash
checkback "notify"
if [ "$res" -gt 0 ] ; then
send_normal_message "${CHAT[ID]}" "Start notify"
2019-04-19 09:28:12 +00:00
background "examples/notify.sh" "notify"
2019-04-15 19:06:29 +00:00
else
send_normal_message "${CHAT[ID]}" "Process notify already running."
fi
```
2019-04-15 09:49:13 +00:00
2019-04-15 10:52:38 +00:00
##### killback
2019-04-15 19:06:29 +00:00
*usage:* killback "jobname"
2019-04-15 09:49:13 +00:00
2019-04-15 10:52:38 +00:00
*example:*
2019-04-15 19:06:29 +00:00
```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
```
2019-04-15 09:49:13 +00:00
2019-04-24 08:07:46 +00:00
----
##### send_message
```send_message``` sends any type of message to the given chat. Type of output is steered by keywords within the message.
The main use case for send_message is to process the output of interactive chats and background jobs. **For regular Bot commands I recommend using of the dedicated send_xxx_message() functions from above.**
*usage:* send_message "${CHAT[ID]}" "message"
*example:* - see [Usage](2_usage.md#send_message) and [Advanced Usage](3_advanced.md#Interactive-Chats)
----
### Helper functions
#### _is_function
Returns true if the given function exist, can be used to check if a module is loaded.
*usage* _is_function function
*example:*
```bash
_is_function "background" && _message "you can run background jobs!"
```
----
2019-04-16 11:29:49 +00:00
### Bashbot internal functions
2019-04-15 12:17:18 +00:00
These functions are for internal use only and must not used in your bot commands.
2019-04-15 09:49:13 +00:00
2019-04-17 07:34:02 +00:00
##### get_file
*usage:* url="$(get_file "${CHAT[ID]}" "message")"
----
2019-04-15 10:52:38 +00:00
##### send_text
2019-04-15 19:06:29 +00:00
*usage:* send_text "${CHAT[ID]}" "message"
2019-04-15 10:52:38 +00:00
2019-04-15 09:49:13 +00:00
----
2019-04-15 10:52:38 +00:00
##### JsonDecode
2019-04-15 19:06:29 +00:00
Outputs decoded string to STDOUT
*usage:* JsonDecode "string"
2019-04-15 10:52:38 +00:00
##### JsonGetString
2019-04-15 19:06:29 +00:00
Reads JSON fro STDIN and Outputs found String to STDOUT
*usage:* JsonGetString `"path","to","string"`
2019-04-15 09:49:13 +00:00
2019-04-15 10:52:38 +00:00
##### JsonGetValue
2019-04-15 19:06:29 +00:00
Reads JSON fro STDIN and Outputs found Value to STDOUT
*usage:* JsonGetValue `"path","to","value"`
2019-04-15 10:52:38 +00:00
2019-04-15 09:49:13 +00:00
----
2019-04-15 10:52:38 +00:00
##### get_chat_member_status
2019-04-15 19:06:29 +00:00
*usage:* get_chat_member_status "${CHAT[ID]}" "${USER[ID]}"
2019-04-15 10:52:38 +00:00
2019-04-15 09:49:13 +00:00
----
2019-04-15 10:52:38 +00:00
##### process_client
2019-04-15 12:17:18 +00:00
Every Message sent to your Bot is processd by this function. It parse the send JSON and assign the found Values to bash variables.
2019-04-15 10:52:38 +00:00
##### process_updates
2019-04-15 12:17:18 +00:00
If new updates are availible, this functions gets the JSON from Telegram and dispatch it.
2019-04-15 09:49:13 +00:00
----
2019-04-15 10:52:38 +00:00
##### getBotName
2019-04-15 12:17:18 +00:00
The name of your bot is availible as bash variable "$ME", there is no need to call this function if Bot is running.
2019-04-15 10:52:38 +00:00
2019-04-15 12:17:18 +00:00
*usage:* ME="$(getBotNiname)"
2019-04-15 10:52:38 +00:00
##### inproc
2019-04-15 12:17:18 +00:00
Send Input from Telegram to waiting Interactive Chat.
2019-04-15 09:49:13 +00:00
2019-04-16 14:45:26 +00:00
#### [Prev Best Practice](5_practice.md)
2019-04-23 09:45:03 +00:00
#### [Next Notes for Developers](7_develop.md)
2019-04-16 14:45:26 +00:00
2019-04-25 14:59:17 +00:00
#### $$VERSION$$ v0.70-dev3-4-g8f4b168
2019-04-15 09:49:13 +00:00