How osamaqh4/hospital-voice-agent works
This is a Telnyx voice assistant for hospital appointment administration across General Medicine, Pediatrics, and Dental. A caller speaks with the Telnyx assistant, whose conversation flow handles intent, FAQs, and emergency escalation. At call start, a signed webhook normalizes the caller identity, records the call, and supplies patient and department context. During the call, the assistant invokes MCP tools to check or change appointments, find slots, and send confirmations. Patient records use the shared actor-or-KV abstraction; department data and the same-day-slots flag use KV. The conversation flow is documented in the exported JSON; links among its individual nodes reflect that documentation.
Main entry points: src/index.ts MCP tool server · conversation-flow.json Identify intent · src/index.ts Dynamic variables handler · patientRecords.ts Patient record selector
Components 19
Voice conversation
- Telnyx AI assistant
- Identify intent
docs/conversation-flow.json - Existing appointment
docs/conversation-flow.json - Book appointment
docs/conversation-flow.json - Department FAQ
docs/conversation-flow.json - Emergency escalation
docs/conversation-flow.json - Close call
docs/conversation-flow.json
Call initialization
- Dynamic variables handler
webhook-function/src/index.ts - Phone normalization
webhook-function/src/lib/phone.ts
Appointment tools
- MCP tool server
mcp-server/src/index.ts - Patient record client
mcp-server/src/lib/patientActorClient.ts - Slot scheduling
mcp-server/src/lib/scheduling.ts - SMS sender
mcp-server/src/lib/telnyxApi.ts
State and integrations
- Patient record selector
webhook-function/src/lib/patientRecords.ts - Patient actor
webhook-function/src/actors/patientActor.ts - Patient records KV
webhook-function/src/lib/patientRecords.ts - Department KV data
webhook-function/src/lib/kv.ts
Other components
- Caller
- Telnyx Messaging
Connections 26
- Caller → Telnyx AI assistant: calls
- Telnyx AI assistant → Dynamic variables handler: requests call context
- Telnyx AI assistant → MCP tool server: invokes tools
- Telnyx AI assistant → Identify intent: runs flow
- Identify intent → Existing appointment: routes appointment requests
- Identify intent → Book appointment: routes booking
- Identify intent → Department FAQ: routes questions
- Identify intent → Emergency escalation: escalates emergencies
- Department FAQ → Emergency escalation: escalates emergencies
- Existing appointment → Close call: ends call
- Book appointment → Close call: ends call
- Department FAQ → Close call: ends call
- Emergency escalation → Close call: ends call
- Dynamic variables handler → Phone normalization: normalizes caller
- Dynamic variables handler → Patient record selector: records call
- Dynamic variables handler → Department KV data: reads directory and flag
- Dynamic variables handler → Telnyx AI assistant: returns dynamic variables
- Patient record selector → Patient actor: selects when enabled
- Patient record selector → Patient records KV: reads and writes fallback
- MCP tool server → Phone normalization: normalizes patient number
- MCP tool server → Patient record client: dispatches patient operations
- Patient record client → Patient record selector: accesses patient records
- MCP tool server → Department KV data: reads slots flag and directory
- MCP tool server → Slot scheduling: computes available slots
- MCP tool server → SMS sender: sends confirmation
- SMS sender → Telnyx Messaging: sends SMS