@jambonz/sdk 0.3.0 → 0.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/AGENTS.md +721 -0
  2. package/examples/agent/ws-app.ts +138 -0
  3. package/examples/assemblyai-autogenerate-prompt/app.js +92 -0
  4. package/examples/assemblyai-autogenerate-prompt/package.json +14 -0
  5. package/examples/bedrock-agent.ts +267 -0
  6. package/examples/call-recording/README.md +24 -0
  7. package/examples/call-recording/app.ts +70 -0
  8. package/examples/call-recording/ws-app.ts +47 -0
  9. package/examples/deepgram-voice-agent/ws-app.ts +118 -0
  10. package/examples/dial/app.ts +22 -0
  11. package/examples/echo/app.ts +65 -0
  12. package/examples/echo/ws-app.ts +67 -0
  13. package/examples/elevenlabs-voice-agent/ws-app.ts +81 -0
  14. package/examples/hello-world/README.md +15 -0
  15. package/examples/hello-world/app.js +20 -0
  16. package/examples/hello-world/app.ts +19 -0
  17. package/examples/hello-world/ws-app.ts +18 -0
  18. package/examples/ivr-menu/README.md +15 -0
  19. package/examples/ivr-menu/app.js +85 -0
  20. package/examples/ivr-menu/app.ts +70 -0
  21. package/examples/listen-record/app.ts +22 -0
  22. package/examples/llm-streaming/ws-app.ts +96 -0
  23. package/examples/openai-realtime/ws-app.ts +131 -0
  24. package/examples/queue-with-hold/README.md +19 -0
  25. package/examples/queue-with-hold/app.ts +68 -0
  26. package/examples/queue-with-hold/ws-app.ts +41 -0
  27. package/examples/realtime-translator/src/app.ts +21 -0
  28. package/examples/realtime-translator/src/routes/translator.ts +108 -0
  29. package/examples/realtime-translator/src/utils/config.ts +21 -0
  30. package/examples/realtime-translator/src/utils/translate.ts +23 -0
  31. package/examples/retell-hosted/src/app.ts +22 -0
  32. package/examples/retell-hosted/src/config.ts +53 -0
  33. package/examples/retell-hosted/src/retell.ts +166 -0
  34. package/examples/two-stage-dialer/app.ts +96 -0
  35. package/examples/ultravox-voice-agent/ws-app.ts +116 -0
  36. package/examples/voice-agent/README.md +19 -0
  37. package/examples/voice-agent/app.js +133 -0
  38. package/examples/voice-agent/app.ts +132 -0
  39. package/examples/voice-agent/ws-app.ts +137 -0
  40. package/package.json +9 -4
