Voice AI ClientsxAI Grok Voice Agent

Example: Answering an incoming call

Connect an inbound call to a Grok voice agent
View as Markdown

For the complete documentation index, see llms.txt.

Overview

This minimal example answers an inbound call and connects it to the Grok Voice Agent API with only core settings and barge-in support—no extra tools or function calling.

⬇️ Jump to the Full VoxEngine scenario.

Prerequisites

Architecture

Usage highlights

  • Create a VoiceAgentAPIClient with Grok.createVoiceAgentAPIClient(...).
  • Select the Grok voice model with model: "grok-voice-think-fast-1.0" until xAI changes the Voice Agent API default on May 31, 2026.
  • Configure the session with voice, turn_detection, and a short instructions prompt.
  • Bridge audio with VoxEngine.sendMediaBetween(call, client).
  • Enable barge-in by clearing the media buffer when the caller starts speaking.

Turn detection & barge-in

When InputAudioBufferSpeechStarted fires, clear the media buffer so the caller can interrupt the agent:

1voiceAgentAPIClient.addEventListener(
2  Grok.VoiceAgentAPIEvents.InputAudioBufferSpeechStarted,
3  () => voiceAgentAPIClient.clearMediaBuffer()
4);

Configure before you run

  • Set XAI_API_KEY in Voximplant Secrets.
  • Change GROK_MODEL if you want to use a different Grok voice model. After May 31, 2026, you can remove the explicit model selection and use the xAI default.
  • Adjust the SYSTEM_PROMPT in the example to match your brand voice and guardrails.

Try it

Suggested test prompts:

  • “Hello”
  • “What can you help me with?”
  • “Goodbye.”

Notes

See the VoxEngine API Reference for more details.

Full VoxEngine scenario

voxeengine-grok-answer-incoming-call.js
1require(Modules.Grok);
2// Temporary explicit model until xAI changes the Voice Agent API default on May 31, 2026.
3const GROK_MODEL = "grok-voice-think-fast-1.0";
4const SYSTEM_PROMPT = `
5  You are Voxi, a concise phone agent for Voximplant callers.
6  Keep answers brief and helpful. If you do not know, say so and offer to connect them to a human.
7`;
8
9VoxEngine.addEventListener(AppEvents.CallAlerting, async ({call}) => {
10    let voiceAIClient;
11
12    // Termination functions - add cleanup and logging as needed
13    call.addEventListener(CallEvents.Disconnected, ()=>VoxEngine.terminate());
14    call.addEventListener(CallEvents.Failed, ()=>VoxEngine.terminate());
15
16    call.answer();
17    // call.record({ hd_audio: true, stereo: true });   // Optional: record the call
18
19    try {
20        voiceAIClient = await Grok.createVoiceAgentAPIClient({
21            xAIApiKey: VoxEngine.getSecretValue("XAI_API_KEY"),
22            model: GROK_MODEL,
23            onWebSocketClose: (event) => {
24                Logger.write("===Grok.WebSocket.Close===");
25                if (event) Logger.write(JSON.stringify(event));
26                VoxEngine.terminate();
27            },
28        });
29
30        // Set up the session once created
31        voiceAIClient.addEventListener(
32            Grok.VoiceAgentAPIEvents.ConversationCreated,
33            () => {
34                voiceAIClient.sessionUpdate({
35                    session: {
36                        voice: "Ara",
37                        turn_detection: {type: "server_vad"},
38                        instructions: SYSTEM_PROMPT,
39                    },
40                });
41            },
42        );
43
44        // Wait for Grok setup, then bridge audio and trigger the greeting
45        voiceAIClient.addEventListener(
46            Grok.VoiceAgentAPIEvents.SessionUpdated,
47            () => {
48                VoxEngine.sendMediaBetween(call, voiceAIClient);
49                voiceAIClient.responseCreate({instructions: "Hello! How can I help today?"});
50            },
51        );
52
53        // Simple barge-in: clear buffered audio when caller starts speaking
54        voiceAIClient.addEventListener(
55            Grok.VoiceAgentAPIEvents.InputAudioBufferSpeechStarted,
56            () => voiceAIClient.clearMediaBuffer(),
57        );
58
59        // -------------------- Log Other Events --------------------
60        [
61            CallEvents.FirstAudioPacketReceived,
62            Grok.Events.WebSocketMediaStarted,
63            Grok.Events.WebSocketMediaEnded,
64            Grok.VoiceAgentAPIEvents.ConnectorInformation,
65            Grok.VoiceAgentAPIEvents.ResponseCreated,
66            Grok.VoiceAgentAPIEvents.ResponseOutputItemAdded,
67            Grok.VoiceAgentAPIEvents.ResponseOutputItemDone,
68            Grok.VoiceAgentAPIEvents.ResponseOutputAudioTranscriptDelta,
69            Grok.VoiceAgentAPIEvents.ResponseOutputAudioTranscriptDone,
70            Grok.VoiceAgentAPIEvents.ResponseOutputAudioDone,
71            Grok.VoiceAgentAPIEvents.ResponseDone,
72            Grok.VoiceAgentAPIEvents.InputAudioBufferSpeechStopped,
73            Grok.VoiceAgentAPIEvents.InputAudioBufferCommitted,
74            Grok.VoiceAgentAPIEvents.ConversationItemAdded,
75            Grok.VoiceAgentAPIEvents.ConversationItemInputAudioTranscriptionCompleted,
76            Grok.VoiceAgentAPIEvents.WebSocketError,
77            Grok.VoiceAgentAPIEvents.Unknown,
78        ].forEach((evtName) => {
79            voiceAIClient.addEventListener(evtName, (e) => {
80                Logger.write(`===${e.name}===>${JSON.stringify(e)}`);
81            });
82        });
83
84    } catch (error) {
85        Logger.write("===SOMETHING_WENT_WRONG===");
86        Logger.write(error);
87        VoxEngine.terminate();
88    }
89});