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

# Example: Answering an incoming call

> This example answers an inbound Voximplant call and bridges audio to Inworld Realtime API for speech-to-speech conversations.

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

This example answers an inbound Voximplant call and bridges audio to Inworld Realtime API for a live speech-to-speech demo.
The scenario configures Inworld STT, Claude Sonnet, expressive Inworld TTS2 voice output, automatic turn responses, backchannels, responsiveness behavior, and barge-in.
Video link: Inbound SIP demo video coming soon.

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

## Prerequisites

* Set up an inbound entrypoint for the caller:
  * [Phone number](/getting-started/network-options/phone-numbers-pstn)
  * [WhatsApp](/getting-started/network-options/whatsapp)
  * [SIP user or SIP registration](/getting-started/network-options/sip)
  * [App user](/getting-started/network-options/web-mobile)
* Create a [routing rule](/platform/voxengine/routing-rules) that points the destination to this scenario.
* Store your Inworld API key in Voximplant [Secrets](/platform/voxengine/secrets) under `INWORLD_API_KEY`.

## Session setup

Create an `Inworld.RealtimeAPIClient` with your API key from VoxEngine Secrets and a unique session key.
The session key is an Inworld session identifier; the example generates a new string per call.

```js title="Create Inworld client"
voiceAIClient = await Inworld.createRealtimeAPIClient({
  apiKey: VoxEngine.getSecretValue("INWORLD_API_KEY"),
  sessionKey: `inworld-realtime-demo-${Date.now()}`,
  onWebSocketClose: terminate,
});
```

After Inworld emits `SessionCreated`, send a `session.update` payload that configures the model, prompt, output modalities, speech recognition, turn detection, voice output, and Inworld-specific provider features.
The Inworld-specific settings are passed in the `providerData` block inside the same session config:

```js title="Session setup"
voiceAIClient.addEventListener(Inworld.RealtimeAPIEvents.SessionCreated, () => {
  voiceAIClient.sessionUpdate({
    session: {
      type: "realtime",
      model: "claude-sonnet-4-6",
      instructions: SYSTEM_PROMPT,
      output_modalities: ["audio", "text"],
      audio: {
        input: {
          transcription: {
            model: "inworld/inworld-stt-1",
            language: "en",
            prompt: "Important terms: Voximplant, VoxEngine, Inworld, Inworld Realtime, TTS2, SIP, WhatsApp Business Calling.",
          },
          turn_detection: {
            type: "semantic_vad",
            eagerness: "high",
            create_response: true,
            interrupt_response: true,
          },
        },
        output: { voice: "Ashley", model: "inworld-tts-2", speed: 1.0 },
      },
      providerData: {
        tts: {
          delivery_mode: "BALANCED",
          segmenter_strategy: "full_turn",
          steering_handling: "emit_once",
        },
        stt: { voice_profile: true },
        backchannel: {
          enabled: true,
          eval_interval_ms: 800,
          min_speech_ms: 800,
          min_gap_ms: 4000,
          max_per_turn: 3,
          volume_gain: 0.6,
        },
        responsiveness: {
          enabled: true,
          initial_wait_timeout_ms: 500,
          hard_deadline_ms: 1200,
          max_tokens: 8,
          min_filler_gap_ms: 5000,
          max_initial_per_turn: 1,
          enable_filler_on_first_assistant_reply: false,
        },
      },
    },
  });
});
```

In this config, standard Realtime API fields set the voice model, STT model, and turn detection.
The nested `providerData` block adds Inworld-specific behavior: `delivery_mode: "BALANCED"` for natural call-center speech, `segmenter_strategy: "full_turn"` for coherent spoken turns, backchannels for brief active-listening cues, and responsiveness settings to reduce dead air when the model needs more time.

For deeper tuning details, see Inworld's docs for [Realtime API Extensions](https://docs.inworld.ai/realtime/provider-data), [Adding Naturalness](https://docs.inworld.ai/realtime/usage/naturalness), [Back-channel responses](https://docs.inworld.ai/realtime/usage/back-channel), and [Responsiveness](https://docs.inworld.ai/realtime/usage/responsiveness).

## Connect call audio and greet

Once Inworld emits `SessionUpdated`, bridge audio both ways between the call and Inworld.
Then create a short text conversation item and call `responseCreate`.
This explicit seed item gives Inworld a normal user turn to answer, so the agent greets automatically before the caller speaks.

```js title="Connect audio and trigger greeting"
VoxEngine.sendMediaBetween(call, voiceAIClient);
voiceAIClient.conversationItemCreate({
  item: {
    type: "message",
    role: "user",
    content: [
      {
        type: "input_text",
        text: "The phone call just connected. Say only: Hi, this is Voxi from Voximplant. How can I help?",
      },
    ],
  },
});
voiceAIClient.responseCreate({
  response: {
    output_modalities: ["audio", "text"],
  },
});
```