@@ -0,0 +1,166 @@
1
+ /**
2
+ * Retell route handler — bridges calls between PSTN and Retell AI.
3
+ *
4
+ * Two call directions:
5
+ * 1. PSTN → Retell: inbound call from a phone number is forwarded to
6
+ * the Retell trunk so the AI agent handles it.
7
+ * 2. Retell → PSTN: Retell initiates an outbound call, jambonz dials
8
+ * the destination number via the PSTN trunk.
9
+ *
10
+ * SIP REFER (cold transfer) from Retell is supported in two modes:
11
+ * - PASS_REFER=true: REFER is forwarded to the originating carrier
12
+ * - PASS_REFER=false: jambonz places a new outbound dial to the transfer target
13
+ */
14
+ import type { Session } from '@jambonz/sdk/websocket';
15
+ import { getE164 } from './config.js';
16
+
17
+ /** Track sessions by call_sid for adulting (refer-complete) scenario. */
18
+ const sessions = new Map<string, Session>();
19
+
20
+ export default function retell(session: Session) {
21
+ const log = (msg: string) => console.log(`[${session.callSid}] ${msg}`);
22
+ const { data } = session;
23
+ const env = (data.env_vars ?? {}) as Record<string, string>;
24
+ const sipHeaders = data.sip?.headers ?? {};
25
+
26
+ sessions.set(session.callSid, session);
27
+
28
+ let { from, to } = data;
29
+
30
+ // Determine if call is coming from Retell (trunk match)
31
+ const outboundFromRetell =
32
+ data.direction === 'inbound' &&
33
+ env.RETELL_TRUNK_NAME &&
34
+ data.originating_sip_trunk_name === env.RETELL_TRUNK_NAME;
35
+
36
+ if (outboundFromRetell) {
37
+ log(`call from Retell trunk "${data.originating_sip_trunk_name}"`);
38
+ } else {
39
+ log(`call from PSTN trunk "${data.originating_sip_trunk_name}"`);
40
+ }
41
+
42
+ // ---- Event handlers ----
43
+
44
+ session.on('/refer', (evt: Record<string, any>) => {
45
+ const { refer_details } = evt;
46
+ log(`received REFER → ${refer_details?.refer_to_user}`);
47
+
48
+ const passRefer = env.PASS_REFER !== undefined ? env.PASS_REFER !== 'false' : true;
49
+
50
+ if (passRefer) {
51
+ session
52
+ .sipRefer({
53
+ referTo: refer_details.refer_to_user,
54
+ referredBy: evt.to,
55
+ actionHook: '/referComplete',
56
+ })
57
+ .reply();
58
+ log('REFER passed to originator');
59
+ } else {
60
+ const target = [{
61
+ type: 'phone' as const,
62
+ number: refer_details.x_override_number || refer_details.refer_to_user,
63
+ trunk: refer_details.x_override_carrier || env.PSTN_TRUNK_NAME,
64
+ }];
65
+ session
66
+ .say({ text: 'Connecting you' })
67
+ .dial({
68
+ callerId: evt.to,
69
+ anchorMedia: true,
70
+ actionHook: '/dialAction',
71
+ target,
72
+ })
73
+ .hangup()
74
+ .reply();
75
+ log('new outbound dial for transfer');
76
+ }
77
+ });
78
+
79
+ session.on('/dialAction', (evt: Record<string, any>) => {
80
+ if (evt.dial_call_status !== 'completed') {
81
+ log(`dial failed: ${evt.dial_call_status} (SIP ${evt.dial_sip_status})`);
82
+ session
83
+ .sipDecline({ status: evt.dial_sip_status })
84
+ .reply();
85
+ } else {
86
+ log('dial completed');
87
+ session.reply();
88
+ }
89
+ });
90
+
91
+ session.on('/referComplete', () => {
92
+ log('refer complete');
93
+ session.reply();
94
+ const parentCallSid = data.parent_call_sid;
95
+ if (parentCallSid) {
96
+ const parentSession = sessions.get(parentCallSid);
97
+ if (parentSession) {
98
+ log(`hanging up parent session ${parentCallSid}`);
99
+ parentSession.hangup().send();
100
+ }
101
+ }
102
+ });
103
+
104
+ session.on('close', (code: number) => {
105
+ sessions.delete(session.callSid);
106
+ log(`closed (${code})`);
107
+ });
108
+
109
+ session.on('error', (err: Error) => console.error(`[${session.callSid}] error:`, err));
110
+
111
+ // ---- Build dial target ----
112
+
113
+ try {
114
+ let target: Array<{ type: 'phone'; number: string; trunk: string }>;
115
+ let headers: Record<string, string> = {};
116
+
117
+ if (outboundFromRetell) {
118
+ // Forward X-* headers from Retell to the PSTN leg
119
+ headers = Object.fromEntries(
120
+ Object.entries(sipHeaders).filter(([key]) => key.startsWith('X-'))
121
+ ) as Record<string, string>;
122
+
123
+ target = [{
124
+ type: 'phone',
125
+ number: sipHeaders['X-Override-Number'] || to,
126
+ trunk: sipHeaders['X-Override-Carrier'] || env.PSTN_TRUNK_NAME,
127
+ }];
128
+
129
+ // Caller ID overrides
130
+ if (sipHeaders['X-Original-CLID']) {
131
+ from = sipHeaders['X-Original-CLID'];
132
+ } else if (env.OVERRIDE_FROM_USER) {
133
+ from = env.OVERRIDE_FROM_USER;
134
+ }
135
+ } else {
136
+ // PSTN inbound (or API-originated outbound) → dial Retell
137
+ const pstnInbound = data.direction === 'inbound';
138
+ const dest = env.DEFAULT_COUNTRY ? getE164(to, env.DEFAULT_COUNTRY) : to;
139
+
140
+ target = [{
141
+ type: 'phone',
142
+ number: pstnInbound ? dest : from,
143
+ trunk: env.RETELL_TRUNK_NAME,
144
+ }];
145
+ from = pstnInbound ? from : dest;
146
+ }
147
+
148
+ session
149
+ .dial({
150
+ callerId: from,
151
+ answerOnBridge: true,
152
+ anchorMedia: true,
153
+ referHook: '/refer',
154
+ actionHook: '/dialAction',
155
+ target,
156
+ headers,
157
+ })
158
+ .hangup()
159
+ .send();
160
+
161
+ log(`dialling ${target[0].number} via ${target[0].trunk}`);
162
+ } catch (err) {
163
+ console.error(`[${session.callSid}] error setting up call:`, err);
164
+ session.close();
165
+ }
166
+ }
@@ -0,0 +1,96 @@
1
+ /**
2
+ * Staged dialer — prompts the caller to enter a phone number via DTMF,
3
+ * dials it, and plays a whisper warning before the call time limit expires.
4
+ *
5
+ * Flow:
6
+ * 1. Answer and gather DTMF digits (phone number with country code, # to finish)
7
+ * 2. Dial the entered number with a 20-second time limit
8
+ * 3. At 10 seconds, whisper to the caller that the call ends in 10 seconds
9
+ * 4. At 20 seconds the dial verb auto-disconnects
10
+ */
11
+ import http from 'http';
12
+ import { createEndpoint } from '@jambonz/sdk/websocket';
13
+
14
+ const port = Number(process.env.PORT) || 3000;
15
+ const server = http.createServer();
16
+ const makeService = createEndpoint({ server, port });
17
+
18
+ const svc = makeService({ path: '/' });
19
+
20
+ svc.on('session:new', (session) => {
21
+ const log = (msg: string) => console.log(`[${session.callSid}] ${msg}`);
22
+ log('new call');
23
+
24
+ let whisperTimer: ReturnType<typeof setTimeout> | null = null;
25
+
26
+ // Gather result — caller entered a phone number
27
+ session.on('/gather', (evt: Record<string, any>) => {
28
+ const digits = evt.digits as string | undefined;
29
+
30
+ if (!digits) {
31
+ log('no digits entered, reprompting');
32
+ session
33
+ .gather({
34
+ actionHook: '/gather',
35
+ input: ['digits'],
36
+ finishOnKey: '#',
37
+ timeout: 15,
38
+ say: { text: 'Sorry, I didn\'t get that. Please enter the phone number followed by the pound key.' },
39
+ })
40
+ .hangup()
41
+ .reply();
42
+ return;
43
+ }
44
+
45
+ const number = digits.startsWith('+') ? digits : `+${digits}`;
46
+ log(`dialing ${number}`);
47
+
48
+ // Start a timer to whisper 10 seconds into the call
49
+ whisperTimer = setTimeout(() => {
50
+ log('whispering time warning');
51
+ session.injectWhisper({ verb: 'say', text: 'Your call will end in 10 seconds.' });
52
+ }, 10_000);
53
+
54
+ session
55
+ .dial({
56
+ target: [{ type: 'phone', number }],
57
+ answerOnBridge: true,
58
+ timeout: 30,
59
+ timeLimit: 20,
60
+ actionHook: '/dial-complete',
61
+ })
62
+ .hangup()
63
+ .reply();
64
+ });
65
+
66
+ // Dial complete — call ended (time limit, hangup, or no answer)
67
+ session.on('/dial-complete', (evt: Record<string, any>) => {
68
+ if (whisperTimer) clearTimeout(whisperTimer);
69
+ log(`dial ended: ${evt.dial_call_status || 'unknown'}`);
70
+ session
71
+ .say({ text: 'Your call has ended. Goodbye.' })
72
+ .hangup()
73
+ .reply();
74
+ });
75
+
76
+ session.on('close', (code: number) => {
77
+ if (whisperTimer) clearTimeout(whisperTimer);
78
+ log(`closed (${code})`);
79
+ });
80
+ session.on('error', (err: Error) => console.error(`[${session.callSid}] error:`, err));
81
+
82
+ // Initial verb sequence — answer and gather digits
83
+ session
84
+ .answer()
85
+ .gather({
86
+ actionHook: '/gather',
87
+ input: ['digits'],
88
+ finishOnKey: '#',
89
+ timeout: 15,
90
+ say: { text: 'Please enter the phone number starting with country code, followed by the pound key.' },
91
+ })
92
+ .hangup()
93
+ .send();
94
+ });
95
+
96
+ console.log(`Staged dialer listening on port ${port}`);
@@ -0,0 +1,116 @@
1
+ import http from 'http';
2
+ import { createEndpoint } from '@jambonz/sdk/websocket';
3
+
4
+ const server = http.createServer();
5
+ const makeService = createEndpoint({
6
+ server,
7
+ port: 3000,
8
+ envVars: {
9
+ ULTRAVOX_API_KEY: {
10
+ type: 'string',
11
+ description: 'Ultravox API key',
12
+ required: true,
13
+ obscure: true,
14
+ },
15
+ },
16
+ });
17
+
18
+ const svc = makeService({ path: '/ultravox-s2s' });
19
+
20
+ svc.on('session:new', (session) => {
21
+ console.log(`Incoming call: ${session.callSid}`);
22
+ console.log(' from: %s to: %s', session.data.from, session.data.to);
23
+ console.log(' env_vars:', JSON.stringify(session.data.env_vars || {}));
24
+
25
+ const apiKey = session.data.env_vars?.ULTRAVOX_API_KEY;
26
+ if (!apiKey) {
27
+ console.error('ERROR: ULTRAVOX_API_KEY not found in application environment variables');
28
+ return;
29
+ }
30
+
31
+ session
32
+ .on('/event', (_evt: Record<string, any>) => {
33
+ // Ultravox events (state changes, transcripts, etc.)
34
+ })
35
+ .on('/toolCall', async (evt: Record<string, any>) => {
36
+ const { name, args, tool_call_id } = evt;
37
+
38
+ if (name === 'get_weather') {
39
+ try {
40
+ const scale = (args.scale || 'celsius').toLowerCase().startsWith('f') ? 'fahrenheit' : 'celsius';
41
+
42
+ const geoRes = await fetch(
43
+ `https://geocoding-api.open-meteo.com/v1/search?name=${encodeURIComponent(args.location)}&count=1&language=en&format=json`
44
+ );
45
+ const geoData = await geoRes.json() as any;
46
+ if (!geoData.results?.length) throw new Error('location_not_found');
47
+
48
+ const { latitude: lat, longitude: lng } = geoData.results[0];
49
+ const wxRes = await fetch(
50
+ `https://api.open-meteo.com/v1/forecast?latitude=${lat}&longitude=${lng}&current=temperature_2m,wind_speed_10m&temperature_unit=${scale}`
51
+ );
52
+ const weather = await wxRes.json();
53
+
54
+ session.sendToolOutput(tool_call_id, {
55
+ type: 'client_tool_result',
56
+ invocation_id: tool_call_id,
57
+ result: JSON.stringify(weather),
58
+ });
59
+ } catch (err) {
60
+ session.sendToolOutput(tool_call_id, {
61
+ type: 'client_tool_result',
62
+ invocation_id: tool_call_id,
63
+ result: JSON.stringify({ error: String(err) }),
64
+ });
65
+ }
66
+ }
67
+ })
68
+ .on('/final', (evt: Record<string, any>) => {
69
+ if (['server error', 'connection failure'].includes(evt.completion_reason)) {
70
+ session.say({ text: 'Sorry, there was an error processing your request.' }).hangup();
71
+ }
72
+ session.reply();
73
+ })
74
+ .on('close', (code: number) => {
75
+ console.log(`Session ${session.callSid} closed: ${code}`);
76
+ })
77
+ .on('error', (err: Error) => {
78
+ console.error(`Session ${session.callSid} error:`, err);
79
+ });
80
+
81
+ session
82
+ .answer()
83
+ .pause({ length: 1 })
84
+ .ultravox_s2s({
85
+ auth: { apiKey },
86
+ actionHook: '/final',
87
+ eventHook: '/event',
88
+ toolHook: '/toolCall',
89
+ events: ['all'],
90
+ llmOptions: {
91
+ systemPrompt: `You are a helpful weather assistant.
92
+ You can look up current weather for any location using the get_weather tool.
93
+ When asked about weather, always use the tool to fetch real data — do not guess or make up temperatures.
94
+ After receiving tool results, report the temperature and wind speed to the user.
95
+ Give concise, friendly responses in plain text.`,
96
+ selectedTools: [
97
+ {
98
+ temporaryTool: {
99
+ modelToolName: 'get_weather',
100
+ description: 'Get the weather at a given location',
101
+ dynamicParameters: [
102
+ { name: 'location', location: 'PARAMETER_LOCATION_BODY', required: true },
103
+ { name: 'scale', location: 'PARAMETER_LOCATION_BODY', required: true,
104
+ schema: { type: 'string', enum: ['fahrenheit', 'celsius'], description: 'Temperature unit' } },
105
+ ],
106
+ client: {},
107
+ },
108
+ },
109
+ ],
110
+ },
111
+ })
112
+ .hangup()
113
+ .send();
114
+ });
115
+
116
+ console.log('Ultravox voice agent listening on port 3000');
@@ -0,0 +1,19 @@
1
+ # LLM Voice Agent
2
+
3
+ A conversational AI voice agent powered by an LLM. The caller speaks naturally and the AI responds in real time.
4
+
5
+ ## What It Demonstrates
6
+ - The `config` verb to set session-level TTS and STT defaults
7
+ - The `llm` verb for real-time voice AI conversation
8
+ - Tool/function calling with `toolHook`
9
+ - Using filler noise while the LLM is processing
10
+ - Handling the end of the LLM conversation
11
+
12
+ ## Prerequisites
13
+ - An OpenAI API key (or substitute your preferred LLM vendor)
14
+ - Deepgram and ElevenLabs credentials configured in jambonz (or substitute your preferred STT/TTS vendors)
15
+
16
+ ## Files
17
+ - `app.js` — Webhook version (Plain JavaScript with Express)
18
+ - `app.ts` — Webhook version (TypeScript using `@jambonz/sdk`)
19
+ - `ws-app.ts` — WebSocket version (TypeScript using `@jambonz/sdk`)
@@ -0,0 +1,133 @@
1
+ const express = require('express');
2
+ const app = express();
3
+ app.use(express.json());
4
+
5
+ const SYSTEM_PROMPT = `You are a helpful customer service agent for Acme Corp.
6
+ You help customers with order inquiries, returns, and general questions.
7
+ Be concise and friendly. Keep responses under 2-3 sentences when possible.
8
+ If you need to look up an order, use the lookupOrder function.
9
+ If the customer wants to speak to a human, use the transferToAgent function.`;
10
+
11
+ // Initial call handler
12
+ app.post('/incoming', (req, res) => {
13
+ res.json([
14
+ {
15
+ verb: 'config',
16
+ synthesizer: {
17
+ vendor: 'elevenlabs',
18
+ voice: 'Rachel',
19
+ language: 'en-US'
20
+ },
21
+ recognizer: {
22
+ vendor: 'deepgram',
23
+ language: 'en-US',
24
+ deepgramOptions: { model: 'nova-2', smartFormatting: true }
25
+ },
26
+ fillerNoise: {
27
+ enable: true,
28
+ url: 'https://example.com/sounds/typing.wav',
29
+ startDelaySecs: 2
30
+ }
31
+ },
32
+ {
33
+ verb: 'openai_s2s',
34
+ model: 'gpt-4o',
35
+ auth: { apiKey: process.env.OPENAI_API_KEY },
36
+ llmOptions: {
37
+ messages: [
38
+ { role: 'system', content: SYSTEM_PROMPT }
39
+ ],
40
+ temperature: 0.7,
41
+ tools: [
42
+ {
43
+ type: 'function',
44
+ function: {
45
+ name: 'lookupOrder',
46
+ description: 'Look up an order by order number to get status, tracking, and details',
47
+ parameters: {
48
+ type: 'object',
49
+ properties: {
50
+ orderNumber: { type: 'string', description: 'The order number (e.g. ORD-12345)' }
51
+ },
52
+ required: ['orderNumber']
53
+ }
54
+ }
55
+ },
56
+ {
57
+ type: 'function',
58
+ function: {
59
+ name: 'transferToAgent',
60
+ description: 'Transfer the call to a human agent',
61
+ parameters: {
62
+ type: 'object',
63
+ properties: {
64
+ reason: { type: 'string', description: 'Why the caller wants a human agent' }
65
+ },
66
+ required: ['reason']
67
+ }
68
+ }
69
+ }
70
+ ]
71
+ },
72
+ actionHook: '/llm-complete',
73
+ toolHook: '/tool-call'
74
+ }
75
+ ]);
76
+ });
77
+
78
+ // Handle tool/function calls from the LLM
79
+ app.post('/tool-call', (req, res) => {
80
+ const { name, args } = req.body.tool;
81
+
82
+ switch (name) {
83
+ case 'lookupOrder': {
84
+ // In production, query your order database here
85
+ const order = {
86
+ orderNumber: args.orderNumber,
87
+ status: 'shipped',
88
+ trackingNumber: 'TRK-98765',
89
+ estimatedDelivery: '2026-02-20'
90
+ };
91
+ res.json({ result: JSON.stringify(order) });
92
+ break;
93
+ }
94
+
95
+ case 'transferToAgent': {
96
+ // Return verbs to transfer the call
97
+ res.json({
98
+ result: 'Transferring to agent',
99
+ verbs: [
100
+ { verb: 'say', text: 'Let me connect you to a human agent. Please hold.' },
101
+ {
102
+ verb: 'dial',
103
+ target: [{ type: 'user', name: 'support-queue' }],
104
+ answerOnBridge: true,
105
+ timeout: 60,
106
+ actionHook: '/dial-result'
107
+ },
108
+ { verb: 'say', text: 'Sorry, no agents are available. Please try again later.' },
109
+ { verb: 'hangup' }
110
+ ]
111
+ });
112
+ break;
113
+ }
114
+
115
+ default:
116
+ res.json({ result: 'Unknown tool' });
117
+ }
118
+ });
119
+
120
+ // Handle LLM conversation end
121
+ app.post('/llm-complete', (req, res) => {
122
+ console.log('LLM conversation ended:', req.body.reason);
123
+ res.json([
124
+ { verb: 'say', text: 'Thank you for calling Acme Corp. Goodbye!' },
125
+ { verb: 'hangup' }
126
+ ]);
127
+ });
128
+
129
+ app.post('/dial-result', (req, res) => {
130
+ res.json([{ verb: 'hangup' }]);
131
+ });
132
+
133
+ app.listen(3000, () => console.log('Voice agent listening on port 3000'));
@@ -0,0 +1,132 @@
1
+ import express from 'express';
2
+ import { WebhookResponse } from '@jambonz/sdk/webhook';
3
+
4
+ const app = express();
5
+ app.use(express.json());
6
+
7
+ const SYSTEM_PROMPT = `You are a helpful customer service agent for Acme Corp.
8
+ You help customers with order inquiries, returns, and general questions.
9
+ Be concise and friendly. Keep responses under 2-3 sentences when possible.
10
+ If you need to look up an order, use the lookupOrder function.
11
+ If the customer wants to speak to a human, use the transferToAgent function.`;
12
+
13
+ // Initial call handler
14
+ app.post('/incoming', (_req, res) => {
15
+ const jambonz = new WebhookResponse();
16
+ jambonz
17
+ .config({
18
+ synthesizer: {
19
+ vendor: 'elevenlabs',
20
+ voice: 'Rachel',
21
+ language: 'en-US',
22
+ },
23
+ recognizer: {
24
+ vendor: 'deepgram',
25
+ language: 'en-US',
26
+ deepgramOptions: { model: 'nova-2', smartFormatting: true },
27
+ },
28
+ fillerNoise: {
29
+ enable: true,
30
+ url: 'https://example.com/sounds/typing.wav',
31
+ startDelaySecs: 2,
32
+ },
33
+ })
34
+ .openai_s2s({
35
+ model: 'gpt-4o',
36
+ auth: { apiKey: process.env.OPENAI_API_KEY! },
37
+ llmOptions: {
38
+ messages: [{ role: 'system', content: SYSTEM_PROMPT }],
39
+ temperature: 0.7,
40
+ tools: [
41
+ {
42
+ type: 'function',
43
+ function: {
44
+ name: 'lookupOrder',
45
+ description: 'Look up an order by order number to get status, tracking, and details',
46
+ parameters: {
47
+ type: 'object',
48
+ properties: {
49
+ orderNumber: { type: 'string', description: 'The order number (e.g. ORD-12345)' },
50
+ },
51
+ required: ['orderNumber'],
52
+ },
53
+ },
54
+ },
55
+ {
56
+ type: 'function',
57
+ function: {
58
+ name: 'transferToAgent',
59
+ description: 'Transfer the call to a human agent',
60
+ parameters: {
61
+ type: 'object',
62
+ properties: {
63
+ reason: { type: 'string', description: 'Why the caller wants a human agent' },
64
+ },
65
+ required: ['reason'],
66
+ },
67
+ },
68
+ },
69
+ ],
70
+ },
71
+ actionHook: '/llm-complete',
72
+ toolHook: '/tool-call',
73
+ });
74
+
75
+ res.json(jambonz);
76
+ });
77
+
78
+ // Handle tool/function calls from the LLM
79
+ app.post('/tool-call', (req, res) => {
80
+ const { name, args } = req.body.tool;
81
+
82
+ switch (name) {
83
+ case 'lookupOrder': {
84
+ // In production, query your order database here
85
+ const order = {
86
+ orderNumber: args.orderNumber,
87
+ status: 'shipped',
88
+ trackingNumber: 'TRK-98765',
89
+ estimatedDelivery: '2026-02-20',
90
+ };
91
+ res.json({ result: JSON.stringify(order) });
92
+ break;
93
+ }
94
+
95
+ case 'transferToAgent': {
96
+ const jambonz = new WebhookResponse();
97
+ jambonz
98
+ .say({ text: 'Let me connect you to a human agent. Please hold.' })
99
+ .dial({
100
+ target: [{ type: 'user', name: 'support-queue' }],
101
+ answerOnBridge: true,
102
+ timeout: 60,
103
+ actionHook: '/dial-result',
104
+ })
105
+ .say({ text: 'Sorry, no agents are available. Please try again later.' })
106
+ .hangup();
107
+ res.json({ result: 'Transferring to agent', verbs: jambonz.toJSON() });
108
+ break;
109
+ }
110
+
111
+ default:
112
+ res.json({ result: 'Unknown tool' });
113
+ }
114
+ });
115
+
116
+ // Handle LLM conversation end
117
+ app.post('/llm-complete', (req, res) => {
118
+ console.log('LLM conversation ended:', req.body.reason);
119
+ const jambonz = new WebhookResponse();
120
+ jambonz
121
+ .say({ text: 'Thank you for calling Acme Corp. Goodbye!' })
122
+ .hangup();
123
+ res.json(jambonz);
124
+ });
125
+
126
+ app.post('/dial-result', (_req, res) => {
127
+ const jambonz = new WebhookResponse();
128
+ jambonz.hangup();
129
+ res.json(jambonz);
130
+ });
131
+
132
+ app.listen(3000, () => console.log('Voice agent listening on port 3000'));