OpenAI Realtime API Voice Agent

\n\n

\n\n \n \n",[],[154,172],[154],{"_102":181,"_95":182,"_155":183,"_157":-5,"_158":136,"_159":135,"_160":161,"_104":184,"_99":32,"_163":164,"_165":-5,"_166":22,"_167":-5,"_168":185,"_98":227},"26f749b4-a9c0-11f0-baae-0224a6c84d84","routes","0199e7c8-cadd-7359-9ff3-59a5a0b6dab2",["D",1760530320030],[186,195,203,211,219],{"_102":187,"_95":188,"_155":189,"_157":183,"_158":136,"_159":135,"_160":161,"_104":190,"_99":32,"_163":191,"_165":192,"_166":22,"_167":-5,"_168":193,"_98":194},"26f73d66-a9c0-11f0-baae-0224a6c84d84","agent.ts","0199e7c8-cadd-7359-9ff3-46ace53f7061",["D",1760530320030],"script","import { ObserverClient, ObserverHandler } from \"./observer.ts\";\nimport { getErrorText, makeHeaders, makeUrl } from \"./utils.ts\";\n\nconst MODEL = \"gpt-realtime\";\nconst TRANSCRIBE_MODEL = \"gpt-4o-transcribe\";\nconst NR_TYPE = \"near_field\";\nconst INSTRUCTIONS = `\n Greet the user in English and tell them that they're using the OpenAI Realtime API, powered by the {{model}} model.\n Give them a very brief summary of the benefits of the Realtime API based on the headline below,\n and then ask if they have any questions.\n Answer questions using the information below. For questions outside this scope,\n apologize and say you can't help with that.\n When the user says goodbye or you think the call is over, say a brief goodbye and then\n invoke the end_call function.\n ---\n Headline:\n - The Realtime API is now generally available, and is easier to develop for. There's also a new telephony integration for phone scenarios.\n Full list of improvements:\n - generally available (no longer in beta)\n - two new voices (Cedar and Marin)\n - improved instruction following\n - enhanced voice naturalness\n - higher audio quality\n - improved handling of alphanumerics (eg, properly understanding credit card and phone numbers)\n - support for the OpenAI Prompts API\n - support for MCP-based tools\n - auto-truncation to reduce context size\n - native telephony support, making it simple to connect voice calls to existing Realtime API applications\n - when using WebRTC, you can connect without needing an ephemeral token\n - when using WebRTC, you can now control sessions (including tool calls) from the server\n - when using WebRTC, you can now send video to the model, and it can respond based on what it sees\n - many helpful bugfixes!\n`;\nconst VOICE = \"marin\";\nconst HANGUP_TOOL = {\n type: \"function\",\n name: \"end_call\",\n description: `\n Use this function to hang up the call when the user says goodbye \n or otherwise indicates they are about to end the call.`,\n};\n\n// Builds the declarative session configuration for a Realtime API session.\nexport function makeSession(modelOverride?: string) {\n const model = modelOverride || MODEL;\n const instructions = INSTRUCTIONS.replace(\"{{model}}\", model);\n return {\n type: \"realtime\",\n model,\n instructions,\n audio: {\n input: {\n noise_reduction: { type: NR_TYPE },\n transcription: { model: TRANSCRIBE_MODEL },\n },\n output: { voice: VOICE },\n },\n tools: [HANGUP_TOOL],\n };\n}\n\n// AgentHandler implements the agent runtime behavior (tool calling, etc).\nclass AgentHandler implements ObserverHandler {\n private audioActive = false;\n private callEnding = false;\n constructor(private client: ObserverClient, private callId: string) {}\n async onInit() {\n // Trigger a response immediately, with a slight delay to prevent clipping.\n setTimeout(() => this.client.createResponse(), 250);\n }\n async onTool(name: string, _args: any) {\n // If audio is playing, defer the hangup until it finishes.\n // Otherwise, end the call now.\n if (name == HANGUP_TOOL.name) {\n if (this.audioActive) {\n this.callEnding = true;\n } else {\n await this.hangup();\n }\n }\n }\n async onOutputAudioStarted() {\n this.audioActive = true;\n }\n async onOutputAudioStopped() {\n // Shut down the call and websocket once audio has finished spooling.\n this.audioActive = false;\n if (this.callEnding) {\n await this.hangup();\n }\n }\n async onOutputAudioCleared() {\n this.audioActive = false;\n }\n private async hangup() {\n const url = makeUrl(this.callId, \"hangup\");\n const resp = await fetch(url, { method: \"POST\", headers: makeHeaders() });\n if (!resp.ok) {\n console.error(`🔴 end call failed: ${await getErrorText(resp)}`);\n return;\n }\n\n console.log(\"✅ call ended\");\n }\n}\n\n// Creates the runtime handler for the session.\nexport function createHandler(client: ObserverClient, callId: string) {\n return new AgentHandler(client, callId);\n}",[],[182,188],{"_102":196,"_95":197,"_155":198,"_157":183,"_158":136,"_159":135,"_160":161,"_104":199,"_99":32,"_163":191,"_165":200,"_166":22,"_167":-5,"_168":201,"_98":202},"26f74220-a9c0-11f0-baae-0224a6c84d84","observer.ts","0199e7c8-cadd-7359-9ff3-48489864ce81",["D",1760530320030],"import { Hono } from \"npm:hono\";\nimport WebSocket from \"npm:ws\";\nimport { createHandler } from \"./agent.ts\";\nimport { makeHeaders, makeUrl } from \"./utils.ts\";\n\nexport interface ObserverHandler {\n onInit(): void;\n onTool(name: string, args: any): void;\n onOutputAudioStarted(): void;\n onOutputAudioStopped(): void;\n onOutputAudioCleared(): void;\n}\n\nexport class ObserverClient {\n private ws: WebSocket;\n private closeResolve: () => void;\n private closePromise: Promise;\n private handler: ObserverHandler;\n\n constructor(callId: string) {\n const url = makeUrl(callId);\n this.ws = new WebSocket(url, { headers: makeHeaders() });\n this.ws.on(\"open\", () => this.handleOpen());\n this.ws.on(\"message\", (data) => this.handleMessage(JSON.parse(data)));\n this.ws.on(\"error\", (err) => this.handleError(err));\n this.ws.on(\"close\", (ev) => this.handleClose(ev));\n this.closePromise = new Promise((resolve) =>\n this.closeResolve = resolve\n );\n this.handler = createHandler(this, callId);\n }\n createResponse() {\n this.sendMessage({ type: \"response.create\" });\n }\n async waitForClose() {\n await this.closePromise;\n }\n private sendMessage(message: any) {\n this.ws.send(JSON.stringify(message));\n }\n private handleOpen() {\n console.log(\"✅ websocket connected\");\n this.handler.onInit();\n }\n private async handleMessage(message: any) {\n if (!message.type.endsWith(\".delta\")) { // ignore verbose messages\n console.log(message);\n }\n switch (message.type) {\n case \"response.function_call_arguments.done\":\n this.handler.onTool(message.name, message.arguments);\n break;\n case \"output_audio_buffer.started\":\n this.handler.onOutputAudioStarted();\n break;\n case \"output_audio_buffer.stopped\":\n this.handler.onOutputAudioStopped();\n break;\n case \"output_audio_buffer.cleared\":\n this.handler.onOutputAudioCleared();\n break;\n }\n }\n private handleError(err: Error) {\n console.error(`🔴 websocket failed: ${err.message}`);\n this.closeResolve();\n }\n private handleClose(e: Event) {\n console.log(`websocket closed: ${e}`);\n this.closeResolve();\n }\n}\n\nconst observer = new Hono();\n\n// POST /observer/:callId : self-connect to establish a web socket\nobserver.post(\"/:callId\", async (c) => {\n const callId = c.req.param(\"callId\");\n const client = new ObserverClient(callId);\n await client.waitForClose();\n return c.newResponse(null);\n});\n\nexport default observer;",[],[182,197],{"_102":204,"_95":205,"_155":206,"_157":183,"_158":136,"_159":135,"_160":161,"_104":207,"_99":32,"_163":191,"_165":208,"_166":22,"_167":-5,"_168":209,"_98":210},"26f744e6-a9c0-11f0-baae-0224a6c84d84","rtc.ts","0199e7c8-cadd-7359-9ff3-4cbdffd4adb0",["D",1760530320030],"import { Hono } from \"npm:hono\";\nimport { makeSession } from \"./agent.ts\";\nimport { getErrorText, makeHeaders, makeUrl } from \"./utils.ts\";\n\nconst rtc = new Hono();\n\n// POST /rtc : create a new call\nrtc.post(\"/\", async (c) => {\n // Extract model parameter from URL if provided\n const model = c.req.query(\"model\");\n if (model !== undefined) {\n console.log(\"🔧 Model parameter received:\", model);\n }\n \n // Create the call.\n const fd = new FormData();\n fd.set(\"sdp\", await c.req.text());\n fd.set(\"session\", JSON.stringify(makeSession(model)));\n const opts = { method: \"POST\", headers: makeHeaders(), body: fd };\n const resp = await fetch(makeUrl(), opts);\n if (!resp.ok) {\n console.error(`🔴 start call failed: ${await getErrorText(resp)}`);\n return c.text(\"Internal error\", 500);\n }\n\n const contentType = resp.headers.get(\"Content-Type\");\n const location = resp.headers.get(\"Location\");\n const callId = location?.split(\"/\").pop();\n console.log(\"✅ call created:\", callId);\n\n // Kick off observer in the background (fire-and-forget).\n const selfUrl = new URL(c.req.url);\n fetch(`${selfUrl.origin}/observer/${callId}`, { method: \"POST\" })\n .catch((e) => console.error(\"observer start failed:\", e));\n\n const responseHeaders = {\n \"Content-Type\": contentType,\n \"Location\": location,\n };\n return c.newResponse(resp.body, { headers: responseHeaders });\n});\n\nexport default rtc;",[],[182,205],{"_102":212,"_95":213,"_155":214,"_157":183,"_158":136,"_159":135,"_160":161,"_104":215,"_99":32,"_163":191,"_165":216,"_166":22,"_167":-5,"_168":217,"_98":218},"26f7461c-a9c0-11f0-baae-0224a6c84d84","sip.ts","0199e7c8-cadd-7359-9ff3-50ed2b4a20fb",["D",1760530320030],"import { Hono } from \"npm:hono\";\nimport { Webhook } from \"npm:svix\";\nimport { makeSession } from \"./agent.ts\";\nimport { getErrorText, makeHeaders, makeUrl } from \"./utils.ts\";\n\nconst sip = new Hono();\n\n// POST /sip : webhook endpoint\nsip.post(\"/\", async (c) => {\n // Verify the webhook.\n const OPENAI_SIGNING_SECRET = Deno.env.get(\"OPENAI_SIGNING_SECRET\");\n if (!OPENAI_SIGNING_SECRET) {\n console.error(\"🔴 webhook secret not configured\");\n return c.text(\"Internal error\", 500);\n }\n const webhook = new Webhook(OPENAI_SIGNING_SECRET);\n const bodyStr = await c.req.text();\n let callId: string | undefined;\n let toNumber: string | undefined;\n try {\n const headers = Object.fromEntries(c.req.raw.headers.entries());\n const payload: any = webhook.verify(bodyStr, headers);\n callId = payload.data.call_id;\n toNumber = getToNumber(payload.data.sip_headers);\n const fromNumber = getFromNumber(payload.data.sip_headers);\n console.log(\"✅ verified webhook:\", callId, fromNumber, toNumber);\n } catch (error) {\n console.error(`🔴 verify failed: ${error}`);\n return c.text(\"Invalid signature\", 401);\n }\n\n // Accept the call.\n const model = getModelForNumber(toNumber);\n const url = makeUrl(callId, \"accept\");\n const headers = makeHeaders(\"application/json\");\n const body = JSON.stringify(makeSession(model));\n const opts = { method: \"POST\", headers, body };\n const resp = await fetch(url, opts);\n if (!resp.ok) {\n console.error(`🔴 accept failed: ${await getErrorText(resp)}`);\n return c.text(\"Internal error\", 500);\n }\n console.log(\"✅ call accepted:\", callId);\n\n // Kick off observer in the background (fire-and-forget).\n const selfUrl = new URL(c.req.url);\n fetch(`${selfUrl.origin}/observer/${callId}`, { method: \"POST\" })\n .catch((e) => console.error(\"observer start failed:\", e));\n\n return c.newResponse(null);\n});\n\nconst getToNumber = headers => getNumberFromSipHeader(headers, \"to\");\nconst getFromNumber = headers => getNumberFromSipHeader(headers, \"from\");\n\nfunction getNumberFromSipHeader(headers: any, name: string) {\n const header = getSipHeader(headers, name);\n const match = header?.match(/sip:\\+?(\\d+)@/);\n return match ? `+${match[1]}` : undefined;\n}\n\nfunction getSipHeader(headers: any, name: string) {\n return headers.find((h) => h.name.toLowerCase() === name)?.value;\n}\n\nfunction getModelForNumber(number: string) {\n const map = { \"+14258000074\": \"gpt-realtime-mini\" };\n return map[number];\n}\n\nexport default sip;",[],[182,213],{"_102":220,"_95":221,"_155":222,"_157":183,"_158":136,"_159":135,"_160":161,"_104":223,"_99":32,"_163":191,"_165":224,"_166":22,"_167":-5,"_168":225,"_98":226},"26f74892-a9c0-11f0-baae-0224a6c84d84","utils.ts","0199e7c8-cadd-7359-9ff3-54449e320b2a",["D",1760530320030],"const REALTIME_BASE_URL = \"https://api.openai.com/v1/realtime\";\nconst OPENAI_API_KEY = Deno.env.get(\"OPENAI_API_KEY\");\nif (!OPENAI_API_KEY) {\n throw new Error(\"🔴 OpenAI API key not configured\");\n}\n\n// Builds the URL for a Realtime API endpoint.\nexport function makeUrl(callId?: string, action?: string) {\n let url = REALTIME_BASE_URL;\n if (!callId) {\n // start call (POST)\n url += \"/calls\";\n } else if (action) {\n // accept, reject, hangup (POST)\n url += `/calls/${callId}/${action}`;\n } else {\n // observer (web socket)\n url += `?call_id=${callId}`;\n }\n return url;\n}\n\n// Builds the headers for a Realtime API endpoint.\nexport function makeHeaders(contentType?: string) {\n const obj: Record = {\n Authorization: `Bearer ${OPENAI_API_KEY}`,\n };\n if (contentType) obj[\"Content-Type\"] = contentType;\n return obj;\n}\n\n// Debug helper for printing Realtime API errors.\nexport async function getErrorText(resp: Response) {\n const errBody = await resp.text().catch(() => \"\");\n return `${resp.status} ${resp.statusText}: ${errBody}`;\n}",[],[182,221],[182],{"_102":229,"_95":230,"_155":231,"_157":-5,"_158":136,"_159":135,"_160":161,"_104":232,"_99":32,"_163":175,"_165":233,"_166":22,"_167":-5,"_168":234,"_98":235},"26f74ad6-a9c0-11f0-baae-0224a6c84d84","README.md","0199e7c8-cadd-7359-9ff3-5c1ae0620560",["D",1760530320030],"# hello-realtime\n\n**Hello Realtime** is a OpenAI Realtime app that supports both WebRTC and SIP\n(telephone) users. You can access the app via WebRTC at\n[hello-realtime.val.run](https://hello-realtime.val.run), or via SIP by calling\n425-800-0042.\n\nThis demo shows off the new SIP API, the new all-in-one WebRTC API, and the new\nserver-side websocket interface.\n\nIf you remix the app, you'll just need to pop in your own `OPENAI_API_KEY` (from\n[platform.openai.com](https://platform.openai.com)), and if you want SIP, the\n`OPENAI_SIGNING_SECRET`.\n\n## Architecture\n\n1. **WebRTC Flow**:\n - Browser connects to frontend\n - creates WebRTC offer\n - `/rtc` endpoint handles SDP negotiation with OpenAI\n - observer established to monitor session\n2. **SIP Flow**:\n - Phone calls triggers webhook\n - `/sip` endpoint verifies webhook and accepts call\n - observer established to monitor session\n\n## API Endpoints\n\n- `GET /` - serves the WebRTC-based app\n- `POST /rtc` - creates a new WebRTC-based Realtime API session\n - Supports optional `model` URL parameter to override the default model\n - Example: `POST /rtc?model=gpt-4o-realtime-preview`\n- `POST /sip` - handles an incoming Realtime API SIP call\n- `POST /observer` - internal endpoint to establish a Realtime API websocket for\n session control\n\n## Project Structure\n\n```\n├── frontend/ \n│ └── index.html # HTML/JS application for WebRTC\n├── main.tsx # Main entrypoint for the val.town app\n└── routes/\n |\n ├── agent.ts # Realtime API session configuration and tools\n ├── observer.ts # Server-side session control for SIP & WebRTC\n ├── rtc.ts # WebRTC session setup\n ├── sip.ts # SIP webhook handling and session setup\n └── utils.ts # Various HTTP helpers\n```\n\n## File Links\n\n- [`frontend/index.html`](./frontend/index.html)\n- [`main.tsx`](./main.tsx)\n- [`routes/agent.ts`](./routes/agent.ts)\n- [`routes/observer.ts`](./routes/observer.ts)\n- [`routes/rtc.ts`](./routes/rtc.ts)\n- [`routes/sip.ts`](./routes/sip.ts)\n- [`routes/utils.ts`](./routes/utils.ts)",[],[230],{"_102":237,"_95":238,"_155":239,"_157":-5,"_158":136,"_159":135,"_160":161,"_104":240,"_99":32,"_163":241,"_165":242,"_166":22,"_167":-5,"_168":243,"_98":244},"26f74cf2-a9c0-11f0-baae-0224a6c84d84","main.tsx","0199e7c8-cadd-7359-9ff3-61633df2c4da",["D",1760530320030],"http","import { Hono } from \"npm:hono\";\nimport { blob } from \"https://esm.town/v/std/blob\";\nimport { parseVal, serveFile } from \"https://esm.town/v/std/utils/index.ts\";\n// import mcp from \"./routes/mcp.ts\";\nimport rtc from \"./routes/rtc.ts\";\nimport sip from \"./routes/sip.ts\";\nimport observer from \"./routes/observer.ts\";\n\nconst SOURCE_URL = parseVal(Deno.env.get(\"VALTOWN_ENTRYPOINT\")).links.self.val;\n\nconst app = new Hono();\napp.route(\"/rtc\", rtc);\napp.route(\"/sip\", sip);\napp.route(\"/observer\", observer);\n// app.route(\"/mcp\", mcp);\napp.get(\"/source\", (c) => c.redirect(SOURCE_URL));\n\napp.get(\"/\", () => serveFile(\"/frontend/index.html\", import.meta.url));\napp.get(\"/favicon.ico\", async (c) => {\n const entry = parseVal(Deno.env.get(\"VALTOWN_ENTRYPOINT\"));\n const file = await blob.get(`${entry.name}/favicon.ico`);\n if (!file) {\n return c.text(\"favicon not found\", 404);\n }\n return new Response(file.body, {\n headers: {\n \"Content-Type\": \"image/x-icon\",\n \"Cache-Control\": \"public, max-age=31536000, immutable\",\n },\n });\n}); \n \nexport default app.fetch;",[],[238],"files",[152,170,180,186,195,203,211,219,228,236],"counts",{"_249":32,"_250":135,"_251":32,"_252":253},"pulls","branches","forks","envVars",{"_254":255,"_256":255},"count",2,"emptyCount","contents",[259,262,265,268],{"_102":153,"_95":154,"_155":156,"_157":-5,"_158":136,"_159":135,"_160":161,"_104":260,"_99":32,"_163":164,"_165":-5,"_166":22,"_167":-5,"_98":261},["D",1760530320030],[154],{"_102":181,"_95":182,"_155":183,"_157":-5,"_158":136,"_159":135,"_160":161,"_104":263,"_99":32,"_163":164,"_165":-5,"_166":22,"_167":-5,"_98":264},["D",1760530320030],[182],{"_102":229,"_95":230,"_155":231,"_157":-5,"_158":136,"_159":135,"_160":161,"_104":266,"_99":32,"_163":175,"_165":233,"_166":22,"_167":-5,"_98":267},["D",1760530320030],[230],{"_102":237,"_95":238,"_155":239,"_157":-5,"_158":136,"_159":135,"_160":161,"_104":269,"_99":32,"_163":241,"_165":242,"_166":22,"_167":-5,"_98":270},["D",1760530320030],[238],"upstreamProject",{"_102":144,"_95":273,"_110":274,"_111":-5,"_108":109,"_23":275},"hello-realtime","Sample app for the OpenAI Realtime API",{"_93":276,"_128":277},"jubertioai","https://imagedelivery.net/iHX6Ovru0O7AjmyT5yZRoA/61901958-12bd-49a3-43e9-2f67f1617200/square512","upstreamBranch",{"_102":139,"_104":280,"_281":282,"_95":43,"_137":144,"_99":283,"_138":284,"_140":285,"_286":287,"_106":-5,"_149":22,"_108":109,"_148":276,"_16":146,"_147":273},["D",1755188493466],"updatedAt",["D",1760849643067],372,"e004ac78-4230-11f0-834a-76b3cceeab13",47,"lockfileKey","1760849654205-esm.town_v_jubertioai_hello-realtime@372-main","emptyEnvVars","isNew","flags",[],"routes/_app.x.$handle.$name.environment-variables",{"_93":94,"_95":96,"_100":294,"_252":299},{"_102":103,"_95":96,"_104":295,"_106":-5,"_107":22,"_108":109,"_110":-5,"_111":-5,"_14":112,"_113":-5,"_114":22,"_115":-5,"_116":32,"_16":117,"_118":119,"_120":119,"_121":122,"_123":122,"_124":122,"_125":119,"_126":119,"_23":296,"_130":297,"_133":298,"_149":22},["D",1760530320030],{"_93":94,"_128":129},{"_93":94,"_132":129},{"_99":135,"_95":43,"_102":136,"_137":103,"_138":139,"_140":141,"_142":109,"_143":144,"_145":146,"_147":96,"_148":94},[300,305],{"_301":302,"_104":303,"_281":-5,"_110":72,"_304":161},"key","OPENAI_API_KEY",["D",1760530320030],"isEmpty",{"_301":306,"_104":307,"_281":-5,"_110":72,"_304":161},"OPENAI_SIGNING_SECRET",["D",1760530320030],"actionData","errors"]

Realtime Agent

Key	Description
OPENAI_API_KEY
OPENAI_SIGNING_SECRET

steepdecline

hello-realtime2

Environment variables