397 lines
17 KiB
Markdown
397 lines
17 KiB
Markdown
#### [Home](../README.md)
|
|
## Getting Started
|
|
|
|
The Bots default commands are in `commands.sh`. Do not edit this file! Instead copy `mycommands.sh.clean` to `mycommands.sh` and place you commands there.
|
|
Have a look at `mycommands.sh.dist` for examples on how to write commands or overwrite existing ones. See [Best practices](5_practice.md) for more information.
|
|
|
|
Once you're done with editing run the Bot with `./bashbot.sh start`. To stop running the Bot use `./bashbot.sh stop`
|
|
|
|
If something doesn't work as expected, debug with `./bashbot.sh startbot DEBUG &`, where DEBUG can be 'debug', 'xdebug' or 'xdebugx'.
|
|
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)
|
|
|
|
Have FUN!
|
|
|
|
----
|
|
|
|
### Files
|
|
```
|
|
.
|
|
├── mycommands.sh # THIS is your bot, place logic and commands here!
|
|
├── mycommands.conf # place your bot config and bot messages here!
|
|
│
|
|
├── mycommands.conf.dist # copy to "mycommands.conf" if not exist
|
|
├── mycommands.sh.clean # copy to "mycommands.sh" to start developing a new bot
|
|
├── mycommands.sh.dist # example bot, also used for testing bashbot internally
|
|
│
|
|
├── count.jssh # count bashbot usage in jssh key-value store
|
|
├── blocked.jssh # list of blocked USER[ID] in jssh key-value store
|
|
│
|
|
├── bashbot.sh # main bashbot script - DO NOT EDIT!
|
|
├── commands.sh # command dispatcher - DO NOT EDIT!
|
|
├── JSON.sh # bashbot JSON parsers
|
|
│ ├── JSON.sh # sh implementation, https://github.com/dominictarr/JSON.sh
|
|
│ └── JSON.awk.dist # faster awk version, https://github.com/step-/JSON.awk
|
|
│
|
|
├── bin # ready to use scripts, use `scriptname --help` for help
|
|
│ ├── bashbot_stats.sh # does what it says ...
|
|
│ ├── send_broadcast.sh # send message to all known chats
|
|
│ ├── send_message.sh # send message to given chat
|
|
│ ├── edit_message.sh # replace given message id in given chat
|
|
│ ├── send_file.sh # send file to given chat
|
|
│ ├── delete_message.sh # delete given message id in given chat
|
|
│ ├── send_buttons.sh # send message with attached button
|
|
│ ├── edit_buttons.sh # attach/edit message buttons
|
|
│ ├── kickban_user.sh # kick/unban user from given chat
|
|
│ ├── promote_user.sh # promote/dente user rights in given chat
|
|
│ │
|
|
│ ├── bashbot_env.inc.sh # sourced from scripts, adapt locations if needed
|
|
│ └── bashbot_init.inc.sh # sourced from bashbot.sh init
|
|
│
|
|
├── scripts # place your bashbot interactive and background scripts here
|
|
│ └── interactive.sh.clean # interactive script template for new scripts
|
|
│
|
|
├── logs # here you'll find BASHBOT, ERROR, DEBUG and MESSAGE.log
|
|
│
|
|
├── modules # optional functions, sourced by commands.sh
|
|
│ ├── aliases.sh # to disable modules rename them xxx.sh.off
|
|
│ ├── answerInline.sh
|
|
│ ├── background.sh # interactive and background functions
|
|
│ ├── chatMember.sh # manage chat mambers
|
|
│ ├── jsshDB.sh # read and store JSON.sh style JSON, mandatory
|
|
│ ├── processUpdates.sh # process updates from telegram, mandatory (run bot)
|
|
│ └── sendMessage.sh # send message functions, mandatory
|
|
│
|
|
├── addons # optional addons, disabled by default
|
|
│ ├── 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
|
|
│
|
|
├── bashbot.rc # start/stop script if you run bashbot as service
|
|
│
|
|
├── 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
|
|
│
|
|
├── doc # Documentation and License
|
|
├── html
|
|
├── LICENSE
|
|
├── README.html
|
|
├── README.md
|
|
└── README.txt
|
|
|
|
```
|
|
|
|
----
|
|
|
|
## Managing your Bot
|
|
#### 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
|
|
```
|
|
|
|
### Scripts in bin/
|
|
Use `script.sh -h` or `script --help` to get short/long help for script.
|
|
|
|
To count the total number of users and messages run the following command:
|
|
|
|
```bash
|
|
bin/bashbot_stats.sh
|
|
```
|
|
|
|
To send a broadcast to all of users that ever used the bot run the following command:
|
|
|
|
```bash
|
|
bin/send_broadcast.sh "Hey, I just wanted to let you know that the bot's been updated!"
|
|
|
|
Sending broadcast message to all users of Deal_O_Mat_bot
|
|
DRY RUN! use --doit as first argument to execute broadcast...
|
|
...
|
|
Message "Hey, ..." sent to xxx users.
|
|
```
|
|
|
|
To send a message to one user or chat run the following command:
|
|
|
|
```bash
|
|
bin/send_message.sh "CHAT[ID]" "Hey, I just wanted to let you know that the bot's been updated!"
|
|
|
|
["OK"] "true"
|
|
["ID"] "12345"
|
|
```
|
|
|
|
To replace a message already sent to one user or chat run the following command:
|
|
|
|
```bash
|
|
bin/edit_message.sh "CHAT[ID]" "12345" "Done!"
|
|
|
|
["OK"] "true"
|
|
["ID"] "12345"
|
|
```
|
|
|
|
To send a file to one user or chat run the following command:
|
|
|
|
```bash
|
|
bin/send_file.sh "CHAT[ID]" "funny-pic.jpg" "enjoy this picture"
|
|
|
|
["OK"] "true"
|
|
["ID"] "12346"
|
|
```
|
|
|
|
Note: to get help about a script in bin/ run `scriptname.sh --help`
|
|
|
|
----
|
|
|
|
## Receive data
|
|
Evertime a Telegram update is received, you can read incoming data using the following variables:
|
|
In case you need other update values, the array `UPD` contains complete Telegram response.
|
|
|
|
### Processing Messages
|
|
|
|
If an update is received from Telegram, the message is pre processed by Bashbot and the following bash variables are set for use in `mycommands.sh`.
|
|
|
|
These variables are always present if a message is pre processed:
|
|
|
|
* `${ME}`: Name of your bot
|
|
* `${BOTADMIN}`: User id of bot administrator
|
|
|
|
* `${MESSAGE}`: Current message text
|
|
* `${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)
|
|
|
|
The following variables are set if the message contains optional parts:
|
|
|
|
* `MESSAGE[CAPTION]`: Picture, Audio, Video, File Captions
|
|
* `MESSAGE[DICE]`: Animated DICE Emoji DICE values is contained in `MESSAGE[RESULT]`
|
|
* `$REPLYTO`: Original message which was replied to
|
|
* `$REPLYTO`: This array contains the First name, last name, username and user id of the ORIGINAL sender of the message REPLIED to.
|
|
* `${REPLYTO[ID]}`: ID of message which was replied to
|
|
* `${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
|
|
* `$URLS`: This array contains the `path` on Telegram server for files send to chat, e.g. photo, video, audio file.
|
|
* `${URLS[AUDIO]}`: Path to audio file
|
|
* `${URLS[VIDEO]}`: Path to video
|
|
* `${URLS[PHOTO]}`: Path to photo (maximum quality)
|
|
* `${URLS[VOICE]}`: Path to voice recording
|
|
* `${URLS[STICKER]}`: Path to sticker
|
|
* `${URLS[DOCUMENT]}`: Path to any other file
|
|
**Important:** This is NOT a full URL, you must use `download_file "${URLS[xxx]}"` or prefix path with telegram api url for manual download
|
|
(_e.g. `getJson "${URL}/${URLS[xxx]}" >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
|
|
|
|
|
|
### Service Messages
|
|
|
|
Service Messages are updates not itended for end users, instead they signal special events in a chat, e.g. new users.
|
|
|
|
If a service message is received bashbot pre processing sets `${MESSAGE}` according to the service message type,
|
|
e.g. if a new user joins a chat MESSAGE is set to `/_new_chat_user ...`.
|
|
|
|
* `$SERVICE`: This array contains info about received service messages.
|
|
* `${SERVICE}`: "yes" if service message is received
|
|
* `${SERVICE[NEWMEMBER]}}`: New user's id
|
|
* `${MESSAGE}`: /_new_chat_member ID NAME
|
|
* `${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
|
|
* `${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
|
|
* `${SERVICE[NEWPHOTO]}`: New Chat Picture
|
|
* `${MESSAGE}`: /_new_chat_picture SENDER URL
|
|
**Important:** SERVICE[NEWPHOTO] is NOT a full URL, you must use `download_file "${SERVICE[NEWPHOTO]}"` or prefix path with telegram api url for manual download
|
|
(_e.g. `getJson "${FILEURL}/${SERVICE[NEWPHOTO]}" >file`_).
|
|
* `${SERVICE[PINNED]}`: Pinned MESSAGE ID
|
|
* `${MESSAGE}`: /_new_pinned_message SENDER ID
|
|
* `${PINNED[ID]}`: Id of pinned message
|
|
* `${PINNED[MESSAGE]}`: Message text of pinned message
|
|
* `${SERVICE[MIGRATE]}`: Old and new group id
|
|
* `${MESSAGE}`: /_migrate_group MIGRATE_FROM MIGRATE_TO
|
|
* `${MIGRATE[FROM]}`: Old group id
|
|
* `${MIGRATE[TO]}`: New group id
|
|
|
|
|
|
|
|
### Inline query messages
|
|
Inline query messages are special messages for direct interaction with your bot.
|
|
If an user starts an inline conversation an inline query is sent after each user keystroke.
|
|
|
|
To receive inline messages you must set `inline=1` in `mycommands.conf` and in botfather.
|
|
THe message contatains all characters so far typed from the user.
|
|
|
|
An received inline query must be anserwered with `answer_inline_query`, see also (Inline Query)[6_reference.md#inline-query]
|
|
|
|
If an inline query is received only the following variables are available:
|
|
|
|
* `${iQUERY}`: Inline message typed so far by user
|
|
* `$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
|
|
|
|
|
|
|
|
### Callback button messages
|
|
Callback button messages special messages swend from callback buttons, they contain the following variables only:
|
|
|
|
* `$iBUTTON`: This array contains the ID, First name, last name, username and user id of the user clicked on the button
|
|
* `${iBUTTON[ID]}`: Callback query ID
|
|
* `${iBUTTON[DATA]`: Data attached to button, hopefully unique
|
|
* `${iBUTTON[CHAT_ID]`: Chat where button was pressed
|
|
* `${iBUTTON[MESSAGE_ID]`: Message to which button is attached
|
|
* `${iBUTTON[MESSAGE]`: Text of message
|
|
* `${iBUTTON[USER_ID]}`: User's id
|
|
* `${iBUTTON[FIRST_NAME]}`: User's first name
|
|
* `${iBUTTON[LAST_NAME]}`: User's last name
|
|
* `${iBUTTON[USERNAME]}`: User's @username
|
|
|
|
|
|
## Send data / get response
|
|
|
|
After every `send_xxx` `get_xxx` call the array BOTSENT contains the most important values from Telegram response.
|
|
In case you need other response values , the array `UPD` contains complete Telegram response.
|
|
|
|
You can use the array values to check if a commands was successful and get returned values from Telegram.
|
|
|
|
### BOTSENT array
|
|
|
|
* `$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
|
|
* `${BOTSENT[FILE_ID]}`: unique identifier returned for an uploaded file or URL
|
|
* `${BOTSENT[FILE_TYPE]}`: file type: photo, audio, video, sticker, voice, document
|
|
|
|
|
|
|
|
## Usage of bashbot functions
|
|
|
|
#### sending messages
|
|
To send messages use the `send_xxx_message` functions.
|
|
To insert line brakes in a message place `\n` in the text.
|
|
|
|
To send regular text without any markdown use:
|
|
```bash
|
|
send_normal_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 local files or URL's (photo, video, voice, sticker, documents) use the `send_file` function.
|
|
```bash
|
|
send_file "${CHAT[ID]}" "/home/user/dog.jpg" "Lool" "photo"
|
|
send_file "${CHAT[ID]}" "https://images-na.ssl-images-amazon.com/images/I/81DQ0FpoSNL._AC_SL1500_.jpg"
|
|
```
|
|
To send custom keyboards use the `send_keyboard` function:
|
|
```bash
|
|
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
|
|
```
|
|
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.51-0-g6e66a28
|
|
|