(EN) Quick start for service owners

Heartfelt thanks for choosing to use booking bot by zweb, the Telegram bot that simplifies bookings of spaces and services for temporary rental.

This guide is designed to provide an overview of the bot's features and the ways of interacting with it. Enjoy the reading.

This guide is related to the software version R34

Functionality

Below is a list with a brief description of what the Zweb Booking Bot application offers. With this bot you can:

book a service of your choice among various hourly services;
choose a day of the week for booking - normally up to 2 weeks away from 'today';
view a list of available times divided by customized time intervals;
choose the duration of your reservation;
view the list of your active reservations;
cancel your own reservation;
view an information content, typically containing the description, conditions and prices related to the service;
receive a pro-forma ticket containing the main information of your reservation;
if activated by the bot settings, register with your Telegram phone and full name, and then you'll have the option to book;
view the map position (in Telegram location format) of the structure;

For the service manager

In addition to all previous features, the service manager can also:

send reservation schedules to their Google Calendar;
create virtual services, that is services that depend on another service declared as 'parent' and sharing the same timetable: this may come in very handy when you want to differentiate services that use a shared asset (a person, a room, etc.);
create rules to establish one or more specific operating time slots for a single day of the week (i.e. operating shifts), including rules that become valid starting from some hours in the future (this can now be configured); each rule remains valid until it is set again: the last one inserted and valid in the present has priority for that day of the week;
view all active rules for operating hours;
retrieve, in .xlsx format (Microsoft Excel), a reservation table based on quantity of reservations, or by specifying a month and year, or retrieve only the reservations that are still active (future reservations, both active or cancelled by the user);
view in monospaced text format all the currently active reservations; now buttons can be added from the configuration in order to show only reservations of a specific service;
make a fast reservation by means of a text message;
cancel someone else's reservation or edit one of theirs;
make a weekly recurring reservation;
use reserved services (i.e. available to them only);
access a full list of reservations in csv format (comma separated values, universal file format that can be opened by spreadsheet applications and simple text editors);
access the list of registered users (only if registration is active: see below)
cancel a specific registration or reservation (the latter can be done either via a text command or a button);
disable a user or enable a disabled user, either via text commands or the control panel;
promote a user to a different role, thus modifying the number of maximum reservations available for that user, either via text commands or the control panel.

The service manager will be recognized by the system automatically, based on the Telegram ID specified in the configuration file. You can now specify more than one service manager.

For the service configurator (developer) and/or manager

The manual configuration of the bot, which is generally carried out when the service is started by editing a specific configuration text file, also allows you to:

edit the text for each bot message;
choose the language for the entire bot: all messages, notifications, and special commands will be translated into the chosen language;
activate the simplified registration function to track users, so that only registered users can make a reservation;
choose whether or not to send the pro-forma ticket;
choose the maximum number of reservations per user (NOTE: the manager is not subject to this limit). It is advisable to set a low limit to prevent a user from accidentally or intentionally filling up the timetable by booking too many times;
set the map position based on geographical coordinates;
set the services available for booking;
set the world time zone, the name of the days of the week in short format (3 letters), and the date format;
set an interval of generic daily operating hours; this will be valid in the absence of rules for a specific day of the week;
set the telegram ID of the service owner/keeper;
set the names of the user commands (Telegram buttons) and those reserved for the manager;
set the maximum number of days in advance with which you can make a reservation (current hard-limit maximum: 14);
[Option available in the future] change the minimum minute interval. This however must always be a submultiple of an hour, so basically: 10, 12, 15, 20, or 30 minutes (default: 30 minutes)

Recipes and examples

Remember: the recipes text commands refer to what is in the configuration file. Changes in that file will affect the commands are written. Please read the dev guide for further details.

Q: How do I know a user made a reservation?

A: A telegram text message with user and date-time of the reservation will be sent to all keepers of the service. Prior to receive such messages, a keeper has to interact with the chat bot at least once. This is not an issue of our bot, it's Telegram anti-spam policy. You can also periodically check the active (or all the) reservations by using button or text commands.

