> For a complete documentation index, fetch https://docs.voximplant.ai/llms.txt

# Example: OpenAI Realtime on Azure

<blockquote>
  For the complete documentation index, see <a href="/llms.txt">llms.txt</a>.
</blockquote>

## Overview

This example answers an inbound call and bridges call audio to an Azure OpenAI Realtime deployment using `OpenAI.createRealtimeAPIClient()`.

Use this pattern when you have an Azure OpenAI Realtime model deployment and want VoxEngine call control, recording, media bridging, and OpenAI-compatible Realtime session handling in the same scenario.

**⬇️ Jump to the [Full VoxEngine scenario](#full-voxengine-scenario).**

## Prerequisites

* An Azure subscription with access to [Azure OpenAI in Microsoft Foundry Models](https://learn.microsoft.com/en-us/azure/foundry/openai/).
* A Microsoft Foundry or Azure OpenAI resource in a region that supports GPT Realtime models. Check Microsoft's [Realtime audio model and region documentation](https://learn.microsoft.com/en-us/azure/foundry/openai/how-to/realtime-audio#supported-models) before creating the deployment.
* Quota for the selected Realtime model and deployment type. Azure OpenAI quota is region-specific, so confirm the requested model has available quota in the target region. See [Azure OpenAI quotas and limits](https://learn.microsoft.com/en-us/azure/foundry/openai/quotas-limits).
* An Azure OpenAI Realtime model deployment, for example `gpt-realtime-1.5`. The `model` value in this VoxEngine scenario must match the Azure deployment name.
* The Azure OpenAI resource endpoint from Foundry. The current Azure v1 API format uses `/openai/v1` in the endpoint URL. See [Azure OpenAI v1 API](https://learn.microsoft.com/en-us/azure/foundry/openai/api-version-lifecycle).
* Store the Azure OpenAI API key in Voximplant [Secrets](/platform/voxengine/secrets) under `AZURE_API_KEY`.
* Store the Azure OpenAI endpoint in Voximplant [Secrets](/platform/voxengine/secrets) under `AZURE_OPENAI_BASE_URL`.
* Create a Voximplant [routing rule](/platform/voxengine/routing-rules) that points your test destination to this scenario.

## Azure setup checklist

1. Create or select a Microsoft Foundry project with an Azure OpenAI resource.
2. Confirm the target region supports your Realtime model and has quota.
3. Deploy a GPT Realtime model from the Foundry **Build** area. For `gpt-realtime-1.5`, use the deployed model name as the `AZURE_OPENAI_MODEL` value in the scenario.
4. Open the deployment details and copy both the API key and Azure OpenAI endpoint.
5. Add the API key to Voximplant [Secrets](/platform/voxengine/secrets) as `AZURE_API_KEY`.
6. Add the Azure OpenAI endpoint to Voximplant [Secrets](/platform/voxengine/secrets) as `AZURE_OPENAI_BASE_URL`.
7. Keep the `AZURE_OPENAI_MODEL` scenario constant set to the Azure deployment name, not just the model family name unless you used the same value for the deployment name.
8. Test the deployment in the Foundry Audio playground before routing live calls through Voximplant.

Microsoft's Azure OpenAI v1 documentation shows endpoint values like
`https://your-resource.openai.azure.com/openai/v1/`.

VoxEngine accepts the same endpoint with or without the `openai/v1` path.
Both of these are valid for `baseUrl`:

* `https://your-resource.openai.azure.com/openai/v1/`
* `https://your-resource.openai.azure.com/`

## Architecture

```mermaid
graph LR
  Caller[PSTN/SIP/WhatsApp/App users/WebRTC] --> VoxEngine[VoxEngine Scenario]
  VoxEngine -->|WebSocket media bridge| Client[OpenAI Realtime client]
  Client -->|baseUrl plus model deployment| Azure[Azure OpenAI Realtime]
  Azure --> Client
  Client --> VoxEngine
  VoxEngine --> Caller
```

## How it works

* The scenario reads `AZURE_API_KEY` and `AZURE_OPENAI_BASE_URL` from Voximplant Secrets.
* `baseUrl` points the OpenAI Realtime client at the Azure OpenAI resource.
* `model` uses the Azure deployment name.
* `VoxEngine.sendMediaBetween(call, voiceAIClient)` bridges call audio to the Realtime client after the session is updated.
* `responseCreate(...)` after `SessionUpdated` creates the audible greeting for the caller.
* The barge-in handler clears the media buffer when the caller starts speaking.

## Usage highlights

* Create the Realtime client with `OpenAI.createRealtimeAPIClient(...)`.
* Set `baseUrl` from `AZURE_OPENAI_BASE_URL` to route the VoxEngine OpenAI module to Azure instead of OpenAI's default endpoint.
* Set `model` to the Azure deployment name.
* Use `sessionUpdate(...)` to configure Realtime instructions, voice, output modalities, and turn detection.
* Bridge audio with `VoxEngine.sendMediaBetween(call, voiceAIClient)`.
* Handle barge-in with `InputAudioBufferSpeechStarted` and `clearMediaBuffer()`.

## Full VoxEngine scenario

```javascript title={"voxeengine-byollm-azure-openai-rt.js"} maxLines={0}
/**
 * Voximplant + Azure OpenAI Realtime API connector demo
 * Scenario: answer an incoming call and bridge it to Azure OpenAI Realtime.
 */

require(Modules.OpenAI);

const SYSTEM_PROMPT = `
You are Voxi, a helpful voice assistant for Voximplant phone callers.
Keep responses short and telephony-friendly (usually 1-2 sentences).
`;

const SESSION_CONFIG = {
    session: {
        type: "realtime",
        instructions: SYSTEM_PROMPT,
        voice: "alloy",
        output_modalities: ["audio"],
        turn_detection: {type: "server_vad", interrupt_response: true},
    },
};

VoxEngine.addEventListener(AppEvents.CallAlerting, async ({call}) => {
    let voiceAIClient;

    function terminate(){
        voiceAIClient?.close();
        VoxEngine.terminate();
    }

    call.addEventListener(CallEvents.Disconnected, terminate);
    call.addEventListener(CallEvents.Failed, terminate);

    try {
        call.answer();
        // call.record({hd_audio: true, stereo: true}); // Optional: record the call

        voiceAIClient = await OpenAI.createRealtimeAPIClient({
            apiKey: VoxEngine.getSecretValue("AZURE_API_KEY"),          // API key from Azure
            baseUrl: VoxEngine.getSecretValue("AZURE_OPENAI_BASE_URL"), // https://{{resource}}.openai.azure.com
            model: "gpt-realtime-1.5",                                        // align with deployed model
            onWebSocketClose: (event) => {
                Logger.write("===AzureOpenAI.WebSocket.Close===");
                if (event) Logger.write(JSON.stringify(event));
                VoxEngine.terminate();
            },
        });

        //---------------------- Event handlers -----------------------
        voiceAIClient.addEventListener(OpenAI.RealtimeAPIEvents.SessionCreated, () => {
            voiceAIClient.sessionUpdate(SESSION_CONFIG);
        });

        voiceAIClient.addEventListener(OpenAI.RealtimeAPIEvents.SessionUpdated, () => {
            VoxEngine.sendMediaBetween(call, voiceAIClient);
            voiceAIClient.responseCreate({instructions: "Greet the caller and ask how you can help."});
        });

        // Barge-in: clear buffered audio when the caller starts speaking
        voiceAIClient.addEventListener(OpenAI.RealtimeAPIEvents.InputAudioBufferSpeechStarted, () => {
            Logger.write("===BARGE-IN: AzureOpenAI.InputAudioBufferSpeechStarted===");
            voiceAIClient.clearMediaBuffer();
        });


        voiceAIClient.addEventListener(
            OpenAI.RealtimeAPIEvents.ConversationItemInputAudioTranscriptionCompleted,
            (event) => {
                const {transcript} = event.data.payload;
                if (transcript) Logger.write(`===USER=== ${transcript}`);
            },
        );

        voiceAIClient.addEventListener(
            OpenAI.RealtimeAPIEvents.ResponseOutputAudioTranscriptDelta,
            (event) => {
                const {delta} = event.data.payload;
                if (delta) Logger.write(`===AGENT_DELTA=== ${delta}`);
            },
        );

        voiceAIClient.addEventListener(
            OpenAI.RealtimeAPIEvents.ResponseOutputAudioTranscriptDone,
            (event) => {
                const {transcript} = event.data.payload;
                if (transcript) Logger.write(`===AGENT=== ${transcript}`);
            },
        );

        // Consolidated "log-only" handlers - key OpenAI/VoxEngine debugging events
        [
            OpenAI.RealtimeAPIEvents.ResponseCreated,
            OpenAI.RealtimeAPIEvents.ResponseDone,
            OpenAI.RealtimeAPIEvents.ResponseOutputAudioDone,
            OpenAI.RealtimeAPIEvents.ConnectorInformation,
            OpenAI.RealtimeAPIEvents.HTTPResponse,
            OpenAI.RealtimeAPIEvents.WebSocketError,
            OpenAI.RealtimeAPIEvents.Unknown,
            OpenAI.Events.WebSocketMediaStarted,
            OpenAI.Events.WebSocketMediaEnded,
        ].forEach((eventName) => {
            voiceAIClient.addEventListener(eventName, (event) => {
                Logger.write(`===${event.name}===`);
                if (event?.data) Logger.write(JSON.stringify(event.data));
            });
        });
    } catch (error) {
        Logger.write("===UNHANDLED_ERROR===");
        Logger.write(error);
        terminate();
    }
});

```

## More info

* VoxEngine OpenAI module API: [https://voximplant.com/docs/references/voxengine/openai](https://voximplant.com/docs/references/voxengine/openai)
* Realtime client parameters: [/api-reference/voxengine/openai#createrealtimeapiclient](/api-reference/voxengine/openai#createrealtimeapiclient)
* Voximplant Secrets: [/platform/voxengine/secrets](/platform/voxengine/secrets)
* Voximplant routing rules: [/platform/voxengine/routing-rules](/platform/voxengine/routing-rules)
* Azure OpenAI Realtime audio: [https://learn.microsoft.com/en-us/azure/foundry/openai/how-to/realtime-audio](https://learn.microsoft.com/en-us/azure/foundry/openai/how-to/realtime-audio)
* Azure OpenAI v1 API: [https://learn.microsoft.com/en-us/azure/foundry/openai/api-version-lifecycle](https://learn.microsoft.com/en-us/azure/foundry/openai/api-version-lifecycle)
* Azure OpenAI quotas and limits: [https://learn.microsoft.com/en-us/azure/foundry/openai/quotas-limits](https://learn.microsoft.com/en-us/azure/foundry/openai/quotas-limits)