16 KiB
Home
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 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 for more information.
To use the functions provided in this script in other scripts simply source bashbot: source bashbot.sh source. see 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 # bashbots JSON parser, see https://github.com/dominictarr/JSON.sh
│
├── 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
│ ├── jsshDB.sh # read and store JSON.sh style JSON, mandatory
│ ├── background.sh # interactive and background functions
│ ├── chatMember.sh
│ └── sendMessage.sh # main 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
│ └── xxxxxage.sh
│
├── 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:
./bashbot.sh start
./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:
bin/bashbot_stats.sh
To send a broadcast to all of users that ever used the bot run the following command:
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:
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:
bin/send_edit_message.sh "CHAT[ID]" "12345" "Done!"
["OK"] "true"
["ID"] "12345"
To send a file to one user or chat run the following command:
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.
Regular Messages
These Variables are always present in regular messages:
${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 CaptionsMESSAGE[DICE]: Animated DICE Emoji DICE values is contained inMESSAGE[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 thepathon 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 usedownload_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 regular messages not itended for end users, instead they signal special events to the client, e.g. new users.
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".
$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 usedownload_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 used for interaction with the user, they contain the following variables only:
${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
Callback button messages
Callback button messages special messages swedn 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.
BOTSENT array
$BOTSENT: This array contains the parsed results from the last transmission to telegram.${BOTSENT[OK]}: contains the stringtrue: 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:
send_normal_message "${CHAT[ID]}" "lol"
To send text with markdown:
send_markdown_message "${CHAT[ID]}" "lol *bold*"
To send text with html:
send_html_message "${CHAT[ID]}" "lol <b>bold</b>"
To forward messages use the forward function:
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:
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
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:
send_message "${CHAT[ID]}" "markdown_parse_mode lol *bold*"
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):
send_message "${CHAT[ID]}" "lol" "safe"
See also Interactive chats
Send files, locations, keyboards.
To send local files or URL's (photo, video, voice, sticker, documents) use the send_file function.
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:
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:
send_location "${CHAT[ID]}" "Latitude" "Longitude"
To send venues use the send_venue function:
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.
send_action "${CHAT[ID]}" "action"
See also Bashbot function reference