From 14eb3520d5bb93293116a9c52e8f805b880adf1b Mon Sep 17 00:00:00 2001 From: "Kay Marquardt (Gnadelwartz)" Date: Mon, 15 Apr 2019 12:52:38 +0200 Subject: [PATCH] minor doc updates --- doc/1_firstbot.md | 2 +- doc/2_usage.md | 57 ++++++++------ doc/3_advanced.md | 2 +- doc/4_expert.md | 2 +- doc/5_practice.md | 2 +- doc/6_reference.md | 185 ++++++++++++++++++++++++++++++++++++--------- 6 files changed, 185 insertions(+), 65 deletions(-) diff --git a/doc/1_firstbot.md b/doc/1_firstbot.md index 6fb9479..15247e8 100644 --- a/doc/1_firstbot.md +++ b/doc/1_firstbot.md @@ -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-0-gc001d14 +#### $$VERSION$$ v0.6-rc1-6-ge18b200 diff --git a/doc/2_usage.md b/doc/2_usage.md index d00e7af..b0926d7 100644 --- a/doc/2_usage.md +++ b/doc/2_usage.md @@ -83,8 +83,37 @@ Evertime a Message is recieved, you can read incoming data using the following v ## Usage of bashbot functions +#### sending messages +To send messages use the ```send_xxx_message``` functions. + +To send regular text without any markdown use: +```bash +send_text_message "${CHAT[ID]}" "lol" +``` +To send text with markdown: +```bash +send_markdown_message "${CHAT[ID]}" "lol *bold*" +``` +To send text with html: +```bash +send_html_message "${CHAT[ID]}" "lol bold" +``` + +To forward messages use the ```forward``` function: +```bash +forward "${CHAT[ID]}" "from_chat_id" "message_id" +``` + +If your Bot is Admin in a Chat you can delete every message, if not you can delete only your messages. +To delete a message with a known ${MESSAGE[ID]} you can simple use: +```bash +delete_message "${CHAT[ID]}" "${MESSAGE[ID]}" +``` + #### send_message -To send messages use the ```send_message``` function: +In addition there is a universal send_massage function which can output any type of message. +This function is used to process output from external scrips like interactive chats or background jobs. +**For safety and performance reasons I recommend to use send_xxxx_message functions above for sending messages** ```bash send_message "${CHAT[ID]}" "lol" ``` @@ -99,30 +128,8 @@ This function also allows a third parameter that disables additional function pa ```bash send_message "${CHAT[ID]}" "lol" "safe" ``` -To forward messages use the ```forward``` function: -```bash -forward "${CHAT[ID]}" "from_chat_id" "message_id" -``` +More examples boutsend_message strings can be found in [Advanced Usage](3_advanced.md#Interactive-Chats) -#### For safety and performance reasoms I recommend to use send_xxxx_message direct and not the universal send_message function. -To send regular text without any markdown use: -```bash -send_text_message "${CHAT[ID]}" "lol" -``` -To send text with markdown: -```bash -send_markdown_message "${CHAT[ID]}" "lol *bold*" -``` -To send text with html: -```bash -send_html_message "${CHAT[ID]}" "lol bold" -``` - -If your Bot is Admin in a Chat you can delete every message, if not you can delete only your messages. -To delete a message with a known ${MESSAGE[ID]} you can simple use: -```bash -delete_message "${CHAT[ID]}" "${MESSAGE[ID]}" -``` #### Send files, location etc. To send images, videos, voice files, photos etc. use the ```send_photo``` function (remember to change the safety Regex @ line 14 of command.sh to allow sending files only from certain directories): @@ -147,6 +154,6 @@ Allowed values: typing for text messages, upload_photo for photos, record_video send_action "${CHAT[ID]}" "action" ``` -#### $$VERSION$$ v0.6-rc1-0-gc001d14 +#### $$VERSION$$ v0.6-rc1-6-ge18b200 diff --git a/doc/3_advanced.md b/doc/3_advanced.md index 1ce1014..319e4a0 100644 --- a/doc/3_advanced.md +++ b/doc/3_advanced.md @@ -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-0-gc001d14 +#### $$VERSION$$ v0.6-rc1-6-ge18b200 diff --git a/doc/4_expert.md b/doc/4_expert.md index ea263a5..b2157fc 100644 --- a/doc/4_expert.md +++ b/doc/4_expert.md @@ -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-0-gc001d14 +#### $$VERSION$$ v0.6-rc1-6-ge18b200 diff --git a/doc/5_practice.md b/doc/5_practice.md index c388593..d98323f 100644 --- a/doc/5_practice.md +++ b/doc/5_practice.md @@ -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-3-g6be706b +#### $$VERSION$$ v0.6-rc1-6-ge18b200 diff --git a/doc/6_reference.md b/doc/6_reference.md index e5c7b3f..7e9a60e 100644 --- a/doc/6_reference.md +++ b/doc/6_reference.md @@ -2,105 +2,218 @@ ### Send, forward, delete Messages -send_action() +##### send_action +*usage:* -send_message() +*example:* -send_normal_message() +##### send_normal_message +*usage:* -send_markdown_message() +*example:* -send_html_message() +##### send_markdown_message +*usage:* + +*example:* + +##### send_html_message +*usage:* + +*example:* + +##### forward +*usage:* + +*example:* ---- -forward() +##### send_message +Send Message is only used to process the output of interactive chats an background jobs. +I reccommend to use the more dedicated send_xxx_message() functions above. + +*usage:* + +*example:* see [Usage](2_usage.md#send_message) and [Advanced Usage](3_advanced.md#Interactive-Chats) ---- -delete_message() +##### delete_message +*usage:* + +*example:* ---- -answer_inline_query() +##### answer_inline_query +*usage:* + +*example:* ---- ### File, Location, Venu, keyboards -get_file() +##### get_file +*usage:* -send_file() +*example:* -send_location() +##### send_file +*usage:* -send_venue() +*example:* + +##### send_location +*usage:* + +*example:* + +##### send_venue +*usage:* + +*example:* ---- -send_keyboard() +##### send_keyboard +*usage:* -remove_keyboard() +*example:* + +##### remove_keyboard +*usage:* + +*example:* ### Manage users -kick_chat_member() +##### kick_chat_member +*usage:* -unban_chat_member() +*example:* -leave_chat() +##### unban_chat_member +*usage:* + +*example:* + +##### leave_chat +*usage:* + +*example:* ---- -user_is_creator() +##### user_is_creator +*usage:* -user_is_admin() +*example:* -user_is_botadmin() +##### user_is_admin +*usage:* -user_is_allowed() +*example:* + +##### user_is_botadmin +*usage:* + +*example:* + +##### user_is_allowed +*usage:* + +*example:* ### Interactive and backgound jobs -startproc() +##### startproc +*usage:* -checkproc() +*example:* -killproc() +##### checkproc +*usage:* + +*example:* + +##### killproc +*usage:* + +*example:* ---- -background() +##### background +*usage:* -checkback() +*example:* -killback() +##### checkback +*usage:* + +*example:* + +##### killback +*usage:* + +*example:* ### Bashbot internal +These function are for internal use only and must not used for your bot commands. -send_text() +##### send_text +*usage:* + +*example:* ---- -JsonDecode() +##### JsonDecode +*usage:* -JsonGetString() +*example:* -JsonGetValue() +##### JsonGetString +*usage:* + +*example:* + +##### JsonGetValue +*usage:* + +*example:* ---- -get_chat_member_status() +##### get_chat_member_status +*usage:* + +*example:* ---- -process_client() +##### process_client +*usage:* -process_updates() +*example:* + +##### process_updates +*usage:* + +*example:* ---- +##### getBotName +*usage:* -inproc() +*example:* -#### $$VERSION$$ v0.6-rc1-3-g6be706b +##### inproc +*usage:* + +*example:* + +#### $$VERSION$$ v0.6-rc1-6-ge18b200