Bookivo documentation

Bookivo lets you run your own online booking business. Salons, clinics, studios, trainers and any business that works by appointment sign up on your website, pay you a monthly plan, and get a booking page, a team calendar, online deposits and automatic reminders.

The team calendar with appointments for each team member
The team calendar: one column per team member, booked and free times at a glance.
You, the platform ownerSet plans and prices, collect subscriptions, put your own name and logo on everything.
BusinessesServices, team and working hours, calendar, deposits, payments at the desk, clients, coupons, reports.
ClientsOpen the booking link, pick a service, a person and a free time, pay the deposit, get a confirmation and a reminder.

What's in the download

FolderWhat it is
bookivo/The application. This is what you upload to your server. It already contains everything it needs (vendor/ and the built interface), so you don't need Composer or Node.js.
documentation/This guide. Open index.html in any browser; it works offline.

Requirements

Any normal cPanel or Plesk hosting works, as does a VPS. You don't need SSH, Composer, Node.js, Redis or a separate queue worker.

ItemNeeded
PHP8.3 or newer (8.3, 8.4 and 8.5 are supported). The installer warns you when your PHP is not the latest patch release of its branch, but it never stops you: update PHP when your host offers it.
PHP extensionsbcmath, ctype, curl, dom, fileinfo, gd, intl, json, mbstring, openssl, pdo, pdo_mysql, tokenizer, xml, zip, and sodium (used to check update packages). Most hosts have all of them on; the installer lists any that are missing.
DatabaseMySQL 8.0+ or MariaDB 10.6+, one empty database with a user that has all privileges on it.
Web serverApache (with mod_rewrite), LiteSpeed or Nginx.
HTTPSStrongly recommended, and required for card payments and phone notifications. Free AutoSSL / Let's Encrypt is fine.
CronOne cron job that runs every minute (see Cron job).
Memory / uploadmemory_limit 256M or more; upload_max_filesize 16M or more for update packages and photos.

Installation

It takes about ten minutes. The steps below use cPanel, and other panels use the same steps under different names.

1. Create the database

  1. cPanel → MySQL® Databases. Create a database, for example youruser_bookivo.
  2. Create a user with a strong password.
  3. Add the user to the database with ALL PRIVILEGES. Keep the three names and the password for step 4.

2. Upload the files

  1. Upload the contents of the bookivo/ folder to your account, for example to /home/youruser/bookivo. The easiest way: upload the zip with File Manager, then Extract.
  2. Make sure the hidden files came along. You should see .htaccess files in the main folder and in public/ (File Manager → Settings → Show hidden files).

3. Point the domain at the public folder

The domain must open the public folder, not the main folder. In cPanel: Domains → your domain → Manage → Document Root → bookivo/public.

Can't change the document root?Some hosts force public_html. Then upload everything into public_html. The .htaccess in the main folder sends visitors into public/ and blocks everything else, like .env, storage and backups. Afterwards, Admin → System → Server check confirms nothing private can be downloaded.

4. Run the installer

Open your domain in a browser. The installer starts by itself and has three steps:

  1. Requirements: PHP version, extensions and writable folders. Anything red tells you what to fix.
  2. Database: host (usually localhost or 127.0.0.1), port 3306, database name, user and password. Creating the tables takes up to two minutes on slow hosting, so keep the page open.
  3. Admin:
    • Your platform name and address.
    • The main country of your customers. New businesses start with its currency, time zone, phone code and tax rate, and each one can change them later.
    • Your admin account.

When it finishes you land on the login page. The installer locks itself after the first successful installation.

Installing on a VPS (Nginx)

Point the server block's root at /var/www/bookivo/public and send all requests to index.php:

server {
    listen 80;
    server_name example.com *.example.com;
    root /var/www/bookivo/public;
    index index.php;
    client_max_body_size 32m;

    location / { try_files $uri $uri/ /index.php?$query_string; }
    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        fastcgi_pass unix:/run/php/php8.4-fpm.sock;
    }
    location ~ /\.(?!well-known) { deny all; }
}

Give the web server user write access to storage/, bootstrap/cache/ and .env:

chown -R www-data:www-data storage bootstrap/cache .env
chmod -R ug+rwX storage bootstrap/cache

