Appointments

Use appointments to reserve a time, collect the patient details, notify the patient on WhatsApp when configured, and start the front-office check-in or visit workflow.

Who can do this: Receptionists, Branch Managers, Practitioners and Super Admins with appointment.read to view and appointment.manage to book, confirm, reschedule, cancel or check in. Public patients can submit a request from the public booking page. Where: Appointments (/app/appointments), Appointments → Book Appointment (/app/appointments/book), Appointments → Online Requests (/app/appointments/pending-online), public Book an Appointment (/book-appointment).

Before you start

• Add at least one active branch and practitioner so the form can show Select Doctor/Therapist.
• Register the patient first when the clinic wants the appointment tied to an existing patient record.
• Configure WhatsApp before expecting appointment confirmation, cancellation, reschedule or online-request acknowledgement messages to send.
• Remember that public booking accepts Monday to Saturday, 9:00 AM to 7:00 PM. Sunday is blocked by the backend.

Book a staff appointment

1. Open Appointments and click Book Appointment. Result: The Book an Appointment form opens.
2. If you are signed in, enter the patient's Phone Number and click Search Patient. Result: If a match exists, the form is filled and the toast says Patient found! Details auto-filled. If no match exists, the screen says No patient found with this phone number.
3. For a new patient, click New Patient or Continue with New Patient. Result: The full booking form opens.
4. Fill Patient Name, Guardian Name, Phone Number, Patient Age, Service Required, Appointment Type, Preferred Date, Preferred Time, Select Doctor/Therapist and Reason for Appointment.
5. Add Additional Notes if needed.
6. Click Confirm Appointment. Result: The appointment is saved as confirmed, the toast says Appointment confirmed successfully!, and you return to Appointments. If the patient has a phone number, the backend sends the appointment confirmation WhatsApp message in the background.

tip

If the phone search cannot run, continue as a new-patient booking and register the full patient record later from Patients → Register New Patient.

Review online booking requests

1. Open Appointments and click Online Requests. Result: Pending Online Appointments lists requests with the ONLINE BOOKING badge.
2. Review the patient name, phone, date, branch, reason and doctor.
3. Click ✔ Confirm to accept the request. Result: The toast says Appointment confirmed! and a WhatsApp confirmation is attempted for the patient.
4. To refuse the request, click ✕ Cancel.
5. In Cancel appointment, type Cancellation reason and click Confirm cancellation. Result: The toast says Appointment cancelled and a cancellation WhatsApp is attempted.

note

Online booking creates an in-app notification titled 🆕 New Online Appointment Request for Super Admin, Branch Manager and Receptionist roles. The WhatsApp acknowledgement to the patient is fire-and-forget; a failed external WhatsApp call never blocks saving the request.

Understand WhatsApp appointment messages

1. For staff bookings, save the appointment with a patient phone number. Result: The backend attempts an appointment-confirmation WhatsApp in the background.
2. For online bookings, submit the public request. Result: Staff get an in-app notification and the backend attempts an online-booking acknowledgement WhatsApp.
3. Confirm, reschedule or cancel an appointment. Result: The backend attempts the matching confirmation, reschedule or cancellation WhatsApp.

note

The current worktree does not include a scheduled automatic appointment-reminder job. Do not promise reminder messages unless your clinic has a separate WhatsApp workflow configured.

Search, filter and export appointments

1. Open Appointments.
2. Use Search appointments to search by patient name, patient phone or doctor name.
3. Use Filter by status to show statuses such as Pending, Confirmed, Checked In, Completed, Cancelled, No Show or Pending Online.
4. Click Export CSV if you need a spreadsheet. Result: The browser downloads appointments.csv or the toast says Export failed.

Check in a patient and start the visit

1. Find the appointment row on Appointments.
2. Click the row action for Check In when the patient arrives. Result: The status becomes Checked In and the toast says Patient checked in.
3. If the queue module is enabled and the action issues a queue token, give the token number to the patient.
4. When the clinician is ready, click Start visit. Result: Achal opens the visit workspace at /app/patients/:patientId/encounters/:encounterId. Starting again opens the same visit for that appointment.

Reschedule an appointment

1. On Appointments, click the appointment's reschedule action.
2. In the reschedule dialog, choose newDate and, if needed, newTime.
3. Enter reason.
4. Click the dialog's reschedule button. Result: The toast says Appointment rescheduled and the backend attempts a WhatsApp reschedule message.

caution

The backend refuses rescheduling a COMPLETED or CANCELLED appointment and refuses a target slot that is already booked.

Cancel or complete an appointment

1. To cancel, open the cancellation dialog for the appointment.
2. Enter a reason and confirm. Result: The appointment status becomes Cancelled and the toast says Appointment cancelled.
3. To finish a visit-only workflow from the appointment list, click the complete action. Result: The status becomes Completed and the toast says Appointment completed.

Public patient booking

1. Share the public link /book-appointment.
2. The patient fills Patient Name, Guardian Name, Phone Number, Patient Age, Service Required, Appointment Type, Preferred Date, Preferred Time, Select Doctor/Therapist and Reason for Appointment.
3. The patient clicks Submit Appointment Request. Result: The toast says Appointment request submitted! Our receptionist will contact you soon to confirm. The request appears under Online Requests.

Troubleshooting

Problem / message	What it means	What to do
Unable to load appointments right now.	The appointments list API failed.	Click refresh or reopen Appointments. Check your connection and branch access.
Failed to load appointments	The frontend could not load /appointments.	Retry after a moment. If only one branch fails, ask an admin to check branch access.
Please select both date and time for the appointment	The booking form is missing Preferred Date or Preferred Time.	Select both fields before submitting.
Please enter a valid phone number	The public or staff form needs a 10-digit phone number.	Enter the mobile number without spaces or country code.
Appointment date and time must be in the future or Please select a future date and time	The selected slot is in the past.	Choose a future date and time.
Clinic is closed on Sundays	The backend blocks Sunday appointments.	Pick Monday to Saturday.
Appointments are available between 9:00 AM and 7:00 PM only	Public booking was outside clinic hours.	Choose a slot between 9:00 AM and 7:00 PM.
This time slot is already booked. Please choose another time.	Another appointment already uses that branch and time.	Choose a different time, or cancel/reschedule the other appointment first.
Appointment not found	The appointment was deleted, moved or the link is wrong.	Return to Appointments and reload the list.
Cannot reschedule a COMPLETED appointment or Cannot reschedule a CANCELLED appointment	The appointment is in a final state.	Create a new appointment instead.
Enter a cancellation reason before cancelling the appointment.	The online request cancellation dialog requires a reason.	Type a short reason and click Confirm cancellation again.
Phone number not verified. Please verify with OTP first.	Public booking API requires a verified phone before saving.	Ask the patient to complete OTP verification and submit again.
Invalid date/time format. Use date: YYYY-MM-DD, time: HH:mm	Public booking sent a malformed date or time.	Re-select the date and time in the form.

Related

• Queue & tokens
• Patients
• Encounters
• WhatsApp
• Book an appointment video