telegram-bot-bash/doc/2_usage.md

303 lines
13 KiB
Markdown
Raw Normal View History

2019-05-16 14:43:44 +00:00
#### [Home](../README.md)
2020-06-23 14:11:45 +00:00
## Getting Started
2019-05-16 14:43:44 +00:00
2019-05-25 12:06:41 +00:00
The Bots standard commands are in the commands dispatcher ```commands.sh```, Do not edit this file! Add your commands and functions to ```mycommands.sh```. In 'mycommands.sh.dist' you find examples how to add own commands and overwrite existing ones. See [Best practices](5_practice.md) for more information.
2019-05-16 14:43:44 +00:00
2020-07-28 07:14:57 +00:00
Once you're done with editing start the Bot with ```./bashbot.sh start```. To stop the Bot run ```./bashbot.sh stop```
2019-05-16 14:43:44 +00:00
If something doesn't work as expected, debug with ```./bashbot.sh startbot DEBUG &```, where DEBUG can be 'debug', 'xdebug' or 'xdebugx'.
2019-05-16 14:43:44 +00:00
See [Bashbot Development](7_develop.md) for more information.
To use the functions provided in this script in other scripts simply source bashbot: ```source bashbot.sh source```. see [Expert Use](8_expert.md#Expert-use)
2019-05-16 14:43:44 +00:00
Have FUN!
2019-05-25 12:06:41 +00:00
----
2019-05-24 14:49:11 +00:00
### Files
```
.
2020-06-07 12:32:18 +00:00
├── mycommands.sh # THIS is your bot, place logic and commands here!
2020-05-14 13:47:04 +00:00
2020-06-23 14:35:50 +00:00
├── mycommands.sh.clean # copy to "mycommands.sh" if you start developing your bot
2020-06-07 12:32:18 +00:00
├── mycommands.sh.dist # example bot, also used for testing bashbot internally
2020-05-14 13:47:04 +00:00
2020-06-07 12:32:18 +00:00
├── count.jssh # count bashbot usage in jssh key-value store
├── blocked.jssh # list of blocked USER[ID] in jssh key-value store
2020-06-07 12:32:18 +00:00
├── bashbot.sh # main bashbot script - DO NOT EDIT!
├── commands.sh # command dispatcher - DO NOT EDIT!
├── JSON.sh # bashbots JSON parser, see https://github.com/dominictarr/JSON.sh
2020-06-07 12:32:18 +00:00
├── scripts # place your bashbot interactive and background scripts here
│   └── interactive.sh.clean # interactive script template for new scripts
2019-05-24 14:49:11 +00:00
2020-06-18 14:20:42 +00:00
├── logs # here you'll find BASHBOT, ERROR, DEBUG and MESSAGE.log
2020-06-07 12:32:18 +00:00
├── modules # optional functions, sourced by commands.sh
│   ├── aliases.sh # to disable modules rename them xxx.sh.off
2019-05-24 14:49:11 +00:00
│   ├── answerInline.sh
2020-06-23 14:35:50 +00:00
│   ├── jsshDB.sh # read and store JSON.sh style JSON, mandatory
2020-06-07 12:32:18 +00:00
│   ├── background.sh # interactive and background functions
2019-05-24 14:49:11 +00:00
│   ├── chatMember.sh
2020-06-07 12:32:18 +00:00
│   └── sendMessage.sh # main send message functions, mandatory
2019-05-24 14:49:11 +00:00
2020-06-23 14:35:50 +00:00
├── addons # optional addons, disabled by default
2020-06-07 12:32:18 +00:00
│   ├── example.sh # to enable addons change their XXX_ENABLE to true
│   ├── antiFlood.sh # simple addon taking actions based on # files and text sent to chat
2019-05-25 12:06:41 +00:00
│   └── xxxxxage.sh
├── bashbot.rc # start/stop script if you run bashbot as service
2019-05-24 14:49:11 +00:00
2020-06-07 12:32:18 +00:00
├── examples # example scripts and configs for bashbot
│   ├── README.md # description of files and examples
│   ├── bash2env.sh # script to convert shebang to /usr/bin/env, see [Security Considerations](../README.md#Security-Considerations)
│   └── bashbot.cron # example crontab
2019-05-24 14:49:11 +00:00
2020-06-29 12:55:08 +00:00
├── doc # Documentation and License
2019-05-24 14:49:11 +00:00
├── html
├── LICENSE
├── README.html
├── README.md
└── README.txt
```
----
## Managing your Bot
2019-05-16 14:43:44 +00:00
#### Note: running bashbot as root is highly danger and not recommended. See Expert use.
### Start / Stop
Start or Stop your Bot use the following commands:
```bash
./bashbot.sh start
```
```bash
./bashbot.sh stop
2019-05-16 14:43:44 +00:00
```
### User stats
2020-05-14 13:47:04 +00:00
To count the total number of users and messages run the following command:
```
./bashbot.sh stats
2019-05-16 14:43:44 +00:00
```
### Sending broadcasts to all users
To send a broadcast to all of users that ever used the bot run the following command:
```
./bashbot.sh broadcast "Hey! I just wanted to let you know that the bot's been updated!"
2019-05-16 14:43:44 +00:00
```
2019-05-24 14:49:11 +00:00
----
2020-06-23 14:11:45 +00:00
## Receive data
Evertime a Message is received, you can read incoming data using the following variables:
2019-05-16 14:43:44 +00:00
### Regular Messages
2020-06-17 06:38:44 +00:00
These Variables are always present in regular messages:
* ```${MESSAGE}```: Current message text
2019-05-16 14:43:44 +00:00
* ```${MESSAGE[ID]}```: ID of current message
* ```$USER```: This array contains the First name, last name, username and user id of the sender of the current message.
* ```${USER[ID]}```: User id
* ```${USER[FIRST_NAME]}```: User's first name
* ```${USER[LAST_NAME]}```: User's last name
* ```${USER[USERNAME]}```: Username
* ```$CHAT```: This array contains the First name, last name, username, title and user id of the chat of the current message.
* ```${CHAT[ID]}```: Chat id
* ```${CHAT[FIRST_NAME]}```: Chat's first name
* ```${CHAT[LAST_NAME]}```: Chat's last name
* ```${CHAT[USERNAME]}```: Username
* ```${CHAT[TITLE]}```: Title
* ```${CHAT[TYPE]}```: Type
* ```${CHAT[ALL_MEMBERS_ARE_ADMINISTRATORS]}```: All members are administrators (true if true)
2020-06-17 06:38:44 +00:00
The following variables are set if the message contains optional parts:
2020-06-23 14:35:50 +00:00
* ```$REPLYTO```: Original message which was replied to
2019-05-16 14:43:44 +00:00
* ```$REPLYTO```: This array contains the First name, last name, username and user id of the ORIGINAL sender of the message REPLIED to.
2020-06-23 14:35:50 +00:00
* ```${REPLYTO[ID]}```: ID of message which was replied to
2019-05-16 14:43:44 +00:00
* ```${REPLYTO[UID]}```: Original user's id
* ```${REPLYTO[FIRST_NAME]}```: Original user's first name
* ```${REPLYTO[LAST_NAME]}```: Original user's' last name
* ```${REPLYTO[USERNAME]}```: Original user's username
* ```$FORWARD```: This array contains the First name, last name, username and user id of the ORIGINAL sender of the FORWARDED message.
* ```${FORWARD[ID]}```: Same as MESSAGE[ID] if message is forwarded
* ```${FORWARD[UID]}```: Original user's id
* ```${FORWARD[FIRST_NAME]}```: Original user's first name
* ```${FORWARD[LAST_NAME]}```: Original user's' last name
* ```${FORWARD[USERNAME]}```: Original user's username
2020-06-17 06:38:44 +00:00
* ```$CAPTION```: Picture, Audio, Video, File Captions
2019-05-16 14:43:44 +00:00
* ```$URLS```: This array contains documents, audio files, voice recordings and stickers as URL.
* ```${URLS[AUDIO]}```: Audio files
* ```${URLS[VIDEO]}```: Videos
* ```${URLS[PHOTO]}```: Photos (maximum quality)
* ```${URLS[VOICE]}```: Voice recordings
* ```${URLS[STICKER]}```: Stickers
* ```${URLS[DOCUMENT]}```: Any other file
* ```$CONTACT```: This array contains info about contacts sent in a chat.
* ```${CONTACT[ID]}```: User id
* ```${CONTACT[NUMBER]}```: Phone number
* ```${CONTACT[FIRST_NAME]}```: First name
* ```${CONTACT[LAST_NAME]}```: Last name
* ```${CONTACT[VCARD]}```: User's complete Vcard
* ```$LOCATION```: This array contains info about locations sent in a chat.
* ```${LOCATION[LONGITUDE]}```: Longitude
* ```${LOCATION[LATITUDE]}```: Latitude
* ```$VENUE```: This array contains info about venue (a place) sent in a chat.
* ```${VENUE[TITLE]}```: Name of the place
* ```${VENUE[ADDRESS]}```: Address of the place
* ```${VENUE[LONGITUDE]}```: Longitude
* ```${VENUE[LATITUDE]}```: Latitude
* ```${VENUE[FOURSQUARE]}```: Fouresquare ID
2020-06-17 06:38:44 +00:00
### Service Messages
Service Messages are regular messages not itended for end users, instead they signal special events to the
client, e.g. new users.
2020-06-23 14:11:45 +00:00
If a service message is received bashbot sets MESSAGE to the service message type as a command,
e.g. if a new user joins a chat MESSAGE is set to "/_new_chat_user".
2020-06-17 06:38:44 +00:00
2020-06-23 14:35:50 +00:00
* ```$SERVICE```: This array contains info about received service messages.
2020-06-17 06:38:44 +00:00
* ```${SERVICE}```: "yes" if service message is received
2020-06-29 13:39:03 +00:00
* ```${SERVICE[NEWMEMBER]}}```: New user's id
* ```${MESSAGE}```: /_new_chat_member ID NAME
2020-06-29 13:39:03 +00:00
* ```${NEWMEMBER[ID]}```: New user's id
* ```${NEWMEMBER[FIRST_NAME]}```: New user's first name
* ```${NEWMEMBER[LAST_NAME]}```: New user's last name
* ```${NEWMEMBER[USERNAME]}```: New user's username
* ```${NEWMEMBER[ISBOT]}```: New user is a bot
* ```${SERVICE[LEFTMEMBER]}```: Id of user left
* ```${MESSAGE}```: /_left_chat_member ID NAME
2020-06-29 13:39:03 +00:00
* ```${LEFTMEMBER[ID]}```: Left user's id
* ```${LEFTMEMBER[FIRST_NAME]}```: Left user's first name
* ```${LEFTMEMBER[LAST_NAME]}```: Left user's last name
* ```${LEFTMEMBER[USERNAME]}```: Left user's username
* ```${LEFTMEMBER[ISBOT]}```: Left user is a bot
* ```${SERVICE[NEWTITLE]}```: Text of new title
* ```${MESSAGE}```: /_new_chat_title SENDER TEXT
2020-06-29 13:39:03 +00:00
* ```${SERVICE[NEWPHOTO]}```: New Chat Picture
* ```${MESSAGE}```: /_new_chat_picture SENDER URL
2020-12-13 11:00:18 +00:00
* ```${SERVICE[PINNED]}```: Pinned MESSAGE ID
* ```${MESSAGE}```: /_new_pinned_message SENDER ID
2020-06-29 12:55:08 +00:00
* ```${PINNED[ID]}```: Id of pinned message
* ```${PINNED[MESSAGE]}```: Message text of pinned message
2020-12-13 11:00:18 +00:00
* ```${SERVICE[MIGRATE]}```: Old and new group id
* ```${MESSAGE}```: /_migrate_group MIGRATE_FROM MIGRATE_TO
2020-12-13 11:00:18 +00:00
* ```${MIGRATE[FROM]}```: Old group id
* ```${MIGRATE[TO]}```: New group id
2020-05-14 13:47:04 +00:00
2020-06-17 06:38:44 +00:00
### Inline query messages
2020-05-14 13:47:04 +00:00
2020-06-17 06:38:44 +00:00
Inline query messages are small, non regular messages used for interaction with the user,
2020-06-23 14:35:50 +00:00
they contain the following variables only:
2019-05-16 14:43:44 +00:00
* ```${iQUERY}```: Current inline query
* ```$iQUERY```: This array contains the ID, First name, last name, username and user id of the sender of the current inline query.
* ```${iQUERY[ID]}```: Inline query ID
* ```${iQUERY[USER_ID]}```: User's id
* ```${iQUERY[FIRST_NAME]}```: User's first name
* ```${iQUERY[LAST_NAME]}```: User's last name
2020-12-07 17:29:37 +00:00
### Send Message Results
2020-12-07 17:34:23 +00:00
BOTSENT is set on every send_xxx action and only valid until next send action. For more on message results see.
2020-12-07 17:29:37 +00:00
[Advanced Usage](3_advanced.md)
* ```$BOTSENT```: This array contains the parsed results from the last transmission to telegram.
* ```${BOTSENT[OK]}```: contains the string ```true```: after a successful transmission
* ```${BOTSENT[ID]}```: Message ID of sent message, image, file etc., if OK is true
2019-05-16 14:43:44 +00:00
## 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 <b>bold</b>"
```
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
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"
```
To send html or markdown put the following strings before the text, depending on the parsing mode you want to enable:
```bash
send_message "${CHAT[ID]}" "markdown_parse_mode lol *bold*"
```
```bash
send_message "${CHAT[ID]}" "html_parse_mode lol <b>bold</b>"
```
This function also allows a third parameter that disables additional function parsing (for safety use this when reprinting user input):
```bash
send_message "${CHAT[ID]}" "lol" "safe"
```
**See also [Interactive chats](3_advanced.md#Interactive-Chats)**
#### Send files, locations, keyboards.
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):
```bash
send_file "${CHAT[ID]}" "/home/user/doge.jpg" "Lool"
```
To send custom keyboards use the ```send_keyboard``` function:
```bash
2020-06-23 14:35:50 +00:00
send_keyboard "${CHAT[ID]}" "Text that will appear in chat?" '[ "Yep" , "No" ]' # note the single quotes!
send_keyboard "${CHAT[ID]}" "Text that will appear in chat?" "[ \\"Yep\\" , \\"No\\" ]" # within double quotes you must escape the inside double quots
2019-05-16 14:43:44 +00:00
```
To send locations use the ```send_location``` function:
```bash
send_location "${CHAT[ID]}" "Latitude" "Longitude"
```
To send venues use the ```send_venue``` function:
```bash
send_venue "${CHAT[ID]}" "Latitude" "Longitude" "Title" "Address" "optional foursquare id"
```
To send a chat action use the ```send_action``` function.
Allowed values: typing for text messages, upload_photo for photos, record_video or upload_video for videos, record_audio or upload_audio for audio files, upload_document for general files, find_location for locations.
```bash
send_action "${CHAT[ID]}" "action"
```
**See also [Bashbot function reference](6_reference.md#Interactive_Chats)**
#### [Prev Create Bot](1_firstbot.md)
#### [Next Advanced Usage](3_advanced.md)
#### $$VERSION$$ v1.2-dev2-5-gda7a3f1
2019-05-16 14:43:44 +00:00