OpenAI

Example: Placing an outbound call

View as Markdown

For the complete documentation index, see llms.txt.

This example starts a VoxEngine session, places an outbound PSTN call, and bridges audio to OpenAI Realtime once the callee answers.

Jump to the Full VoxEngine scenario.

Prerequisites

  • Store your OpenAI API key in Voximplant ApplicationStorage under OPENAI_API_KEY.
  • Ensure outbound calling is enabled for your Voximplant application and that your caller ID is verified.

Outbound call parameters

The example expects destination and caller ID in customData (read via VoxEngine.customData()):

Custom data example
1{"destination":"+15551234567","callerId":"+15557654321"}

Launch the routing rule

For quick testing, you can start this outbound scenario from the Voximplant Control Panel:

  1. Open your Voximplant application and go to the Routing tab.
  2. Select the routing rule that has this scenario attached.
  3. Click Run.
  4. Provide Custom data (max 200 bytes) with destination and callerId:
Custom data example
1{"destination":"+15551234567","callerId":"+15557654321"}

For production, start the routing rule via Management API startScenarios (pass rule_id, and pass the same JSON string in script_custom_data): https://voximplant.com/docs/references/httpapi/scenarios#startscenarios

Alternate outbound destinations

This example uses VoxEngine.callPSTN(...) for PSTN dialing. You can also route outbound calls to other destination types in VoxEngine:

  • SIP (VoxEngine.callSIP): dial a SIP URI to reach a PBX, carrier, SIP trunk, or other SIP endpoint.
  • WhatsApp (VoxEngine.callWhatsappUser): place a WhatsApp Business-initiated call (requires a WhatsApp Business account and enabled numbers).
  • Voximplant users (VoxEngine.callUser): calls another app user inside the same Voximplant application such as web SDK, mobile SDK, or SIP user.

Relevant guides:

Connect call audio

After the callee answers, the example bridges audio both ways:

Connect call audio
1VoxEngine.sendMediaBetween(call, voiceAIClient);

Barge-in

Barge-in
1voiceAIClient.addEventListener(OpenAI.RealtimeAPIEvents.InputAudioBufferSpeechStarted, () => {
2  voiceAIClient.clearMediaBuffer();
3});

Notes

See the VoxEngine API Reference for more details.

Full VoxEngine scenario

voxeengine-openai-place-outbound-call.js
1/**
2 * Voximplant + OpenAI Realtime API connector demo
3 * Scenario: place an outbound PSTN call and bridge it to OpenAI Realtime.
4 */
5
6require(Modules.OpenAI);
7require(Modules.ApplicationStorage);
8
9const SYSTEM_PROMPT = `
10You are Voxi, a concise phone assistant for outbound calls.
11Keep responses short and helpful.
12`;
13
14const SESSION_CONFIG = {
15    session: {
16        type: "realtime",
17        instructions: SYSTEM_PROMPT,
18        voice: "alloy",
19        output_modalities: ["audio"],
20        turn_detection: {type: "server_vad", interrupt_response: true},
21    },
22};
23
24const MAX_CALL_MS = 2 * 60 * 1000;
25
26VoxEngine.addEventListener(AppEvents.Started, async () => {
27    let call;
28    let voiceAIClient;
29    let hangupTimer;
30
31    try {
32        // Custom data example: {"destination":"+15551234567","callerId":"+15557654321"}
33        const {destination, callerId} = JSON.parse(VoxEngine.customData());
34
35        call = VoxEngine.callPSTN(destination, callerId);
36        // Alternative outbound paths (uncomment to use):
37        // call = VoxEngine.callUser({username: destination, callerid: callerId});
38        // call = VoxEngine.callSIP(`sip:${destination}@your-sip-domain`, callerId);
39        // call = VoxEngine.callWhatsappUser({number: destination, callerid: callerId});
40
41        call.addEventListener(CallEvents.Failed, () => VoxEngine.terminate());
42        call.addEventListener(CallEvents.Disconnected, () => {
43            if (hangupTimer) clearTimeout(hangupTimer);
44            VoxEngine.terminate();
45        });
46
47        call.addEventListener(CallEvents.Connected, async () => {
48            hangupTimer = setTimeout(() => {
49                Logger.write("===HANGUP_TIMER===");
50                call.hangup();
51            }, MAX_CALL_MS);
52
53            voiceAIClient = await OpenAI.createRealtimeAPIClient({
54                apiKey: (await ApplicationStorage.get("OPENAI_API_KEY")).value,
55                model: "gpt-realtime-1.5",
56                onWebSocketClose: (event) => {
57                    Logger.write("===OpenAI.WebSocket.Close===");
58                    if (event) Logger.write(JSON.stringify(event));
59                    VoxEngine.terminate();
60                },
61            });
62
63            voiceAIClient.addEventListener(OpenAI.RealtimeAPIEvents.SessionCreated, () => {
64                voiceAIClient.sessionUpdate(SESSION_CONFIG);
65            });
66
67            voiceAIClient.addEventListener(OpenAI.RealtimeAPIEvents.SessionUpdated, () => {
68                VoxEngine.sendMediaBetween(call, voiceAIClient);
69                voiceAIClient.responseCreate({instructions: "Hello! This is Voxi. How can I help today?"});
70            });
71
72            voiceAIClient.addEventListener(
73                OpenAI.RealtimeAPIEvents.InputAudioBufferSpeechStarted,
74                () => {
75                    Logger.write("===BARGE-IN: OpenAI.InputAudioBufferSpeechStarted===");
76                    voiceAIClient.clearMediaBuffer();
77                }
78            );
79
80            // Consolidated "log-only" handlers
81            [
82                OpenAI.RealtimeAPIEvents.ResponseCreated,
83                OpenAI.RealtimeAPIEvents.ResponseDone,
84                OpenAI.RealtimeAPIEvents.ResponseOutputAudioDone,
85                OpenAI.RealtimeAPIEvents.ConversationItemInputAudioTranscriptionCompleted,
86                OpenAI.RealtimeAPIEvents.ResponseOutputAudioTranscriptDone,
87                OpenAI.RealtimeAPIEvents.ConnectorInformation,
88                OpenAI.RealtimeAPIEvents.HTTPResponse,
89                OpenAI.RealtimeAPIEvents.WebSocketError,
90                OpenAI.RealtimeAPIEvents.Unknown,
91                OpenAI.Events.WebSocketMediaStarted,
92                OpenAI.Events.WebSocketMediaEnded,
93            ].forEach((eventName) => {
94                voiceAIClient.addEventListener(eventName, (event) => {
95                    Logger.write(`===${event.name}===`);
96                    if (event?.data) Logger.write(JSON.stringify(event.data));
97                });
98            });
99        });
100    } catch (error) {
101        Logger.write("===UNHANDLED_ERROR===");
102        Logger.write(error);
103        voiceAIClient?.close();
104        VoxEngine.terminate();
105    }
106});