Files · Voice Agent for No-Show Recovery in Urgent Care and Mental Health

# No-Show Recovery Voice Agent — Urgent Care & Mental Health
 
> Automate appointment no-show recovery with AI voice calls that rebook in under 30 seconds.
 
A tutorialized reference solution from [reaatech.com](https://reaatech.com), demonstrating how to build production-grade AI systems with the `@reaatech/*` package family.
 
## Problem
 
Front-desk receptionists manually call each no-show patient, spending 10-15 minutes per call. With 10-20 no-shows daily, this drains staff time and loses appointment revenue. Most voicemails go unanswered.
 
## Solution
 
This AI voice agent automatically calls no-show patients, understands their availability through natural conversation, and rebooks appointments directly — all in under 30 seconds per call.
 
## Architecture
 
The system is composed of the following components:
 
- **Next.js App Router** — Twilio webhook (`POST /api/twilio`) and health status (`GET /api/status`) routes
- **Hono WebSocket server** — Handles Twilio Media Streams for bidirectional real-time audio
- **`@reaatech/voice-agent-core`** — Pipeline orchestration (STT → MCP → TTS), latency enforcement, and session lifecycle
- **`@reaatech/voice-agent-telephony`** — Twilio Media Streams handler with barge-in detection and call lifecycle management
- **`@reaatech/voice-agent-stt` + `@reaatech/voice-agent-tts`** — Deepgram-based speech-to-text and text-to-speech adapters
- **`@reaatech/session-continuity`** — Multi-turn conversation context with token budgeting, sliding-window compression, and concurrency-safe storage
- **`@reaatech/agent-handoff`** — Escalation routing with configurable confidence thresholds and typed event emitters
- **Vercel AI SDK + `@ai-sdk/openai`** — `generateText` for conversational responses and `generateObject` for structured rebooking intent extraction
- **Langfuse** — LLM observability and latency tracing
- **Twilio REST API** — Outbound call initiation and status callbacks
 
## REAA Packages
 
| Package | Description |
|---|---|
| `@reaatech/voice-agent-core` | Core pipeline orchestration, session management, latency enforcement, configuration, and types for building voice-enabled AI agents |
| `@reaatech/voice-agent-telephony` | Twilio Media Streams WebSocket handler with barge-in detection and full call lifecycle management |
| `@reaatech/voice-agent-stt` | Provider-agnostic speech-to-text interface with Deepgram, AWS Transcribe, and Google Cloud Speech-to-Text adapters |
| `@reaatech/voice-agent-tts` | Provider-agnostic text-to-speech interface with Deepgram Aura, AWS Polly, and Google Cloud Text-to-Speech adapters |
| `@reaatech/session-continuity` | Multi-turn conversation context with token budgeting, sliding-window compression, and concurrency-safe storage |
| `@reaatech/agent-handoff` | Core types, utilities, and configuration for the Agent Handoff Protocol |
 
## Prerequisites
 
- **Twilio account** — A phone number with voice capabilities and your Account SID / Auth Token
- **Deepgram API key** — For speech-to-text and text-to-speech
- **OpenAI API key** — For LLM-powered conversation and structured intent extraction
- **Langfuse account** — For LLM observability tracing
 
## Getting Started
 
```bash
pnpm install
cp .env.example .env
```
 
Fill all 11 environment variables in `.env`, then:
 
```bash
pnpm dev          # Starts Next.js on port 3000 + Hono on port 3001
```
 
Point your Twilio phone number's voice webhook to `https://your-domain/api/twilio`.
 
## API Endpoints
 
| Method | Path | Description |
|---|---|---|
| `POST` | `/api/twilio` | Twilio Voice webhook — returns TwiML to initiate the media stream or acknowledges status callbacks |
| `GET` | `/api/status` | Health check — returns `{ status, timestamp, version, activeCalls }` |
 
## Testing
 
```bash
pnpm test
```
 
Runs vitest with coverage. Expects **≥90%** on lines, branches, functions, and statements across **≥135 tests**.
 
## License
 
MIT — see [LICENSE](./LICENSE).