telegram-bot-bash/doc/2_usage.md

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

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

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:

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

Prev Create Bot

Next Advanced Usage

$$VERSION$$ v1.52-1-g0dae2db