OpenAI Voice Agent for ServiceTitan Field Service Dispatch

Handle phone dispatch for home service businesses, converting voice instructions into ServiceTitan work orders automatically.

openai voice-agent servicetitan field-service dispatch twilio deepgram nextjs typescript

The problem

Field service companies lose after-hours calls from customers needing emergency dispatch; an AI agent that answers calls, captures job details, and creates work orders in ServiceTitan without human intervention would recover lost revenue.

Built from

Intro

In this tutorial, you’ll build an AI-powered voice agent that answers phone calls for field service businesses, converts voice instructions into ServiceTitan work orders, and handles the full dispatch workflow automatically. The agent uses OpenAI for LLM orchestration, Deepgram for speech-to-text, Cartesia for text-to-speech, and Twilio for telephony. You’ll wire up a confidence router that classifies caller intent, an MCP client for tool execution, and a session store that keeps conversation context across turns.

Prerequisites

Node.js 22+ and pnpm 10+ installed
A Twilio account with a phone number that has voice capability and Media Streams enabled
A Deepgram account with an API key (for real-time STT)
A Cartesia account with an API key (for TTS)
An OpenAI API key
A ServiceTitan developer account with client credentials (client ID, client secret, tenant ID, app key)
Familiarity with TypeScript, Next.js App Router, and REST APIs

Step 1: Create the Next.js project and install dependencies

Start by creating a new Next.js project with the App Router and installing all dependencies.

terminal

npx create-next-app@latest openai-voice-agent-for-servicetitan-field-service-dispatch --typescript --app --src-dir
cd openai-voice-agent-for-servicetitan-field-service-dispatch

Example artifact

A complete, working implementation of this recipe — downloadable as a zip or browsable file by file. Generated by our build pipeline; tested with full coverage before publishing.

Download example (zip)Browse files

159 kB·111 tests·99.4% coverage·vitest passing

SHA-2561b3f8a221b8cc993cc51f8e51295cddfb085f757cb3f742937225b7cdfe7e149

Book a conversation All solutions

Comments

Loading comments…

import { describe, it, expect, beforeEach } from "vitest"; import { SessionNotFoundError } from "@reaatech/session-continuity"; import { createSessionStore } from "../../src/lib/session-store.js"; describe("session-store", () => { const manager = createSessionStore(); beforeEach(async () => { const sessions = await manager.listSessions(); for (const s of sessions) { await manager.deleteSession(s.id); } }); it("createSession returns session with auto-generated id, status active, createdAt", async () => { const session = await manager.createSession({ userId: "test-user" }); expect(session.id).toBeDefined(); expect(session.id.length).toBeGreaterThan(0); expect(session.status).toBe("active"); expect(session.createdAt).toBeInstanceOf(Date); }); it("addMessage on valid session adds message and updates lastActivityAt", async () => { const session = await manager.createSession(); const originalLastActivity = session.lastActivityAt; await new Promise((r) => setTimeout(r, 5)); await manager.addMessage(session.id, { role: "user", content: "Hello" }); const updated = await manager.getSession(session.id); expect(updated.lastActivityAt.getTime()).toBeGreaterThan(originalLastActivity.getTime()); const messages = await manager.getMessages(session.id); expect(messages).toHaveLength(1); expect(messages[0].content).toBe("Hello"); }); it("getConversationContext returns messages in insertion order", async () => { const session = await manager.createSession(); await manager.addMessage(session.id, { role: "user", content: "first" }); await manager.addMessage(session.id, { role: "assistant", content: "second" }); await manager.addMessage(session.id, { role: "user", content: "third" }); const context = await manager.getConversationContext(session.id); expect(context).toHaveLength(3); expect(context[0].content).toBe("first"); expect(context[1].content).toBe("second"); expect(context[2].content).toBe("third"); }); it("getSession nonexistent throws SessionNotFoundError", async () => { await expect(manager.getSession("nonexistent")).rejects.toThrow(SessionNotFoundError); }); it("endSession valid-id sets status to completed", async () => { const session = await manager.createSession(); await manager.endSession(session.id); const ended = await manager.getSession(session.id); expect(ended.status).toBe("completed"); }); });

