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

#### [Home](../README.md)
## 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](5_practice.md) 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](7_develop.md) for more information.

To use the functions provided in this script in other scripts simply source bashbot: `source bashbot.sh source`. see [Expert Use](8_expert.md#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:
```bash
./bashbot.sh start
```
```bash
./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:

```bash
bin/bashbot_stats.sh
```

To send a broadcast to all of users that ever used the bot run the following command:

```bash
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:

```bash
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:

```bash
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:

```bash
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:
```bash
send_normal_message "${CHAT[ID]}" "lol"
```
To send text with markdown:
```bash
send_markdown_message "${CHAT[ID]}" "lol *bold*"
```
To send text with html:
```bash
send_html_message "${CHAT[ID]}" "lol <b>bold</b>"
```

To forward messages use the `forward` function:
```bash
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:
```bash
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**
```bash
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:
```bash
send_message "${CHAT[ID]}" "markdown_parse_mode lol *bold*"
```
```bash
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):
```bash
send_message "${CHAT[ID]}" "lol" "safe"
```
**See also [Interactive chats](3_advanced.md#Interactive-Chats)**


#### Send files, locations, keyboards.
To send local files or URL's (photo, video, voice, sticker, documents) use the `send_file` function.
```bash
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:
```bash
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:
```bash
send_location "${CHAT[ID]}" "Latitude" "Longitude"
```
To send venues use the `send_venue` function:
```bash
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.
```bash
send_action "${CHAT[ID]}" "action"
```
**See also [Bashbot function reference](6_reference.md#Interactive_Chats)**

#### [Prev Create Bot](1_firstbot.md)
#### [Next Advanced Usage](3_advanced.md)

#### $$VERSION$$ v1.5-0-g8adca9b