Cron job (required)

Bookivo needs one cron job, every minute. It sends e-mails and booking reminders, issues renewal invoices, pauses unpaid businesses and makes the nightly backup. No separate queue worker is needed: the same cron job runs background jobs too.

cPanel → Cron Jobs → Once Per Minute (* * * * *), command:

cd /home/youruser/bookivo && php artisan schedule:run >> /dev/null 2>&1

Use your real path. Admin → System → Server check shows the exact line for your server and tells you when the cron last ran.

If php is the wrong versionSome hosts have several PHP versions. Use the full path of PHP 8.3 or newer, for example /opt/cpanel/ea-php84/root/usr/bin/php or /usr/local/bin/ea-php84. Your host's support can tell you the right one.
TaskWhen
Background jobs (e-mails, notifications)Every minute
Booking reminders to clientsEvery 5 minutes
WhatsApp reminders (businesses with a reminder template)Every 15 minutes
Google Calendar: busy times, retries, push channelsEvery 5 minutes
Subscriptions: renewal invoices, overdue and paused businessesDaily 02:15
Backup of the database and uploadsDaily 03:30

First steps as platform owner

After logging in you see Get your platform ready to sell, a checklist that ticks itself off as you go:

  1. Check your plans and prices: three plans are ready (Solo, Team, Business) in US dollars. Set your own prices and currency in Plans.
  2. Set up e-mail: so businesses receive sign-up, password and invoice e-mails, and their clients receive confirmations and reminders (E-mail).
  3. Choose how businesses pay you: Stripe, PayPal or bank transfer (Payments).
  4. Upload your logo: Website → logo. It replaces the Bookivo mark everywhere, including the login pages and e-mails.
  5. Write your home page: headline, features, FAQ, terms and privacy pages, in every language you offer.
  6. Get your first business: share your sign-up page (/register), or add one yourself under Businesses.

E-mail

Admin → Email. Enter your SMTP details, for example from the e-mail account you created in cPanel, or from Mailgun, Postmark, Amazon SES or Brevo. Then use Send a test e-mail on the same page.

FieldTypical value
Hostmail.yourdomain.com
Port / encryption465 with SSL, or 587 with TLS
Username / passwordThe full e-mail address and its password
From addressAn address on your own domain, such as no-reply@yourdomain.com. That helps keep mail out of spam.

The password is stored encrypted. Until e-mail works, new accounts don't need to confirm their e-mail address, so nobody gets locked out.

SMS

Businesses can text their clients when a booking is made, before the visit, when it moves to a new time and when it is canceled. Each text is short, in the business's language, and links to the client's booking page. Texts are sent by the background jobs of the cron job; reminders go out at the reminder time the business set under Settings → Booking rules.

There are two kinds of SMS account:

On the same page the business switches each message on or off, sends a test, and sees the last 30 messages with the provider's answer. A client without a phone number is not texted. A client who already gets the same news on WhatsApp (see WhatsApp agent) is not texted either, unless the business ticks Also text clients who get the same message on WhatsApp. Numbers typed without a country code are read as numbers of the business's country, so set the country in Settings.

Twilio

  1. In the Twilio Console, copy the Account SID and Auth Token from the account dashboard.
  2. Buy a number that can send SMS to your clients' countries, or create a Messaging Service with your numbers in it.
  3. In Bookivo choose Twilio, paste the Account SID and Auth token, and enter either the From number (for example +15551234567, or an approved alphanumeric sender ID) or the Messaging Service SID (starts with MG). When both are filled in, the Messaging Service is used.
  4. Save, then use Send a test message. A trial Twilio account only texts numbers you verified in the Twilio Console.

Vonage (API key, API secret, From) and Plivo (Auth ID, Auth token, From number or Powerpack UUID) are set up the same way.

Any other SMS company (HTTP API)

Choose Other provider (HTTP API) and copy the details from your provider's API documentation. In the URL and the body, these placeholders are replaced for each message:

PlaceholderReplaced with
{to}The client's number with +, for example +201001234567
{to_digits}The same number without +: 201001234567
{message}The text of the message

