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", or set GROK_MODEL to another xAI Voice Agent model supported by your account.
  • 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.
  • 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// Pin the xAI Voice Agent model used by this example.
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});