14 KiB
Home
Getting Started
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 for more information.
Once you're done with editing start the Bot with ./bashbot.sh start. To stop the Bot run ./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.sh.clean # copy to "mycommands.sh" if you start developing your 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
│ ├── send_message.sh # send message to given chat
│ ├── edit_message.sh # replace given message id in given chat
│ ├── send_broadcast.sh # send message to all known chats
│ ├── send_file.sh # send file to given chat
│ ├── bashbot_stats.sh # does what it says ...
│ │
│ └── bashbot_env.inc.sh # bashbot location included from scripts, adapt if needed
│
├── 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/
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 Message is received, you can read incoming data using the following variables:
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:
$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
$CAPTION: Picture, Audio, Video, File Captions$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
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
${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 small, non regular 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
Send Message Results
BOTSENT is set on every send_xxx action and only valid until next send action. For more on message results see.
Advanced Usage
$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
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 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):
send_file "${CHAT[ID]}" "/home/user/doge.jpg" "Lool"
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