Each value is escaped for where it stands, so do not encode it yourself. Examples:

Provider expectsSettings
A GET linkMethod GET, URL https://sms.example.com/send?user=me&key=KEY&to={to_digits}&text={message}
A form postMethod POST, format form, body to={to_digits}&text={message}&sender=Salon
JSON with a tokenMethod POST, format json, header Authorization: Bearer YOUR-KEY, body {"to": "{to}", "text": "{message}"}

Any answer with HTTP status 200–299 counts as sent. If your provider answers 200 even when it refuses a message, fill in Success text with a word that only appears in a good answer (for example OK or "status":"success"). Message id path (for example data.id) picks the provider's message id out of a JSON answer, so it shows in the log. Headers are stored encrypted. A business's own HTTP provider must be on the public internet; the platform account may also point at your own network.

All credentials are stored encrypted. The public demo never sends text messages.

Payments

There are two separate kinds of money:

Stripe

  1. Stripe Dashboard → Developers → API keys: copy the Secret key (sk_live_…, or sk_test_… to try it out).
  2. Developers → Webhooks → Add endpoint: paste the webhook URL shown on the payment card in Bookivo. Select the events checkout.session.completed, checkout.session.async_payment_succeeded, checkout.session.async_payment_failed and checkout.session.expired.
  3. Copy the endpoint's Signing secret (whsec_…) into Bookivo, turn Stripe on, and save. The keys are tested when you save, so a wrong key is caught right away.

PayPal

  1. developer.paypal.com → Apps & Credentials → create an app. Copy the Client ID and Secret.
  2. In the app, add a webhook with the URL shown in Bookivo and the events CHECKOUT.ORDER.APPROVED, PAYMENT.CAPTURE.COMPLETED, PAYMENT.CAPTURE.DENIED and PAYMENT.CAPTURE.DECLINED. Copy the Webhook ID.
  3. Choose sandbox to test or live for real money.

Bank transfer

Turn it on and write the transfer instructions (bank, account, reference). Businesses upload proof of payment; you see it under Billing → Waiting for review and approve it with one click.

Amounts and currenciesEvery amount is calculated with the right number of decimals for its currency, for example 3 for KWD, BHD and OMR, and 0 for JPY. Payments that come back a few fils off because of rounding are still accepted as paid in full.

Plans & billing

Admin → Plans. Each plan has:

Limits are enforced everywhere. A business that reaches its monthly booking limit sees a clear message and an upgrade link, and its clients are asked to contact the business directly.

The billing cycle

  1. A new business starts on a free trial of the plan it chose.
  2. Before the period ends, an invoice is created and e-mailed.
  3. Unpaid after the due date, the subscription becomes past due. The business keeps working but sees a warning.
  4. Still unpaid after the grace period, the business is paused until it pays. Its data is never deleted.

Admin → Billing → Settings sets:

Business addresses

Every business gets a booking page address that always works, on any hosting:

https://yourdomain.com/r/business-name/book

Subdomains (optional)

To give each business business-name.yourdomain.com:

  1. Add a wildcard DNS record: * → A → your server's IP.
  2. Add the wildcard as a subdomain in cPanel (*.yourdomain.com, same document root), and get a wildcard SSL certificate for it. AutoSSL covers wildcards on many hosts; otherwise use Let's Encrypt with DNS validation.
  3. In .env set BOOKIVO_SUBDOMAINS=true.

A business's own domain

A business can connect its own domain under Settings → Web address, for example book.theirsalon.com. Bookivo shows two DNS records for them to add:

On shared hosting, also add that domain to your account as an alias (cPanel → Domains, same document root), so your server answers for it and issues its SSL certificate. On a VPS, a catch-all server block does the same.

Running a business

Business owners see their own Get your booking page ready checklist: services, working hours, logo and colour, sharing the booking link, first booking.

Services

Services grouped in categories with price, length and deposit
Services in categories, each with its length, price, deposit and the people who perform it.

Team, working hours and time off

Team members with their weekly working hours
Each person's week at a glance. Add a second range on a day to leave a break.

The calendar

Appointment details with status actions and payment
Everything about one appointment: client, time, money and the actions taken at the desk.

The booking page

