Grok Voice Agent

Example: Answering an incoming call

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

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});