Mobile App Booking Integration¶
HMIS supports patient-facing mobile applications that allow patients to browse available channelling sessions, book appointments, view their booking history, and receive notifications — all without visiting the hospital front desk.
Audience¶
This article is aimed at mobile app developers and IT administrators integrating a patient-facing app with HMIS channelling.
Integration Architecture¶
Patient App (iOS / Android)
↓ HTTPS REST calls
HMIS Channelling API (/api/channel/*)
↓
HMIS Core (bookings, sessions, patients, bills)
↑ WebSocket push
Patient App (real-time updates)
The app communicates exclusively through the Channelling API. No direct database access is used.
Typical Mobile App Flows¶
1 — Browse Available Sessions¶
GET /api/channel/specialities
GET /api/channel/consultants?specialityId={id}
GET /api/channel/sessions?consultantId={id}&fromDate=2026-05-18&toDate=2026-05-25
Present the list of available session instances to the patient with:
- Consultant name, photo, qualifications
- Session date, start time
- Available slots / tokens remaining
- Fee
2 — Patient Login / Registration¶
Patients must be identified before booking:
- Existing patient: Search by NIC, phone number, or patient ID:
- New patient: Register:
3 — Create a Booking¶
POST /api/channel/bookings
{
"sessionInstanceId": 12345,
"patientId": 67890,
"paymentMethod": "OnCall",
"itemId": 111
}
Response includes:
- Booking ID
- Token / serial number
- Total fee
- Bill reference
4 — View Booking History¶
Returns all bookings for the patient (past and upcoming) with status.
5 — Cancel a Booking¶
6 — Real-Time Notifications¶
Subscribe to the WebSocket endpoint for push notifications:
When a session status changes (e.g., doctor has arrived, queue is started), the app receives a push message and can update the UI accordingly.
Online Booking Bill Type¶
Bookings created through the mobile app are recorded in HMIS with a dedicated bill type:
CHANNEL_BOOKING_FOR_PAYMENT_ONLINE_COMPLETED_PAYMENT
These bookings appear in the Channel Booking View with a yellow "OB" tag and the online reference number. No manual re-entry is required — the booking flows into the same queue as front-desk bookings.
Payment Integration¶
Mobile app payments can be handled in two ways:
| Method | Description |
|---|---|
| OnCall | Patient books online but pays at the hospital on arrival |
| Online Payment Gateway | Payment is collected in-app via a payment gateway (requires additional integration with the gateway and HMIS payment confirmation API) |
For online payment gateway integration, refer to the gateway provider's documentation and the HMIS payment API endpoints (documented in Swagger/DOC990).
Push Notifications (FCM / APNs)¶
In addition to WebSocket updates for in-app notifications, the mobile app should implement:
- FCM (Firebase Cloud Messaging) for Android background notifications
- APNs for iOS background notifications
HMIS can be configured to send push notification payloads to an intermediary server that dispatches them to FCM/APNs. This requires:
- Setting up a notification relay server
- Configuring the HMIS push notification endpoint with the relay server URL and credentials
Contact the HMIS technical team for the push notification API specification.
App Requirements and Features Checklist¶
| Feature | Status |
|---|---|
| Session search by speciality and consultant | API available |
| Session availability and slot count | API available |
| Patient registration and search | API available |
| Booking creation | API available |
| Booking cancellation | API available |
| Booking history | API available |
| WebSocket real-time session updates | API available |
| SMS confirmation (server-side) | Handled by HMIS automatically |
| Online payment gateway | Requires additional integration |
| Push notifications (FCM/APNs) | Requires relay server setup |
| Audio/video consultation scheduling | Future feature — refer to current roadmap |