Reference Guide

Use Cases & Data Sync

Understanding the different booking scenarios and how Bot MD and your scheduling system stay synchronized through APIs and webhooks.

Booking Scenarios

There are three primary scenarios for appointment booking. Each follows a specific flow between Bot MD (downstream) and your scheduling system (upstream).

Use Case 1: Patient Books via Chat

Patient initiates booking through Bot MD (Messenger, Viber, SMS)

Patient

Bot MD

API Provider

Patient requests appointment through chat interface

Bot MD calls POST /api/v1/appointments to create appointment

API Provider responds with appointmentId, temporaryPatientId, and/or patientId

API Provider sends webhook with appointment details to Bot MD

Bot MD stores IDs for future operations (reschedule/cancel)

Use Case 2: Patient Calls or Walks In to Book

Staff manually creates appointment in the scheduling system

Patient

API Provider

Bot MD

Patient calls or visits hospital to book appointment

Staff creates appointment manually in the scheduling system

API Provider sends appointmentCreated webhook to Bot MD

Bot MD checks if patient is a new or existing contact and manages accordingly

Bot MD stores IDs for future operations (reschedule/cancel)

Use Case 3: Patient Walks In Without Appointment

Patient arrives without prior booking, staff creates on-the-spot appointment

Walk-in Patient

API Provider

Bot MD

Patient walks into the facility without a prior appointment

Staff creates appointment manually in the scheduling system

API Provider sends webhook with appointment details to Bot MD

Bot MD stores IDs for future communication and operations

Bot MD determines if patient is new or existing contact and manages accordingly

Why Patient Details Are Required in Appointments

Bot MD requires patient contact details (name, phone, email) within the appointment object because Bot MD actively communicates with patients throughout the appointment lifecycle.

What Bot MD Does With Patient Details

Once an appointment is created, Bot MD uses the patient's contact information to send automated communications at key moments:

Appointment Confirmation

When an appointment is booked, Bot MD sends a confirmation message to the patient via their preferred channel (SMS, WhatsApp, Viber, etc.)

Appointment Reminders

Bot MD sends timely reminders before the appointment date, helping reduce no-shows and keeping patients informed

Reschedule Notifications

When an appointment is rescheduled (by patient or staff), Bot MD notifies the patient of the new date and time

Cancellation Notices

When an appointment is canceled, Bot MD informs the patient and can offer options to rebook

This is why the patient object must be included in all appointment API responses and webhook payloads. Without the patient's name, phone number, and email, Bot MD cannot reach the patient to send confirmations, reminders, or status updates.

Required Patient Object in Appointments

Every appointment response and webhook payload must include a patient object with the following fields:

"patient": {
  "id": "3a1fd2884036336bd2b89211ca967f7c",
  "patientId": "2396423",           // permanent ID (null if not yet assigned)
  "temporaryPatientId": "TMP-5001",  // temporary ID
  "firstName": "Jane",
  "lastName": "Doe",
  "fullName": "Doe, Jane",
  "email": "[email protected]",    // for email notifications
  "phone": "+6591234567",            // for SMS/WhatsApp/Viber
  "dob": "1990-05-15T00:00:00+0800",
  "gender": "Female"
}

Key fields for communication: phone and email are essential for Bot MD to reach the patient. firstName / fullName are used to personalize messages.

Data Synchronization

Bot MD and your scheduling system must stay synchronized to ensure patients receive accurate information. This is achieved through a combination of API calls and webhooks.

Bot MD → API Provider

When patients interact with Bot MD, we call your APIs to:

Check availability and time slots
Create new appointments
Reschedule existing appointments
Cancel appointments
Look up patient records

API Provider → Bot MD

When events occur in your system, send webhooks (signed with HMAC-SHA256) to notify Bot MD:

Appointment created (by staff)
Appointment rescheduled
Appointment canceled
Patient checked in (Queued)
Permanent patient ID assigned

What Bot MD Stores

Bot MD stores the following identifiers from your system to enable future operations:

appointmentId

Used for reschedule/cancel operations

patientId

Permanent patient identifier

temporaryPatientId

Used until permanent ID is assigned

Synchronization Best Practices

1
Always send webhooks (signed with HMAC-SHA256) when appointment status changes in your system, even for changes made by staff
2
Include all relevant IDs in webhook payloads (appointmentId, patientId, temporaryPatientId)
3
Send patientCreated webhook when a temporary patient ID is converted to a permanent patient ID
4
Include status field in all API responses and webhooks using the standardized status values

Appointment Status Values

The API Provider should include the appropriate status string in API responses and send the same status via webhooks whenever the status changes, so Bot MD stays in sync.

SCHEDULED

Appointment has been created/scheduled

RESCHEDULED

Appointment time has been changed

CANCELED

Appointment has been canceled

CONFIRMED

Patient confirms attendance (e.g., via reminder)

SHOW

Patient physically checked in at the facility

NO SHOW

Patient did not check in on the appointment date

Typical Status Flow

SCHEDULEDCONFIRMEDSHOW

Alternative paths: SCHEDULED → RESCHEDULED → CONFIRMED, or SCHEDULED → CANCELED, or CONFIRMED → NO SHOW

API Reference

View detailed endpoint specifications

Integration Flows

Step-by-step user journeys

Getting Started

Integration overview