xAI 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(...).
  • 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 ApplicationStorage.
  • 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);
2require(Modules.ApplicationStorage);
3
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: (await ApplicationStorage.get("XAI_API_KEY")).value,
22            onWebSocketClose: (event) => {
23                Logger.write("===Gemini.WebSocket.Close===");
24                if (event) Logger.write(JSON.stringify(event));
25                VoxEngine.terminate();
26            },
27        });
28
29        // Set up the session once created
30        voiceAIClient.addEventListener(
31            Grok.VoiceAgentAPIEvents.ConversationCreated,
32            () => {
33                voiceAIClient.sessionUpdate({
34                    session: {
35                        voice: "Ara",
36                        turn_detection: {type: "server_vad"},
37                        instructions: SYSTEM_PROMPT,
38                    },
39                });
40            },
41        );
42
43        // Wait for Grok setup, then bridge audio and trigger the greeting
44        voiceAIClient.addEventListener(
45            Grok.VoiceAgentAPIEvents.SessionUpdated,
46            () => {
47                VoxEngine.sendMediaBetween(call, voiceAIClient);
48                voiceAIClient.responseCreate({instructions: "Hello! How can I help today?"});
49            },
50        );
51
52        // Simple barge-in: clear buffered audio when caller starts speaking
53        voiceAIClient.addEventListener(
54            Grok.VoiceAgentAPIEvents.InputAudioBufferSpeechStarted,
55            () => voiceAIClient.clearMediaBuffer(),
56        );
57
58        // -------------------- Log Other Events --------------------
59        [
60            CallEvents.FirstAudioPacketReceived,
61            Grok.Events.WebSocketMediaStarted,
62            Grok.Events.WebSocketMediaEnded,
63            Grok.VoiceAgentAPIEvents.ConnectorInformation,
64            Grok.VoiceAgentAPIEvents.ResponseCreated,
65            Grok.VoiceAgentAPIEvents.ResponseOutputItemAdded,
66            Grok.VoiceAgentAPIEvents.ResponseOutputItemDone,
67            Grok.VoiceAgentAPIEvents.ResponseOutputAudioTranscriptDelta,
68            Grok.VoiceAgentAPIEvents.ResponseOutputAudioTranscriptDone,
69            Grok.VoiceAgentAPIEvents.ResponseOutputAudioDone,
70            Grok.VoiceAgentAPIEvents.ResponseDone,
71            Grok.VoiceAgentAPIEvents.InputAudioBufferSpeechStopped,
72            Grok.VoiceAgentAPIEvents.InputAudioBufferCommitted,
73            Grok.VoiceAgentAPIEvents.ConversationItemAdded,
74            Grok.VoiceAgentAPIEvents.ConversationItemInputAudioTranscriptionCompleted,
75            Grok.VoiceAgentAPIEvents.WebSocketError,
76            Grok.VoiceAgentAPIEvents.Unknown,
77        ].forEach((evtName) => {
78            voiceAIClient.addEventListener(evtName, (e) => {
79                Logger.write(`===${e.name}===>${JSON.stringify(e)}`);
80            });
81        });
82
83    } catch (error) {
84        Logger.write("===SOMETHING_WENT_WRONG===");
85        Logger.write(error);
86        VoxEngine.terminate();
87    }
88});