The public booking page of a salon
The client's booking page, in the business's own colour, on a phone or a computer.
  1. The client picks a service, then a team member (or anyone available), then a free time.
  2. They enter their name, phone and e-mail, and a discount code if they have one.
  3. If the service asks for a deposit they pay it by card or PayPal; otherwise the booking is confirmed straight away (or waits for approval, if the business chose that).
  4. They get a confirmation e-mail with a link to see, pay or cancel the booking, and a reminder before the visit.

Settings → Booking rules sets the time between offered start times, the minimum notice, how far ahead clients can book, until when they can cancel online, and when the reminder goes out.

Clients, coupons and reports

The business dashboard with today's appointments and earnings
The dashboard: today's appointments, what is coming up and the last 30 days.

Staff and roles

RoleCan do
OwnerEverything, including subscription and settings.
ManagerBranches, staff, services, team, calendar, appointments, clients, reports, and everything under WhatsApp.
ReceptionistCalendar, appointments, payments at the desk, clients and the WhatsApp inbox.
ProviderOnly their own calendar: mark their appointments completed or no-show.

Invite staff by e-mail under Staff. Everything they change is recorded in the Activity log.

WhatsApp agent

Clients write to the business's own WhatsApp number. An AI agent answers from the business's services, free times and Knowledge, and books, moves or cancels real appointments in the calendar. Staff see every conversation in a shared inbox and can take over at any moment. It is part of Bookivo (plan feature WhatsApp agent), not a paid add-on.

The WhatsApp inbox with a conversation the agent booked
The shared inbox: what the agent did at each step, the booking it made, and the client's appointments.
Tested only against simulated servicesEvery part is covered by automated tests in which WhatsApp, Anthropic and OpenAI are simulated. It has not yet been run against a real WhatsApp number or a real AI model, so test it with your own number (and the Test the agent screen) before you rely on it.

What each business needs

