Bot MDAPI Documentation
← Back to API Docs
Integration Guide

Bot MD API Integration

This documentation describes the API endpoints that your scheduling system must provide to enable Bot MD to manage appointments on behalf of your patients.

Important: You Are the API Provider

The endpoints documented here are APIs that you must implement and expose for Bot MD to consume. Bot MD acts as the client that calls your APIs to fetch availability, create appointments, and manage patient records.

How the Integration Works

1

You Provide the APIs

Your scheduling system exposes RESTful API endpoints for patient lookup, availability checking, and appointment management.

2

Bot MD Consumes Your APIs

When patients interact with Bot MD via chat (Messenger, Viber, SMS), Bot MD calls your APIs to check availability, book appointments, and manage schedules.

3

You Send Webhooks to Bot MD

When appointments are created, modified, or canceled in your system (e.g., by admin staff), you send webhook notifications to Bot MD's webhook URL so we can notify patients.

Authentication

Your API should use HTTP Basic Authentication. You will provide Bot MD with:

  • A unique USER_ID for each facility
  • A corresponding API_KEY for authentication

Token Lifetime Requirements

  • Preferred: Long-lived tokens that do not expire. This ensures uninterrupted service and avoids authentication failures during off-hours.
  • If expiry is mandatory: Set the token lifetime to a minimum of 90 days.
  • Token refresh: Provide a mechanism for Bot MD to refresh or regenerate tokens before expiry, either via an API endpoint or an admin portal.
# Bot MD will call your API like this:
curl -u PROVIDER_USER_ID:PROVIDER_API_KEY \
  "https://api.provider.example/v1/calendars"

Required API Endpoints

Your scheduling system must implement the following endpoints for Bot MD to consume:

GET/api/v1/calendarsList available calendars/providers
GET/api/v1/patientLook up patient by name, DOB, phone
GET/api/v1/availabilityGet available time slots
POST/api/v1/appointmentsCreate a new appointment
GET/api/v1/appointmentsList appointments for a patient
PUT/api/v1/appointments/:id/rescheduleReschedule an appointment
PUT/api/v1/appointments/:id/cancelCancel an appointment
View detailed endpoint specifications

Webhook Integration

Your system must provide webhook management endpoints so Bot MD can dynamically register, list, and unregister webhook subscriptions at the clinic/hospital level. When events occur, you send notifications to the registered Bot MD webhook URL. All webhook payloads must be signed with HMAC-SHA256 using a shared secret key exchanged during setup.

Webhook Management Endpoints (provided by you)

  • POST/api/v1/webhooksRegister a new webhook subscription
  • GET/api/v1/webhooksList all active subscriptions
  • DELETE/api/v1/webhooks/:idUnregister a subscription

Each subscription is scoped to a specific clinic/hospital via the clinicId parameter. A single registration can subscribe to multiple events at once. Maximum 25 subscriptions per clinic.

Security: Include X-Webhook-Signature: sha256=<hmac_hex_digest> header on every webhook payload

Supported webhook events:

  • • appointmentCreated - When an appointment is booked
  • • appointmentRescheduled - When an appointment time changes
  • • appointmentCanceled - When an appointment is cancelled
  • • patientCreated - When a permanent patient ID is assigned
  • • Queued - When a patient checks in (includes queue number)

Next Steps

API Reference

View detailed endpoint specifications, request/response formats, and code examples.

Integration Flows

See step-by-step user journeys showing how Bot MD interacts with your system.

Use Cases & Data Sync

Understand booking scenarios, data synchronization, and appointment status lifecycle.

API Explorer

Test API endpoints with mock responses to understand expected behavior.

Contact Support

Need help with integration? Reach out to your Bot MD integration specialist.