import { describe, it, expect, vi, beforeAll, beforeEach } from 'vitest'; import { NextRequest } from 'next/server'; import { GET } from '../../../../app/api/servicetitan/oauth/route.js'; const MockServiceTitanError = vi.hoisted(() => { return class extends Error { status: number; code: string; constructor(status: number, code: string, message: string) { super(message); this.status = status; this.code = code; this.name = 'MockServiceTitanError'; } }; }); const mockGetOAuthToken = vi.hoisted(() => vi.fn()); vi.mock('../../../../src/lib/servicetitan-client.js', () => { const MockClient = class { getOAuthToken: () => Promise<unknown>; close: () => void; constructor() { this.getOAuthToken = mockGetOAuthToken; this.close = () => {}; } }; return { ServiceTitanClient: MockClient, ServiceTitanError: MockServiceTitanError, }; }); beforeAll(() => { process.env.SERVICETITAN_CLIENT_ID = 'test-id'; process.env.SERVICETITAN_CLIENT_SECRET = 'test-secret'; process.env.SERVICETITAN_TENANT_ID = '42'; process.env.SERVICETITAN_APP_KEY = 'test-key'; }); beforeEach(() => { vi.clearAllMocks(); }); describe('GET /api/servicetitan/oauth', () => { it('returns 200 with ok:true when code is provided', async () => { mockGetOAuthToken.mockResolvedValue({ accessToken: 'test', tokenType: 'Bearer', expiresAt: Date.now() + 3600000, }); const request = new NextRequest( 'http://localhost:3000/api/servicetitan/oauth?code=***&state=tenant_42', ); const response = await GET(request); expect(response.status).toBe(200); const body = await response.json() as { ok: boolean }; expect(body).toEqual({ ok: true }); }); it('returns 400 with error when code is missing', async () => { const request = new NextRequest( 'http://localhost:3000/api/servicetitan/oauth', ); const response = await GET(request); expect(response.status).toBe(400); const body = await response.json() as { error: string }; expect(body).toEqual({ error: 'missing code' }); }); it('returns 502 with error when getOAuthToken throws ServiceTitanError', async () => { const error = new MockServiceTitanError( 401, 'AUTH_ERROR', 'Invalid credentials', ); mockGetOAuthToken.mockRejectedValue(error); const request = new NextRequest( 'http://localhost:3000/api/servicetitan/oauth?code=***', ); const response = await GET(request); expect(response.status).toBe(502); const body = await response.json() as { error: string }; expect(body).toEqual({ error: 'Invalid credentials' }); }); });

OpenAI Voice Agent for ServiceTitan Field Service Dispatch

The problem

Built from

Intro

Prerequisites

Step 1: Create the Next.js project and install dependencies

Example artifact

Comments

Intro

Prerequisites

Step 1: Create the Next.js project and install dependencies

Step 2: Configure environment variables

Step 3: Create the ServiceTitan OAuth2 client

Step 4: Create the session store with in-memory storage

Step 5: Create the confidence router for intent classification

Step 6: Create the ServiceTitan MCP tool definitions

Step 7: Create the dispatch agent orchestrator

Step 8: Create the pipeline configuration

Step 9: Enable instrumentation with OpenTelemetry

Step 10: Create the Twilio voice webhook parser

Step 11: Create the Twilio voice webhook route

Step 12: Create the WebSocket stream route

Step 13: Create the ServiceTitan OAuth callback route

Step 14: Write the tests

ServiceTitan client tests

Session store tests

Confidence router tests

Twilio voice API route tests

ServiceTitan OAuth API route test

Step 15: Run typecheck, lint, and tests

Next steps