Connecting a number (the business does this once)

  1. In Meta for Developers create an app of type Business, add the WhatsApp product and add (and verify) the business phone number.
  2. Create a permanent access token: Business Settings → System users → add a system user with the app and the WhatsApp account assigned, then Generate token with whatsapp_business_messaging and whatsapp_business_management. Temporary 24-hour tokens stop working the next day.
  3. Copy the Phone number ID (and optionally the WhatsApp Business Account ID) from WhatsApp → API Setup, and the App secret from App settings → Basic.
  4. In Bookivo: WhatsApp → WhatsApp settings → WhatsApp number → Connect a number. Paste the phone number ID, token and app secret, and choose a verify token (any phrase of 8+ characters). Save, then press Test connection: it asks Meta about the number and shows exactly what Meta answered.
  5. Copy the Callback URL shown under the number (it looks like https://your-domain/whatsapp/webhook/<id>). In Meta: WhatsApp → Configuration → Webhook → Edit, paste the callback URL and the same verify token, Verify and save, then subscribe to the messages field.
  6. Under Agent, choose the provider, paste the API key and fill in the business profile. Try it on Test the agent, then send a WhatsApp message to the number from your phone: it appears in WhatsApp → Inbox.

The token, app secret, verify token and AI keys are stored encrypted with your APP_KEY and are never shown again. The site must be reachable on https from the internet for Meta to deliver messages.

How replies and bookings work

The 24-hour window and templates

WhatsApp allows free replies for 24 hours after the client's last message. After that only a message template approved in Meta's WhatsApp Manager can be sent. Under Templates, type the exact template name and language for: booking confirmation, reminder (sent using the reminder time of the booking rules), cancellation and "write again". A moment with no template sends nothing. Confirmations, reminders and cancellations go only to clients who already have a WhatsApp conversation with the business.

Limits

In Admin → Plans, AI replies per month caps how many times the agent answers in a calendar month (empty = unlimited). Replies on the Test the agent screen and in the sample demo conversations are not counted. Appointments the agent books count towards Bookings per month like any other booking.

Google Calendar

Each team member can connect their own Google Calendar. The sync works both ways:

It is part of Bookivo (plan feature Google Calendar sync). The ready-made Team and Business plans include it; Solo does not.

Tested only against simulated servicesEvery part is covered by automated tests in which Google is simulated. It has not yet been run against a real Google account, so connect your own calendar and book a test appointment before you rely on it.

Setting up Google Cloud (platform owner, once)

All businesses on your platform share one Google OAuth client that you create. It is free.

  1. Open Google Cloud Console and create a project (for example "Bookivo").
  2. APIs & Services → Library: search for Google Calendar API and press Enable.
  3. Google Auth Platform → Branding (older consoles: OAuth consent screen): enter the app name your users will see, a support e-mail and your site's home page, privacy policy and terms links. Under Audience choose External.
  4. Data Access → Add or remove scopes: add these three, and nothing else:
    • https://www.googleapis.com/auth/calendar.events (add, change and remove the appointment events)
    • https://www.googleapis.com/auth/calendar.calendarlist.readonly (list the calendars for the picker)
    • https://www.googleapis.com/auth/calendar.freebusy (read busy times only)
  5. Clients → Create client, type Web application. Under Authorized redirect URIs paste the address shown in Admin → Google Calendar (it looks like https://your-domain/google-calendar/callback). Create, then copy the Client ID and Client secret.
  6. In Bookivo: Admin → Google Calendar, paste both and save. The secret is stored encrypted with your APP_KEY and never shown again.

Testing mode, test users and verification

Connecting a calendar (team members)

  1. A team manager opens Team, clicks the Google Calendar line on a team member's card and presses Connect Google Calendar. A team member who has a login can do it themselves under Profile.
  2. They sign in to Google and allow access, leaving every box ticked. Bookivo writes to their main calendar and checks it for busy times; Calendars on the card lets them pick another calendar to write to and more calendars (shared family or clinic calendars) to check.
  3. Upcoming appointments are copied into the calendar straight away.

Disconnect removes Bookivo's access in Google (the token is revoked) and deletes it here. Events already in Google stay there. In the public demo connecting is turned off.

How it keeps working

Languages

Bookivo comes in 8 languages. English is built in; the other seven are language packs under modules/, all switched on when you install:

LanguageCodePack
Englishenbuilt in
العربية (Arabic, right-to-left)armodules/Arabic
Español (Spanish)esmodules/Spanish
Français (French)frmodules/French
Português (Portuguese)ptmodules/Portuguese
Deutsch (German)demodules/German
Türkçe (Turkish)trmodules/Turkish
Bahasa Indonesia (Indonesian)idmodules/Indonesian

Each pack covers:

Dates, numbers and prices follow the chosen language automatically.

Don't need a language? Switch its pack off under Admin → Modules, or with php artisan module disable Turkish. It disappears from every menu.

Adding a language

The easiest way is to copy a pack. For Italian, say:

  1. Copy modules/Spanish to modules/Italian.
  2. In module.json, set "name": "Italian" and the "language" part: "code": "it", "name": "Italian", "native": "Italiano", "dir": "ltr" ("rtl" for right-to-left languages).
  3. Rename lang/es.json to lang/it.json and the folder lang/es to lang/it (it holds the validation, login, password and pagination messages).
  4. Translate the values, never the keys. Keep words starting with :, like :count or :name, and anything in {braces} or <tags> as they are. For texts with numbers (keys with a |), write one form per plural category of your language, in the order zero|one|two|few|many|other, keeping only the categories the language has (Italian: one|many|other, Arabic: all six).
  5. Run php artisan bookivo:lang it. It reports how much is translated and adds any missing texts, empty, to lang/it.json. Run it again after each update to pick up new texts.
  6. Switch the module on under Admin → Modules. The language now appears in every menu.

Backups

A full backup (database and uploaded photos and logos) is made every night, and the last 7 are kept. Admin → Backups lets you:

Backups are private and are never served on the web. They work on shared hosting without mysqldump, and stay fast and light on memory with large databases.

.env settingDefaultMeaning
BOOKIVO_BACKUP_DAILYtrueMake the nightly backup
BOOKIVO_BACKUP_KEEP7How many to keep
BOOKIVO_BACKUP_FILEStrueInclude uploaded files
Keep a copy somewhere elseA backup on the same server doesn't help if the server is lost. Download one regularly, or use your host's own backups as well.

Updates

Admin → System → Updates:

Every update package is signed and checked before anything changes. During the update:

  1. The site goes into maintenance mode for about a minute.
  2. It backs up the database and every file the update changes.
  3. It installs the update, and puts everything back by itself if something fails.

You can also press Undo the last update afterwards. An update never touches your .env, storage/ (uploads, backups, logs) or the language files you added.

From the command line: php artisan bookivo:update path/to/update.zip, and php artisan bookivo:update:rollback to undo.

Troubleshooting

Start with Admin → System → Server check. It tests PHP, the cron job, background jobs, folder permissions, the uploads link, HTTPS and whether private files are exposed, and tells you how to fix each one. Some problems have a Fix button.

What you seeFix
A list of files, or "404" on every pageThe domain doesn't point at public/, or the hidden .htaccess files weren't uploaded. See Installation, step 3.
"500 Server Error"Check storage/logs/laravel.log. The usual causes are a missing PHP extension or a folder that isn't writable (storage, bootstrap/cache).
Creating tables stops half-wayRun the installer again with the same database; it clears the half-made tables by itself. If it still times out, ask your host to raise max_execution_time.
Logos and photos don't showServer check → Public uploads link → Fix. If your host blocks symbolic links, ask them to allow them.
No e-mails arriveSend a test from Admin → Email, then check the cron job (e-mails are sent in the background). Then check the spam folder and your SMTP details.
Invoices aren't created, trials never endThe cron job isn't running. Server check shows when it last ran.
No reminder e-mailsThe cron job must run every minute, e-mail must work, and the business needs a reminder time set under Settings → Booking rules. Only confirmed bookings with an e-mail address get one.
A client sees no free timesCheck that the service has team members, that they have working hours that day, and the business's minimum notice and days ahead rules.
Deposits stay "pending"The webhook isn't reaching Bookivo. Check the URL and signing secret in Stripe or PayPal; their dashboards show each delivery attempt and its answer.
Never leave debug mode onIf you set APP_DEBUG=true to see an error, set it back to false right after. Debug pages show secrets.

Commands

Optional. Everything can be done from the admin panel. If you have SSH, run these from the Bookivo folder:

CommandWhat it does
php artisan bookivo:healthThe server check, in the terminal
php artisan bookivo:backupMake a backup now (--no-files for the database only)
php artisan bookivo:subscriptionsRun today's billing (normally done by the cron job)
php artisan bookivo:update file.zipInstall an update package
php artisan bookivo:update:rollbackUndo the last update
php artisan bookivo:lang xxCreate or check a language file
php artisan bookivo:remindersSend due e-mail reminders and queue due text reminders now (normally done by the cron job)
php artisan whatsapp:remindersSend due WhatsApp reminders now (normally done by the cron job)
php artisan google-calendar:syncRefresh Google busy times and retry failed events now (normally done by the cron job)
php artisan module listList installed modules (enable / disable a module by name)
php artisan schedule:runWhat the cron job runs every minute

Security

Your part:

Support

Before writing in, open Admin → System → Server check and copy anything that isn't green. Most questions are answered there or in Troubleshooting.

For help, write to support through the page where you bought Bookivo and include:

Support covers installation problems, bugs and questions about the features. It doesn't cover hosting setup, custom changes or third-party services.

Credits

Bookivo is original code. It is built on these open-source projects and assets, each under its own license (all allow use in commercial products):

ProjectUsed forLicense
Laravel, FortifyApplication framework, sign-inMIT
Inertia.jsPages without a separate APIMIT
ReactThe interfaceMIT
Tailwind CSSStylingMIT
Radix UIAccessible dialogs, menus and selectsMIT
LucideIconsISC
SonnerNotifications on screenMIT
spatie/laravel-permissionRoles and permissionsMIT
chillerlan/php-qrcodeQR codesMIT / Apache 2.0
Manrope (Mikhail Sharanda)Interface fontSIL Open Font License 1.1
IBM Plex Sans Arabic (IBM)Arabic fontSIL Open Font License 1.1

The fonts are included in the download (in public/build), so no request goes to a font service. Photos shown in the live demo and screenshots are for illustration only and are not included in the download.