## Barge-in

When the caller starts speaking, clear any queued Inworld output audio so the caller can interrupt the agent naturally.

```js title="Barge-in"
voiceAIClient.addEventListener(Inworld.RealtimeAPIEvents.InputAudioBufferSpeechStarted, () => {
  voiceAIClient.outputAudioBufferClear({});
});
```

## Notes

* `INWORLD_API_KEY` is read from Voximplant Secrets.
* `sessionKey` can be any unique string to maintain context for the Inworld session.
* `create_response: true` lets Inworld respond automatically after caller turns.
* The initial greeting is triggered manually with `conversationItemCreate` followed by `responseCreate`.
* [See the Inworld VoxEngine API reference for more details](/api-reference/voxengine/inworld).

## Full VoxEngine scenario

```javascript title={"voxeengine-inworld-answer-incoming-call.js"} maxLines={0}
/**
 * Voximplant + Inworld Realtime API demo
 * Scenario: answer an incoming call and bridge it to Inworld Realtime.
 */

require(Modules.Inworld);

const SYSTEM_PROMPT = `
You are Voxi, a Voximplant developer advocate on a live phone call.
Voximplant is pronounced VOX-im-plant.
Keep answers short, natural, and useful for a marketing demo.
Default to one short sentence under 12 words.

If the caller asks "Tell me about Voximplant and Inworld" or any similar broad
question, answer directly: Voximplant brings Inworld Realtime agents to real
communication channels, while Inworld provides expressive realtime voice,
conversation-aware delivery, TTS2, persona control, and voice direction.

Demo goal:
- Explain how Voximplant brings Inworld Realtime voice agents to real communications channels.
- Highlight Inworld expressive realtime speech, TTS2-style delivery, conversation awareness, voice direction, and persona control.
- Highlight Voximplant calling, SIP, WhatsApp Business Calling, browser calls, native app calls, and VoxEngine orchestration.
- Mention that teams can use Inworld without building a custom media gateway.
- Mention production telephony features when relevant: transfers, DTMF, barge-in, no-audio detection, debugging, and monitoring.

Voice style:
- Sound like an expressive product expert, not a flat IVR.
- Adapt your tone to the caller's question.
- Use short, human turns. Default to one short spoken sentence.
- Use small spoken disfluencies sparingly: "uh", "hmm", "well", "right", "okay".
- Use at most one TTS-2 non-verbal tag per turn, and often none: [laugh], [breathe], [sigh], [clear throat].
- Use at most one [speak ...] steering tag per turn. If used, it must be first.
- If the caller asks about emotion, persona, pacing, or voice control, demonstrate it briefly with a [speak ...] tag or a natural non-verbal cue.
- If the caller asks what this demo is, say this is Voximplant connected to Inworld Realtime on a live phone call.

