Patient Communication

Patient Communication

DELPHOS provides several channels for patient-facing scheduling interactions including webhooks for event notifications, a conversation engine for multi-turn chat scheduling, natural language processing, voice scheduling, no-show risk prediction, and a waitlist system.

---

Webhooks

Subscribe to scheduling events to receive real-time notifications when appointments are created, updated, or transition through lifecycle states.

Create a webhook subscription

POST /v1/scheduling/webhooks

List subscriptions

GET /v1/scheduling/webhooks

Get a subscription

GET /v1/scheduling/webhooks/{webhook_id}

Update a subscription

PUT /v1/scheduling/webhooks/{webhook_id}

Deactivate a subscription

DELETE /v1/scheduling/webhooks/{webhook_id}

Soft-delete — sets the subscription inactive. Returns 204.

Send a test event

POST /v1/scheduling/webhooks/{webhook_id}/test

Sends a test delivery to verify your endpoint is reachable and handling payloads correctly.

View delivery history

GET /v1/scheduling/webhooks/{webhook_id}/deliveries

Returns recent delivery attempts with status and response codes.

View dead-letter queue

GET /v1/scheduling/webhooks/dead-letters

Returns failed deliveries that exhausted retry attempts.

---

Conversation Engine

The conversation engine processes patient messages through a multi-turn finite state machine (FSM) scheduling pipeline. It maintains state between turns and guides the patient through selecting a provider, date, time, and appointment type.

Process a conversation message

POST /v1/scheduling/conversation

Accepts a patient message and returns the next response in the scheduling conversation, along with updated intent/entity state.

Get conversation state (debug)

GET /v1/scheduling/conversation/{patient_id}/{channel}/state

Returns the current FSM state for debugging and monitoring.

Clear conversation state

DELETE /v1/scheduling/conversation/{patient_id}/{channel}

Resets the conversation, discarding all accumulated entities and state.

---

Natural Language Scheduling

Process free-text scheduling requests in Brazilian Portuguese. Extracts scheduling intents and entities (provider, date, time, appointment type), resolves them against the database, and returns structured scheduling data.

POST /v1/scheduling/natural-language

curl

curl -X POST "https://your-instance.delphos.app/v1/scheduling/natural-language" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Quero marcar uma consulta com o Dr. Silva para semana que vem de manha",
    "patient_id": "d4e5f6a7-b8c9-0123-defa-234567890123"
  }'

Python

import httpx

response = httpx.post(
    "https://your-instance.delphos.app/v1/scheduling/natural-language",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "message": "Quero marcar uma consulta com o Dr. Silva para semana que vem de manha",
        "patient_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
    },
)
result = response.json()

Returns an NLResponse with extracted entities, resolved database references, and suggested available slots matching the expressed intent.

---

Voice Scheduling

Process audio recordings to extract scheduling intent. Accepts multipart/form-data with an audio file, transcribes it, extracts scheduling intent, and returns structured data.

POST /v1/scheduling/voice

LGPD Compliance

Audio data is processed exclusively in-memory. No audio bytes are written to disk, logged, or stored in any persistence layer. Audio data is freed immediately after transcription.

curl

curl -X POST "https://your-instance.delphos.app/v1/scheduling/voice" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "audio=@recording.wav" \
  -F "patient_id=d4e5f6a7-b8c9-0123-defa-234567890123"

Python

import httpx

with open("recording.wav", "rb") as f:
    response = httpx.post(
        "https://your-instance.delphos.app/v1/scheduling/voice",
        headers={"x-api-key": "YOUR_API_KEY"},
        files={"audio": ("recording.wav", f, "audio/wav")},
        data={"patient_id": "d4e5f6a7-b8c9-0123-defa-234567890123"},
    )
result = response.json()

Returns a VoiceSchedulingResponse with the transcribed text, extracted entities, and scheduling suggestions. Returns a VoiceClarificationResponse when the audio is ambiguous and a follow-up question is needed.

---

No-Show Risk Prediction

Predict the likelihood that a patient will not attend their appointment, enabling proactive outreach and reminder scheduling.

Get risk for a single appointment

GET /v1/scheduling/no-show/appointments/{appointment_id}/risk

Returns a NoShowRiskResponse with:

Field	Description
risk_score	Probability of no-show (0.0–1.0)
risk_level	Classified level: low, medium, or high
risk_factors	List of contributing factors with individual impact scores
recommendation	Suggested action based on risk level

Get daily batch risk scores

GET /v1/scheduling/no-show/daily-risks

Returns risk scores for all upcoming appointments on a given date. Accepts a date query parameter (defaults to today).

Model information

GET /v1/scheduling/no-show/model-info

Returns metadata about the currently loaded prediction model, including version, training date, and feature descriptions.

---

Waitlist

Manage a waitlist queue for appointment slots. When a slot opens, patients on the waitlist are notified in queue order.

Add to waitlist

POST /v1/scheduling/waitlist

Field	Type	Required	Description
patient_id	UUID	Yes	Patient to add to waitlist
provider_profile_id	UUID	Yes	Desired provider
appointment_type_id	UUID	Yes	Desired appointment type
(additional preference fields)

Returns 201. Returns 409 if the patient is already on the waitlist for this provider and appointment type.

List waitlist entries

GET /v1/scheduling/waitlist

Remove from waitlist

DELETE /v1/scheduling/waitlist/{waitlist_id}

Returns 204.

Get queue position

GET /v1/scheduling/waitlist/position/{waitlist_id}

Returns the patient’s current position in the queue and an estimated wait time based on historical slot release frequency.