Integration Flows

Step-by-step guides showing how Bot MD integrates with your scheduling system for common patient journeys.

Initial Setup

Connect your Scheduling System with Bot MD

1

API Key Authentication

Your scheduling system provides a unique API key for every hospital. Each facility has its own API key.

2

Appointment Type Configuration

If your scheduling system does not maintain appointment types, a default appointment type per calendar is set up to maintain consistency for further integrations.

3

Reschedule Cutoff Time

Configure the reschedule cutoff time during setup.

4

Calendar Sync

GET

Fetch and store the calendars, maintaining sync separately.

/api/v1/calendars
5

Configure Webhook

WEBHOOK

Set up webhook endpoint to receive appointment and patient updates.

Note: Location can be inferred from API key. Branch support is not required - each facility has its own API key.

User Journey 1: Book Appointment

Patient schedules a new appointment via chat

1

Collect Patient Info

Bot MD collects user's basic information: Name, DOB, Mobile, Gender, National ID

2

Create/Update Contact

Bot MD creates or updates the information of the Contact entity at its end.

3

User Expresses Intent

User expresses intent to book an appointment.

4

Get Availability

GET

Bot MD invokes your API to get available time slots for the selected calendar and appointment type.

/api/v1/availability

Request: month, appointment_type_id, calendar_id

Response: date and time slots

5

User Selects Slot

Bot MD presents available dates and times, allowing user to select preferred slot.

6

Create Appointment

POST

The chosen date and time slot is sent to your API to create an appointment.

/api/v1/appointments
7

Send Confirmation

The appointment booked is sent back as a confirmation message to the user's device.

User Journey 2: Cancel Appointment

Patient cancels an existing appointment via chat (e.g., "I want to cancel an appointment")

1

User Expresses Intent

User expresses intent to cancel an appointment via chat.

2

Retrieve Stored Appointments

Bot MD retrieves the patient's appointments from its own stored data (using previously saved appointmentId, patientId, temporaryPatientId).

3

User Selects Appointment

Bot MD presents the appointments to the user, allowing them to choose which appointment to cancel.

4

Cancel Appointment

PUT

Bot MD sends the cancellation request to your API using the stored appointmentId.

/api/v1/appointments/:id/cancel

Request: appointment_id (from Bot MD's stored data)

5

Send Confirmation

The appointment cancelled is sent back as a confirmation message to the user's device.

Note: Bot MD uses its own stored data (appointmentId, patientId) from previous bookings or webhook events. No need to call Get Patient or Get Appointments endpoints.

User Journey 3: Reschedule Appointment

Patient reschedules an existing appointment via chat (e.g., "I want to reschedule an appointment")

1

User Expresses Intent

User expresses intent to reschedule an appointment via chat.

2

Retrieve Stored Appointments

Bot MD retrieves the patient's appointments from its own stored data (using previously saved appointmentId, patientId, temporaryPatientId).

3

User Selects Appointment

Bot MD presents the appointments to the user, allowing them to choose which appointment to reschedule.

4

Get New Available Slots

GET

Bot MD fetches available dates and time slots for rescheduling.

/api/v1/availability

Request: month, appointment_type_id, calendar_id

Response: date and time slots

5

User Selects New Slot

Bot MD presents available dates and times, allowing user to select preferred new slot.

6

Reschedule Appointment

PUT

Bot MD sends the reschedule request to your API using the stored appointmentId.

/api/v1/appointments/:id/reschedule

Request: appointment_id (from Bot MD's stored data), new datetime

7

Send Confirmation

The appointment rescheduled is sent back as a confirmation message to the user's device.

Note: Bot MD uses its own stored data (appointmentId, patientId) from previous bookings or webhook events. No need to call Get Patient or Get Appointments endpoints.

User Journey 4: Admin Sync (Webhook)

Admin books/modifies/cancels appointment for a patient in your scheduling system

1

Admin Action

Your scheduling system books/modifies/cancels an appointment internally.

2

Trigger Webhook

WEBHOOK

Your scheduling system triggers Bot MD's pre-configured webhook endpoint.

Request: action: scheduled/rescheduled/cancelled, patient_id, appointment_id, email, phone, name, DoB

3

Bot MD Processes Event

Bot MD captures the event, creates a contact entity locally if patient doesn't exist, and associates the appointment_id to the contact entity.

4

Notify Patient

Bot MD sends a confirmation message to the user via Messenger/Viber/SMS.

User Journey 5: Queue Check-in (Webhook)

Patient arrives for appointment and checks in with Queue

1

Patient Arrives

Patient arrives at the facility for their appointment.

2

Trigger Queued Webhook

WEBHOOK

Your scheduling system triggers a webhook to Bot MD to update the status.

Request: action: queued, queue_number, patient_id, appointment_id, email, phone, name, DoB

3

Bot MD Processes Event

Bot MD captures the event, creates a contact entity locally if patient doesn't exist, and associates the appointment_id to the contact entity.

4

Update Appointment Status

Bot MD updates the status of its appointment as SHOW.

Permanent Patient Creation (Webhook)

Patient gets a permanent ID assigned/created in your scheduling system

1

Permanent ID Assigned

Patient gets a permanent ID assigned/created in your scheduling system.

2

Trigger patientCreated Webhook

WEBHOOK

Your scheduling system triggers a webhook to update the permanent ID at Bot MD's end.

Request: patientId, temporaryPatientId

3

Update Patient Entity

The new patient Entity ID is updated on Bot MD's end, linking the temporary patient record to the permanent patient ID.

Integration Checklist

Required Endpoints

  • • GET /api/v1/calendars
  • • GET /api/v1/availability
  • • POST /api/v1/appointments
  • • PUT /api/v1/appointments/:id/reschedule
  • • PUT /api/v1/appointments/:id/cancel

Note: Bot MD uses its own stored data for patient and appointment lookups during cancel/reschedule flows.

Webhook Events

  • • appointmentCreated - New appointment created
  • • appointmentRescheduled - Appointment time changed
  • • appointmentCanceled - Appointment cancelled
  • • patientCreated - Permanent patient ID assigned
  • • Queued - Patient checked in (includes queueNumber)