Q: How do I create a rule to set my working shifts on a specific day of the week, such as every Tuesday, to be effective starting June 5, 2024?

A: Write in the chat text field:

.set rule Tue 09:30/13:00,15:00/22:30 2024-06-05

Normally, the days of the week are Mon, Tue, Wed, Thu, Fri, Sat, Sun. As you can see, the time intervals must be written without spaces, and separated from each other only by a comma (the system will try to prevent setting bad formatted data). You can currently put a maximum of 3 time intervals. Next, enter the year, month and date of the start of the rule (warning: this can change, if you choose another short time format), with the parts of date separated by hyphen.

Q: What if the services I offer have different operating hours (shifts)?

A: Suppose we have multiple services, and that the service with a different shift has the name court1 as short_name in the configuration. For example, write in the chat text field:

.set service rule Tue 12:00/19:30 05-06-2024 30-08-2024 court1

This will ensure that the rule for the field1 service has priority when a user books, and is used instead of the previous one (which still has general validity)

Q: What if I want a rule to be active immediately?

Just put, in the previous writing, any date in the past (before today), et voilà!

Q: I made a mistake in entering a rule. What do I do?

A. To delete the last inserted rule you can write:

.delete last rule

Warning: if this command is used multiple times, each time it will delete a rule.

Alternatively, since the last rule entered relating to a certain day of the week is the valid one, it will be sufficient to set a new one. For example, if you insert a new rule with the same day of the week and the same date, the system will use the last one inserted, ignoring all the others.

Q: How do I view all active rules for shifts this week?

A: Writing in chat:

.show active shifts

Q: How do I retrieve the last 50 reservations entered?

A: Write in the chat text field:

.get latest 50

Instead of 50, you can enter any number you prefer.

Q: How do I get active reservations right now?

A: Press the /reservations_text or /reservations_xls button in the Telegram keyboard, and you will receive them either in text or in Excel (.xlsx) format.

Q: How do I get April 2024 reservations?

A: Write in the chat text field:

.get 2024-04

First the year, then the month, separated by a hyphen.

Q: How do I recover the full archive in .csv with all inserted / canceled reservations?

A: Write in the chat text field:

.get all

Note: This file may become relatively large over time if your business volume is large. The reason why the archive is in 'csv' format is this: the file will remain smaller in size, the format is universal, and the system will update it with each booking and cancellation, keeping it ready in case you request it.

Q: How do I cancel a specific reservation? I can't accept it!

A: First of all, recover the reservations with one of the methods already seen. Write down the value in the rid field of that reservation line. Then write in chat:

.cancel 1234, replacing "1234" with the corresponding rid. Attention: this operation cannot be canceled unless you make the same reservation again!

Note: For privacy reasons, the bot cannot notify the user that their reservation has been cancelled: it would be kind of you to write to him and tell him!

Q: How do I retrieve the list of registered users in Excel format?

A: Write in the chat text field:

.get users

Q: I have identified a fraudulent user: how can I block him?

A: First retrieve the users as written above, and write down their "id". You can deactivate a specific user by writing in chat:

.disable user {id}, inserting the user's numeric id (without parentheses) in place of "{id}". If the user was already blocked, no changes will be made. Once the user is blocked, their booking process will also be blocked.

Note: If the user was making a reservation at the time they were blocked, they could still make it. From that moment, however, it will no longer be possible for him to make new ones.

Q: What if I want to readmit him?

A: Just write:

.enable user {id}, inserting the user's numeric id (without brackets) in place of "{id}", i.e. 1234. If the user was already enabled, no changes will be made.

Q: A customer asks me to book the service for two months every Monday, from 4pm to 6pm. Can I make a repeated reservation?

A. From version 0.20Beta, this is only possible for the manager, on a weekly basis. Let's say the first Monday is April 22, 2024 and the service has the short_name "Gym2" (check the config file, under the property services, and for each service choose a short_name of your liking). Every Monday for two months means at least 8 bookings. We will use the following command:

.book 8 times 22-04-2024 16:00/18:00 Gym2

Q: A customer calls me and wants to make a reservation. How do I add it to the bot?

A. You simply have to write a message line containing all the necessary data for the reservation, including a name at the end of the message. This name will help you remind of the reservation, yet the system will also store the keepers' telegram id, so that you'll know that you booked on someone else's behalf. Example of fast reservation:

.b 2024-06-20 18:00/20:00 Gym2 John Doe

Please note that:

the name at the end can have whatever length and structure, however, due to the table-like structure of the bot text messages, only the first 20 characters will be shown when you get all active reservations in text format;
the example 'Gym2' is the name you put in the configuration file under the property "short_name": this is kind of a short codename indicating which service was chosen; it is advisabile, as the name suggests, to keep it quite short for practical reasons (it will be also shown in the pro-forma ticket)
'.b' stands for 'booking', and ALL the text part of the commands that are NOT in curly brackets (which are parameters and have to kept as they are) can be changed to your liking!

Cheat Sheet

These are the standard text commands structures with parameters in curly braces. You don't have to put the braces when writing a command, as shown in the examples above.

Internal name of the command	Command structure with parameters
"get_all_csv"	.get all
"get_latest_excel"	.get latest {n_reservations}
"cancel_one"	.cancel {reservation_id}
"set_day_shift"	.set rule {weekday_short} {shifts} {start_time} {end_time}
"set_service_day_shift"	.set service rule {weekday_short} {shifts} {start_time} {end_time} {service_short_name}
"get_active_shifts"	.get active shifts
"get_service_shifts"	.get service shifts {service_short_name}
"delete_last_inserted_rule"	.delete last rule
"enable_registered_user"	.enable user {user_id}
"disable_registered_user"	.disable user {user_id}
"delete_registered_user"	.delete user {user_id}
"promote_user"	.promote user {user_id} {role_name}
"get_registered_users"	.get users
"reservations_by_month"	.get reservations {year_dash_month}
"multiple_reservation"	.book {x} times {yyyy_mm_dd} {time_interval} {service_short_name} {user_full_name}
"fast_reservation"	.b {yyyy_mm_dd} {time_interval} {service_short_name} {user_full_name}

Things to keep in mind!

In order to know the {user_id}, you should use a command like .get users, or get an excel formatted list of the reservations, where the user id is shown under the relative column.
Time interval has always the form hh:mm/hh:mm (without spaces in between). In order to be 100% sure that the command is going to work under any circumstances, enforce a leading zero before single digit hours (i.e. 8:30 becomes 08:30). A 'shift' is just a series of time intervals (up to 3) separated by comma.
{user_full_name} can be any series of one or more names separated by space
{yyyy_mm_dd} must should be written in the form YYYY-MM-DD, with a dash as separator between year and month, and between month and day
{weekday_short} is the short naming of a day of the week with capital first letter: Mon, Tue, Wed, Thu, Fri, Sat, Sun.

Configuration

Through further configuration parameters, it is possible to decide:

the number of hours in advance with which it is possible to book;
the number of hours, purely informative, to be able to cancel the booking without incurring penalties (if applicable);
the range of days in which it is possible to book (maximum 14, to avoid clogging the Telegram chat interface with buttons);
the maximum number of active reservations per user;
the time zone;
the text of the commands (warning: an incorrect assignment can lead to errors in the execution of the bot code);
whether to use user registration or deactivate it;
Other...

To modify these parameters, access to the web space that hosts the application code is required, with minimal programming experience. The configuration parameters allow you to customize the experience of using the chatbot, especially in the initial phase. Please consult the Dev Guide for further details.

Limitations

The software currently has some limitations to the functions just seen:

It is not possible to manage times that cross the end of the solar day, i.e. 11.59pm (as a workaround, it would be possible to move on to the following day, dividing the desired time of reservation into two reservations);
It is not possible to make payments through the bot;
It is possible to save only text information relating to the user during registration.