If the caller asks about a product detail you are not sure of, say you would check the latest docs instead of guessing.
`;

const SESSION_CONFIG = {
    session: {
        type: "realtime",   // Realtime mode keeps the call audio stream connected to Inworld.
        model: "claude-sonnet-4-6",     // Note: some models require a payment method on file
        instructions: SYSTEM_PROMPT,
        output_modalities: ["audio", "text"],   // Audio is required for automatic turn-detection responses
        audio: {
            input: {
                // Inworld STT keeps the transcript inside the same realtime session.
                transcription: {
                    model: "inworld/inworld-stt-1",
                    language: "en",
                    prompt: "Important terms: Voximplant, VoxEngine, Inworld, Inworld Realtime, TTS2, SIP, WhatsApp Business Calling.",
                },
                // Semantic VAD decides when the caller's turn is complete and can auto-create the response.
                turn_detection: {
                    type: "semantic_vad",
                    eagerness: "high",
                    create_response: true,
                    interrupt_response: true,
                },
            },
            output: {
                // TTS-2 voice output. This is where the demo showcases expressive delivery.
                voice: "Ashley",
                model: "inworld-tts-2",
                speed: 1.0,
            },
        },
        providerData: {
            tts: {
                delivery_mode: "BALANCED", // Naturalness: steady call-center prosody with TTS-2 control tags.
                segmenter_strategy: "full_turn", // Naturalness: wait for the full turn before speech output.
                steering_handling: "emit_once",  // Apply [speak ...] steering once per response
            },
            stt: {
                // Helps Inworld adapt recognition to the current speaker during the session.
                voice_profile: true,
            },
            backchannel: {
                // Back-channel can produce short acknowledgements while the caller is still speaking.
                enabled: true,
                eval_interval_ms: 800,
                min_speech_ms: 800,
                min_gap_ms: 4000,
                max_per_turn: 3,
                volume_gain: 0.6,
            },
            responsiveness: {
                // Responsiveness allows brief filler behavior if generation is slower than expected.
                enabled: true,
                initial_wait_timeout_ms: 500,
                hard_deadline_ms: 1200,
                max_tokens: 8,
                min_filler_gap_ms: 5000,
                max_initial_per_turn: 1,
                enable_filler_on_first_assistant_reply: false,
            },
        },
    },
};

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

    // Helper to clean-up the call when done
    const terminate = (event) => {
        if (event) Logger.write(JSON.stringify(event));
        voiceAIClient?.close();
        VoxEngine.terminate();
    };

    // Termination handlers
    call.addEventListener(CallEvents.Disconnected, terminate);
    call.addEventListener(CallEvents.Failed, terminate);

    try {
        call.answer();
        // Optional: record & transcribe the call. Note: use `require(Modules.ASR)` needed for enums
        // call.record({hd_audio: true, stereo: true, transcribe: true, provider: TranscriptionProvider.GOOGLE, language: ASRLanguage.ENGLISH_US });

        // Create client and connect to Inworld Realtime.
        voiceAIClient = await Inworld.createRealtimeAPIClient({
            apiKey: VoxEngine.getSecretValue("INWORLD_API_KEY"),
            sessionKey: `inworld-realtime-demo-${Date.now()}`,
            onWebSocketClose: terminate,
        });

        voiceAIClient.addEventListener(Inworld.RealtimeAPIEvents.SessionCreated, () => {
            Logger.write("===Inworld.SessionCreated===");
            voiceAIClient.sessionUpdate(SESSION_CONFIG);
        });

        // Once the session is configured, bridge call media and trigger the greeting.
        voiceAIClient.addEventListener(Inworld.RealtimeAPIEvents.SessionUpdated, () => {
            Logger.write("===Inworld.SessionUpdated===");
            VoxEngine.sendMediaBetween(call, voiceAIClient);
            voiceAIClient.conversationItemCreate({
                item: {
                    type: "message",
                    role: "user",
                    content: [
                        {
                            type: "input_text",
                            text: `The phone call just connected.
                                   Greet the caller as Voxi from Voximplant and invite a question about Voximplant and Inworld.`,
                        },
                    ],
                },
            });
            voiceAIClient.responseCreate({
                response: {
                    output_modalities: ["audio", "text"],
                },
            });
        });

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

        // Caller transcript for debugging.
        voiceAIClient.addEventListener(
            Inworld.RealtimeAPIEvents.ConversationItemInputAudioTranscriptionCompleted,
            (event) => {
                const payload = event?.data?.payload || event?.data || {};
                const transcript = payload.transcript || payload.text || payload.delta;
                if (transcript) Logger.write(`===USER==> ${transcript}`);
            },
        );

        // Final agent transcript for readable call logs.
        voiceAIClient.addEventListener(
            Inworld.RealtimeAPIEvents.ResponseOutputAudioTranscriptDone,
            (event) => {
                const payload = event?.data?.payload || event?.data || {};
                const transcript = payload.transcript || payload.text;
                if (transcript) Logger.write(`===AGENT==> ${transcript}`);
            },
        );

        // Consolidated log-only handlers for lifecycle, audio, and error debugging.
        [
            Inworld.RealtimeAPIEvents.ConversationItemInputAudioTranscriptionDelta,
            Inworld.RealtimeAPIEvents.ResponseCreated,
            Inworld.RealtimeAPIEvents.ResponseDone,
            Inworld.RealtimeAPIEvents.ResponseOutputAudioDone,
            Inworld.RealtimeAPIEvents.InputAudioBufferSpeechStopped,
            Inworld.RealtimeAPIEvents.InputAudioBufferCommitted,
            Inworld.RealtimeAPIEvents.InputAudioBufferCleared,
            Inworld.RealtimeAPIEvents.OutputAudioBufferStarted,
            Inworld.RealtimeAPIEvents.OutputAudioBufferStopped,
            Inworld.RealtimeAPIEvents.OutputAudioBufferCleared,
            Inworld.RealtimeAPIEvents.ConnectorInformation,
            // Inworld.RealtimeAPIEvents.ResponseOutputAudioTranscriptDelta, // this is noisy
            Inworld.RealtimeAPIEvents.HTTPResponse,
            Inworld.RealtimeAPIEvents.Error,
            Inworld.RealtimeAPIEvents.WebSocketError,
            Inworld.RealtimeAPIEvents.Unknown,
            Inworld.Events.WebSocketMediaStarted,
            Inworld.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===");
        terminate(error instanceof Error ? {message: error.message, stack: error.stack} : {error: String(error)});
    }
});

```