Chatbot for online booking

General Information

A chatbot for online booking is a set of funnel builder functions that allow you to automate the process of scheduling services for your company.

The bot’s workflow is based on the sequential execution of functions: receiving data to display to the client, then passing this data on to trigger new functions and obtain new results.

As the client moves through the funnel, you should pass into each subsequent block only the data that corresponds to the client’s choice—use this data to configure the next function calls.

Thanks to the ability to retrieve intermediate data (for example, employee positions and service categories) and pass it along for filtering employees and services, you can flexibly configure your funnel and give the client control over the steps of its progression.

All the methods described in this article return an array of dictionaries.

For convenient work with them, we recommend reviewing the sections Arrays and Dictionaries.

Also, to use the function for generating user actions (service selection, date, booking), we suggest considering the tools_make_button_str_checker method.

Below is a diagram of the bot’s workflow, where each block of the diagram represents a specific function call, and the arrows indicate the flow of data passed from block to block. The information passed in these flows allows you to filter requested data, as well as create, cancel, or modify a booking time.

To see a detailed configuration diagram of the online booking chatbot with the functions in use, refer to the Bot Implementation Example section of this article.

Retrieving Branch Information

To create an online booking funnel and retrieve information about project branches, use the get_companies_for_booking function.

The function returns a list containing data for each branch (funnel) that has “Online Booking” enabled in its settings.

The data is provided as key-value pairs and includes the branch identifier (id), name (name), and address (address).

The function does not take any parameters.

Example of usage:

Function call within a block:

Example of returned data:

Retrieving information about positions or service categories

The function get_categories_for_booking(company_id) allows you to retrieve a list of all types of specialists or service categories for a branch.

Each item in the returned list contains an identifier (id), a name (name), and a description (description) of the position or service category. Data is represented as "key-value" pairs:

Parameters:

Parameter

Description

company_id (required)

Branch identifier, expected format — integer.

Example of usage:

Function call example in code block:

Retrieving information about employees

If you need to provide information about branch employees, use the function get_employees_for_booking.

The call will return a list of data containing the employee identifier (id), name (name), information (information), and job title (job_title).

You can also filter employees by service list, job title, or service category. To do this, pass an additional parameter in the function call: service_ids, job_title_id, or service_category_id.

Parameter order:

company_id -> service_ids -> job_title_id -> service_category_id

Parameters:

company_id (required)

Branch identifier, expected format — integer;

service_ids (optional)

Service ID or a list of service IDs, expected format — an integer or a list of integers in square brackets separated by commas, e.g., [844, 845]

job_title_id (optional)

Job title ID, expected format — integer;

service_category_id (optional)

Service category identifier, expected format — integer;

Note:

If you want to retrieve all employees of a branch, leave the values for service_ids, job_title_id, and service_category_id empty.

Call example: get_employees_for_booking(14275391)

To filter employees by a list of service IDs, pass the list as the second parameter and leave job_title_id and service_category_id empty.

Call example: get_employees_for_booking(14275391, [844, 845])

To filter employees by job title, pass the ID to the job_title_id parameter and leave service_ids and service_category_id empty.

Call example: get_employees_for_booking(14275391, “”, 1021)

To get employees providing services of a specific category, leave service_ids and job_title_id as empty strings, and pass the selected category ID to service_category_id.

Call example: get_employees_for_booking(14275391, “”, “”, 1019)

Example of usage:

Function call in a code block:

Example of returned data:

Getting information about services

To get information about the services provided by the branch, use the get_services_for_booking function.

As a result of the call, the bot will return a list containing service data. Each service entry includes an identifier (id), a name (title), a description (description), a price (price), and the service duration in minutes (duration).

You can filter the resulting list by service category, by employee, or by both service category and employee simultaneously. To do this, pass the additional parameters service_category_id and/or employee_id when calling the function.

Parameter order:

company_id -> service_category_id -> employee_id

Parameters:

company_id (required)

Branch identifier, expected format – integer;

service_category_id (optional)

Service category identifier, expected format – integer;

employee_id (optional)

Employee identifier, expected format – integer;

Note to the “Parameters” section:

If you want to retrieve all services of a branch, leave the service_category_id and employee_id values empty.

Call example: get_services_for_booking(14275391)

If you want to filter services by category and/or employee, pass the corresponding identifiers into the service_category_id and employee_id parameters. To filter by only one parameter, provide an empty string for the other one.

Calls examples:

get_services_for_booking(14275391, 1018) - service category filter;
get_services_for_booking(14275391, “”, 512978) - employee filter;
get_services_for_booking(14275391, 1018, 463665) - filtering by both parameters;

Example of usage:

Calling the function inside a block:

Example of returned data:

Getting available booking dates

After the client has selected the services for booking, they need to retrieve a list of available booking dates.

To generate this list, use the get_dates_for_booking function.

The function will check for available time slots and return a list of suitable dates in the format “day.month.year”.

The order of parameters is as follows:

company_id -> service_ids -> employee_id -> days_limit

Parameters:

company_id (required)

branch identifier, expected format – integer;

service_ids (optional)

list of service identifiers for booking, expected format – integer or a list of integers in square brackets separated by commas (e.g. 842 or [842, 843]);

employee_id (optional)

employee identifier, expected format – integer. If the parameter value is left empty or passed as an empty string “” – the function will search for available dates among all employees who provide the full set of services from the service_ids list;

days_limit (optional)

number of days from the current date within which the search for available dates is performed, expected format – integer, default value – 14 (days);

Example of usage:

Calling the function inside a block:

Example of returned data:

Getting available booking slots

To get a list of available booking slots, use the get_slots_for_booking function.

The function will check for available time on the selected date and return a list of free slots in the format “hours:minutes”, for example [“09:00”, “11:00”, “14:30”, “16:00”].

The order of parameters is as follows:

company_id -> service_ids -> employee_id -> slot_interval

Parameters:

company_id (required)

branch identifier, expected format – integer;

service_ids (optional) -

list of service identifiers for booking, expected format – integer or a list of integers (e.g. 842 or [842, 843]);

date (optional) -

date for slot checking, expected format – string in the form “day.month.year”, for example “01.01.2024”;

employee_id (optional)

employee identifier, expected format – integer. If the parameter value is left empty or passed as an empty string, the function will search for free slots in the schedules of all employees working on the selected date and providing the full set of services from the service_ids list;

slot_interval (optional)

interval in minutes between available slots, expected format – integer, default value – 30 (minutes);

Example of usage:

Function call in the block:

Example of returned data:

Creating a booking

To create an online booking, use the create_booking function.

If the booking is successful, the function will return information about the operation status (status) with the value True and the booking details (booking) in a “key: value” format.

The new booking data includes:

identifier (id),
date (booking_date),
time (booking_time),
service names (services),
booking duration(service_duration),
total cost (total_cost),
assigned employee’s name (employee_name), and his job title (job_title),
branch name (company_name) and branch address (company_address)

in a “key: value” format.

Parameter order:

company_id -> service_ids -> booking_date -> booking_time -> employee_id

Parameters:

company_id (required)

branch identifier, expected format – integer;

service_ids (required)

list of service identifiers for booking, expected format – integer or a list of integers (e.g. 5 or [5, 10, 15]);

booking_date (required)

booking date, expected format – string in the form “day.month.year”, for example “15.01.2024”;

booking_time (required)

booking time, expected format – string in the form “hours:minutes”, for example “12:30”;

employee_id (optional)

employee identifier, expected format – integer. If the parameter value is left empty or passed as an empty string “”, the function will book with a random employee who provides the full set of services from the service_ids list, if they are available at the specified date and time;

Example of usage:

Function call in the block:

Example of a successful booking response:

When creating bookings and subsequently requesting available slots again, you’ll notice that the lists have shortened. For example, on 05.02.2024, the 18:00 slot is no longer available (it was only free in Victoria’s schedule), and for Paul Thompson, bookings for a men’s haircut and beard styling can now be made from 9:00 to 14:00, since the total duration of the services is 1 hour and 45 minutes, and Pavel already has another booking at 16:00.

Getting information about a client’s upcoming bookings

You can view a client’s current bookings by calling the get_bookings_info function.

The response will return a list of active bookings, along with detailed information for each booking.

Booking information is provided in a “key: value” format and includes:

booking identifier (booking_id),
date (booking_date),
time (booking_time),
identifiers (service_ids) and names (service_names) of selected services,
booking duration (booking_duration),
total cost of services (total_cost),
identifier (employee_id) and name (employee_name) of assigned employee's, and his title (job_title),
branch identifier (company_id)
branch name (company_name) and address (company_address).

Parameters:

client_id (optional)

client ID, req – This parameter is required if you want to retrieve bookings for a specific client; by default, it uses the client ID from the chat with the bot.

Example of usage:

Function call in the block:

Example of returned data:

Changing booking date and time

A client can independently change the booking date and time. To do this, they need to access the funnel block where the modify_booking_time function is called.

If the operation is successful, the function will return the operation status (status) with the value True and a message (message) “Booking time modified” in a “key: value” format.

Parameter order:

order_id -> new_date -> new_time

Parameters:

order_id (required)

booking identifier, expected value – integer;

new_date (required)

new booking date, expected format – string in the form “day.month.year”, for example “16.01.2024”;

new_time (required)

new booking time, expected format – string in the form “hours:minutes”, for example “14:30”;

Example of usage:

Function call in the block:

Bot response for a successful operation:

The previously occupied 16:00 slot is now available for booking, and creating a new booking for the same services can now only be done from 11:00

In the client’s booking information, you will also see the updated booking time:

Cancelling a booking

A client can independently cancel an existing booking. To do this, they need to access the block where the cancel_booking function is called.

A successful cancellation will return the operation status (status) with the value True and a message (message) “Booking deleted” in a “key: value” format.

Parameter order:

pipeline_id -> order_id

Parameters:

pipeline_id (required)

branch identifier, expected value – integer;

order_id (required)

booking identifier, expected value – integer;

Example of usage:

Function call in the block:

Bot response for a successful cancellation:

After the cancellation, the “09:00” and “10:00” slots are available for booking again:

Example of bot implementation

Chatbot settings

Block №1. Start. No special actions required

Block №2. In this block, we retrieve the data that will be provided to the client.

Calculator content description:

comp_id - service block identifier, which can be found in the “Services” section;
data - information about the provided services
res - dictionary with data needed for generating buttons and setting conditions
numbered_list - may be useful if the list of services needs to be duplicated in text form
buttons - array of buttons generated from the service data
checker - array of service names, used to set conditions for moving to the next block

Block №3. Retrieve and display data about the selected service.

title -in the array of dictionaries data, find the dictionary where the key title equals question. From that dictionary, get the value for the same key title

description - similarly, get the value for the key description

price - similarly, get the value for the key price

serv_id - similarly, get the value for the key id

b - create an array of strings that will be displayed as buttons under the message

res - from the array b, create an array of dictionaries as in the previous block

buttons - obtain the array for displaying the buttons

Now we have variables containing the name, description, and price of the service selected by the client

Block №4. Display available booking dates

print_dates - use the function to get available booking dates for the selected service

print_dates - add the string “Return to service list” to the array of dates if you want this button to appear along with the dates.

For the arrow returning to the previous step, set a higher priority than the arrow with #{checker}, because #{checker} also contains the condition “Return to service list”.

Block №5. В блоке №5 мы сохраняем выбранную клиентом дату. Это нужно сделать в отдельном блоке потому, что на следующих этапах при возврате в Блок 6, переменная question уже не будет содержать в себе выбранную клиентом дату.

Блок №6. Выбор и отображение доступных ячеек для записи.

data - получаем доступные ячейки.

Логика такая же, как в Блоке №4 с выводом доступных дат. Также важно не забыть настроить повышенный приоритет у стрелки “Вернуться к выбору даты”

Блок №7. Сохранение выбранного времени в переменную и попытка записать клиента.

choosed_time - сохраняем время

a - попытка записать клиента

booking_result - получаем результат выполнения функции.

Получить результат необходимо, так как несколько человек могут попытаться записаться на одно время в один момент.

Блок №7.1. Записать клиента не удалось.

Этот блок нужен только для сообщения об ошибке. После отправки сообщения возвращаем клиента на выбор времени для записи

Блок №8. Запись прошла успешно.

Сообщаем клиенту, что он записан на услугу и отображаем кнопку для оплаты.

Пример настройки кнопок.

Для настройки используем переменные, которые мы получили в блоке №3:

Блок №8.1.

В этом блоке подтверждаем успешную оплату. Переход в блок настраиваем в соответствии с используемой платежной системой

Блок №8.2. Клиент не оплатил услугу. Отмена записи

Если клиент не оплатил вовремя услугу, мы можем отменить запись, если это необходимо.

or_id - получаем id заказа

cancel_status - после выполнения функции получаем ответ, успешно ли выполнена отмена.

В этом примере клиент попадет в блок отмены через 5 секунд после получения ссылки на оплату, в реальной же ситуации вы можете установить необходимое количество времени, главное не забудьте включить переключатель “Отменить, если покинул блок”.