Files · Mistral AI Voice Agent for ServiceTitan Field Service Scheduling

# Mistral AI Voice Agent for ServiceTitan Field Service Scheduling
 
> After-hours voice agent that books field service jobs directly into ServiceTitan, freeing dispatchers from voicemail and reducing scheduling lag.
 
Field service businesses miss after-hours booking calls, forcing dispatchers to spend mornings returning voicemails and manually entering job details into ServiceTitan, leading to scheduling delays and lost revenue. This voice agent answers those calls, understands spoken requests via Deepgram STT, converses using Mistral AI's LLM, and schedules jobs directly into ServiceTitan's REST API.
 
## Architecture
 
```
Phone Call → Twilio → Voice Webhook → TwiML Response → WebSocket Media Stream
                                                              ↓
                                                    Deepgram STT (via @reaatech/voice-agent-stt)
                                                              ↓
                                                    Mistral AI LLM (via @mistralai/mistralai)
                                                              ↓
                                                    ServiceTitan REST API (jobs + appointments)
                                                              ↓
                                                    Deepgram TTS (via @reaatech/voice-agent-tts)
                                                              ↓
                                                    Audio → Twilio → Caller hears response
```
 
All LLM interactions are cached via `@reaatech/llm-cache` and cost-tracked via `@reaatech/llm-cost-telemetry` with CloudWatch export.
 
## Setup
 
### Prerequisites
- Node.js >= 22
- pnpm >= 10
- Twilio account with a phone number
- Deepgram API key
- Mistral AI API key
- ServiceTitan developer account (OAuth 2.0 credentials)
- AWS account (for CloudWatch cost telemetry - optional)
 
### Environment Variables
 
Copy `.env.example` to `.env` and fill in the values:
 
| Variable | Description |
|----------|-------------|
| `TWILIO_ACCOUNT_SID` | Twilio account SID |
| `TWILIO_AUTH_TOKEN` | Twilio auth token |
| `DEEPGRAM_API_KEY` | Deepgram API key |
| `MISTRAL_API_KEY` | Mistral AI API key |
| `OPENAI_API_KEY` | OpenAI API key (for LLM cache embedder) |
| `SERVICETITAN_CLIENT_ID` | ServiceTitan OAuth client ID |
| `SERVICETITAN_CLIENT_SECRET` | ServiceTitan OAuth client secret |
| `SERVICETITAN_TENANT_ID` | ServiceTitan tenant ID |
| `SERVICETITAN_BASE_URL` | ServiceTitan API base URL |
| `AWS_REGION` | AWS region for CloudWatch |
| `AWS_ACCESS_KEY_ID` | AWS access key (for CloudWatch) |
| `AWS_SECRET_ACCESS_KEY` | AWS secret key (for CloudWatch) |
| `LANGFUSE_PUBLIC_KEY` | Langfuse public key |
| `LANGFUSE_SECRET_KEY` | Langfuse secret key |
| `LANGFUSE_HOST` | Langfuse host |
| `WS_PORT` | WebSocket server port (default: 3001) |
 
### Twilio Webhook Configuration
 
1. In your Twilio console, configure your phone number's voice webhook to point to `https://your-server.com/api/twilio/voice`
2. Configure the status callback URL to `https://your-server.com/api/twilio/status`
 
### Run
 
```bash
pnpm install
pnpm dev             # starts Next.js + WebSocket server
```
 
## How It Works
 
1. **Incoming Call**: Twilio sends a POST to `/api/twilio/voice` which returns TwiML that connects the call to a WebSocket media stream.
2. **Speech-to-Text**: Audio from the caller is streamed via WebSocket to Deepgram's STT (via `@reaatech/voice-agent-stt`).
3. **Intent Understanding**: Transcribed text is classified by Mistral AI (via `@mistralai/mistralai`) to determine if the caller wants to book, inquire, cancel, or reschedule.
4. **Data Extraction**: Job details (customer name, address, phone, issue description) are extracted from the conversation.
5. **Booking**: When confirmed, a job and appointment are created in ServiceTitan via its REST API.
6. **Text-to-Speech**: Responses are synthesized via Deepgram TTS (via `@reaatech/voice-agent-tts`) and streamed back to the caller.
7. **Cost Tracking**: Every LLM call is recorded by `@reaatech/llm-cost-telemetry` and can be exported to CloudWatch.
 
## Project Layout
 
```
app/api/twilio/voice/route.ts    Incoming voice webhook handler
app/api/twilio/status/route.ts   Call status callback handler
src/api/twilio-webhook.ts        TwiML generation + Twilio client
src/api/twilio-media-stream.ts   WebSocket media stream handler
src/lib/config.ts                Zod-validated environment config
src/lib/mistral.ts               Mistral AI client
src/services/servicetitan.ts     ServiceTitan REST API client
src/services/voice-agent.ts       Core orchestrator
src/services/llm-cache.ts        LLM response cache (exact + semantic)
src/services/cost-tracker.ts     LLM cost telemetry
src/instrumentation.ts           Next.js startup bootstrap
tests/                           Vitest suite (mirrors src/)
```
 
## License
 
MIT — see [LICENSE](./LICENSE).