Create a Grok xAI Realtime Voice Agent

Introduction

The grokvoiceagent.cs sample connects an inbound 3CX call to an xAI Grok real-time voice session. The agent can answer callers, search the approved company directory, connect calls, offer voicemail or chat, and save caller context when configured.

The sample includes a disabled get_department_hours custom tool that demonstrates how to register a safe AI-callable function.

This script requires a 3CX AI Edition license, a PBX build Update 10, and an xAI API account.

Create the Call Script in 3CX

• Sign in to the 3CX Admin Console.
• Open Admin > Integrations > Call Scripts.
• Select +Add from Store.

• Choose grokvoiceagent.cs.

• Enter a lowercase script name without spaces, for example grokreception.
• Choose how the script will run and assign the required DID, trunk route, or internal destination.
• Assign the script to a department.
• Continue to the code editor.

Configure xAI and the Script

Add the following protected parameters to the PBX:

• GROK_API_KEY - the API key for your xAI account.
• GROK_REALTIME_MODEL - the Grok Realtime voice model.

Leave ApiKeyOverride and ModelOverride empty in the script. When these values are empty, the script automatically reads the API key and model from the PBX parameters.

Do not enter the Grok API key directly in the script, especially if the script will be shared, exported or published. A value configured in ApiKeyOverride or ModelOverride takes precedence over the corresponding PBX parameter and should normally be used only for temporary testing.

Next, review these customer settings near the top of the script:

Before production, set AllowAllVisibilityForTesting to false and expose only the required directory objects.

To activate the optional tool example, review its handler and uncomment:

RegisterExampleCustomTool();



Select Save and confirm successful compilation in the Script output.

How It Works

• The caller reaches the script.
• The script creates a restricted directory visibility list.
• 3CX prepares the media channel and starts the Grok realtime voice session.
• The agent converses with the caller and invokes approved 3CX functions.
• Transfers are executed through tools rather than conversational promises.
• Provider or media failure routes the caller to the configured fallback.

Test the Script

• Confirm the selected Grok voice and multilingual behavior.
• Search for allowed and hidden extensions.
• Confirm the agent executes a transfer after caller confirmation.
• Test voicemail and chat when a user is unavailable.
• Say goodbye and verify that the session closes normally.
• Test provider failure and fallback behavior.

Troubleshooting

• Session fails immediately: Verify GROK_API_KEY, the supported model, license, PBX build, and outbound provider connectivity.
• Transfer is announced but not executed: Confirm the custom instructions still require the connection tool and have not been overwritten.
• Directory search returns too much: Disable AddAll() and restrict visibility.
• Fallback fails: Verify the destination and department permissions.
• Prompt is missing: Confirm ERROR exists in the active prompt set.

See Also

• Create a Call Processing Script
• Sample Call Processing Script for PIN
• 3CX Administration Manual

Last Updated

This guide was last updated on 9 September 2026

https://www.3cx.com/docs/grok-ai-voice-agent/