Create a Gemini Realtime Voice Agent

Introduction

The geminivoiceagent.cs sample connects an inbound 3CX call to Google Gemini Live. The agent can greet callers, use permitted directory objects, route calls, offer voicemail or chat, and, when configured, save useful caller context.

The script 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 a Gemini API account.

Create the Call Script in 3CX

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

  • Choose geminivoiceagent.cs.

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

Configure Gemini and the Script

Add the following protected parameters to the PBX:

  • GEMINI_API_KEY - the API key for your Google AI project.
  • GEMINI_REALTIME_MODEL - the Gemini Realtime 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 Gemini 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.

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

Setting

Purpose

Sample value

FallbackDestination

Route used after media or provider failure

102

VoiceName

Gemini Live voice

Capella

AgentName

Agent session name

Capella

AllowAllVisibilityForTesting

Broad directory access for initial tests

true

VisibleNumbers

Explicit destinations the AI may use

100, 102

VisibleDepartments

Approved departments

Sales, Support

VisibleRoles

Optional approved roles

empty

AgentInstructions

Organization behavior and routing rules

Example Company

Set AllowAllVisibilityForTesting to false before production and configure the smallest practical visibility list.

To enable the optional function example, review its data and uncomment:

RegisterExampleCustomTool();

Select ‘Save’ and verify successful compilation.

How It Works

  1. An inbound call reaches the script route point.
  2. The script clears and rebuilds Gemini's permitted 3CX directory visibility.
  3. 3CX prepares the media channel.
  4. The script starts the Gemini Live voice session with the configured instructions, voice, agent name, API key, and model.
  5. Approved tools perform directory, transfer, voicemail, chat, and context actions.
  6. Failures route to the configured fallback and then use the ERROR prompt if routing is unavailable.

Test the Script

  • Verify the selected Gemini voice and caller-language behavior.
  • Search for permitted directory objects.
  • Verify hidden destinations cannot be selected.
  • Test transfer confirmation, voicemail, and chat.
  • Test a natural goodbye.
  • Simulate provider failure and confirm fallback routing.

Troubleshooting

  • Gemini session fails: Confirm the Gemini API key, supported live model, license, PBX build, and outbound connectivity.
  • A voice is rejected: Use a voice supported by the configured Gemini model.
  • Directory results are missing: Check number, department, and role visibility.
  • Too many objects are exposed: Disable AddAll().
  • Fallback or prompt fails: Verify the destination and active ERROR prompt.

See Also

Last Updated

This guide was last updated on 9 September 2026

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