telegram-bot-bash/doc/2_usage.md
Kay Marquardt (Gnadelwartz) bccd064516 start dev3 - remove tmux
2019-05-18 20:25:18 +02:00

7.8 KiB

Home

Gettting Started

The Bots standard commands are in commands.sh file. You must not add your commands to 'commands.sh', instead place them in mycommands.sh, there you also find examples how to process messages and send out text. See Best practices for more information.

Once you're done with editing 'mycommands.sh' start the Bot with ./bashbot.sh start. To stop the Bot run ./bashbot.sh kill

If some thing doesn't work as it should, you can 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

Have FUN!

Managing your own Bot

Start / Stop

Start or Stop your Bot use the following commands:

./bashbot.sh start
./bashbot.sh kill

User count

To count the total number of users that ever used the bot run the following command:

./bashbot.sh count

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!"

Recieve data

Evertime a Message is recieved, you can read incoming data using the following variables:

Regular Messages

  • ${MESSAGE}: Current message
  • ${MESSAGE[ID]}: ID of current message
  • $CAPTION: Captions
  • $REPLYTO: Original message wich was replied to
  • $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)
  • $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 wich 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 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

Inline queries

Evertime a Message is recieved, you can read incoming data using the following variables:

  • ${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

Usage of bashbot functions

sending messages

To send messages use the send_xxx_message functions.

To send regular text without any markdown use:

send_text_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 simgle quotes!
send_keyboard "${CHAT[ID]}" "Text that will appear in chat?" "[ \\"Yep\\" , \\"No\\" ]" # within double quotes you must excape 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

Prev Create Bot

Next Advanced Usage

$$VERSION$$ v0.80-dev3-0-g31a5d00