telegram-bot-bash/doc/2_usage.md
Kay Marquardt (Gnadelwartz) 13d15f453c doc: remove old stuff
2020-12-29 10:18:41 +01:00

14 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.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

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 string true: 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_messagefunctions. 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 forwardfunction:

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_photofunction (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_keyboardfunction:

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_locationfunction:

send_location "${CHAT[ID]}" "Latitude" "Longitude"

To send venues use the send_venuefunction:

send_venue "${CHAT[ID]}" "Latitude" "Longitude" "Title" "Address" "optional foursquare id"

To send a chat action use the send_actionfunction. 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$$ v1.21-dev-28-g43f5536