Files · Azure AI Voice Agent for Freshservice ITSM Ticket Creation

# Azure AI Voice Agent for Freshservice ITSM Ticket Creation
 
Employees call a dedicated number, describe their IT issue, and a Freshservice ticket is created automatically – no typing, no portal login.
 
## Problem
SMB employees lose time logging into Freshservice to report IT problems; phone calls are faster but create manual data entry. Without voice integration, small IT teams face delays.
 
## How It Works
1. Employee calls a configured Twilio phone number
2. Twilio sends the audio stream to the voice-agent-core pipeline
3. Speech-to-text (Deepgram via @reaatech/voice-agent-stt) transcribes the caller's issue
4. Azure AI inference processes the transcribed text to extract ticket details
5. @reaatech/structured-repair-core validates and repairs the LLM output against Freshservice's schema
6. The Freshservice REST API creates the ticket (POST /api/v2/tickets)
7. Text-to-speech (Deepgram Aura via @reaatech/voice-agent-tts) reads the confirmation back to the caller
 
## Architecture
- **Inbound call webhook**: `app/api/webhook/route.ts` — returns TwiML that connects the call to a WebSocket Media Stream
- **WebSocket server**: `src/instrumentation.ts` — starts a WebSocket server for Twilio Media Streams via the Node.js `ws` package
- **Media stream handler**: `src/routes/webhook.ts` — uses @reaatech/voice-agent-telephony to normalize Twilio's bidirectional streaming protocol
- **Agent pipeline**: `src/voice/agent.ts` — orchestrates STT → Azure AI (MCP) → TTS using @reaatech/voice-agent-core
- **Ticket creation**: `src/handlers/ticket-creation.ts` — uses @reaatech/structured-repair-core to map spoken details to Freshservice fields
- **Freshservice API**: `src/lib/freshservice-client.ts` — REST client for Freshservice ticket CRUD
- **Ticket status**: `app/api/tickets/[id]/route.ts` — check ticket status after creation
 
## Prerequisites
- Node.js >= 22
- pnpm 10.x
- A Twilio account with a phone number that has Voice capabilities
- A Deepgram API key (for STT and TTS)
- An Azure AI Foundry resource with a model deployment (for LLM inference)
- A Freshservice account with API key
 
## Setup
1. Clone this repo
2. Copy `.env.example` to `.env` and fill in all values
3. Run `pnpm install`
4. Configure your Twilio phone number:
   - Set the "A call comes in" webhook to `https://your-domain.com/api/webhook`
   - Set the HTTP method to POST
5. Run `pnpm dev`
6. Call your Twilio number and describe your IT issue
 
## Project Structure
| File | Purpose |
|------|---------|
| `app/api/webhook/route.ts` | Twilio incoming call webhook (returns TwiML) |
| `app/api/tickets/[id]/route.ts` | Ticket status lookup API |
| `src/lib/config.ts` | Environment configuration loader |
| `src/lib/freshservice-client.ts` | Freshservice REST API client |
| `src/lib/azure-ai-client.ts` | Azure AI inference client |
| `src/handlers/ticket-creation.ts` | Ticket creation with structured-repair-core |
| `src/voice/agent.ts` | Voice agent pipeline (STT → LLM → TTS) |
| `src/routes/webhook.ts` | Twilio Media Stream WebSocket handler |
| `src/instrumentation.ts` | WebSocket server bootstrap |
| `src/types/freshservice.ts` | Freshservice type definitions |
| `src/types/voice.ts` | Voice agent type definitions |
 
## Environment Variables
See `.env.example` for all required variables.
 
## License
MIT