Back to API Docs
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
1

Patient requests appointment through chat interface

2

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

3

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

4

API Provider sends webhook with appointment details to Bot MD

5

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
1

Patient calls or visits hospital to book appointment

2

Staff creates appointment manually in the scheduling system

3

API Provider sends appointmentCreated webhook to Bot MD

4

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

5

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
1

Patient walks into the facility without a prior appointment

2

Staff creates appointment manually in the scheduling system

3

API Provider sends webhook with appointment details to Bot MD

4

Bot MD stores IDs for future communication and operations

5

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

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 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 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