Build 3CX Programmable Extensions that connect AI agents to live calls.

3CX Programmable Extensions let developers create AI agents that handle live calls through the 3CX Phone System.

The 3CX Agentic Call Control GitHub repository provides ready-made code examples for connecting Programmable Extensions to OpenAI, xAI, Google Gemini and Alibaba Cloud Qwen. Each example connects the AI provider to 3CX call control, giving developers a starting point for building their own realtime voice applications.

Choose the provider that best fits your use case, configure the agent and test it directly through 3CX. Read on to learn more.

Choose an AI Provider for 3CX Programmable Extensions

Choose the AI service that fits the job without rebuilding the 3CX side of the call. Each provider has its own ready-made example, so you start with the right API, models, voices and regional settings.

  • OpenAI: Use OpenAI Realtime for a familiar and easy to use starting point.
  • xAI: Connect to xAI's realtime voice service.
  • Google Gemini: Build with Google's Gemini realtime service.
  • Alibaba Cloud Qwen: Use Qwen with regional endpoints, including international or Beijing for deployments in mainland China.

For the provider-specific setup, see AI Providers for 3CX Programmable Extensions. It covers the 3CX connection, provider settings and test-call setup.

Use More Than One AI Provider

You can set up any number of agents from any provider with custom configuration.

In other words, you can have several Sales Agents from multiple providers: for example an English one from Grok or OpenAI for your Western countries and then a Qwen one from Alibaba to serve your Chinese callers specifically.

Connect Securely to 3CX

Before the agent can handle calls, it needs its own approved login to the PBX. In 3CX, this is called a Service Principal. It gives the agent a Client ID and PBX API key.

An Administrator decides which extensions the agent can use. The PBX API key connects the agent to 3CX. The separate provider API key connects it to OpenAI, xAI, Gemini or Qwen.

When you start the example, the terminal will confirm whether it is connected to both 3CX and the selected AI provider. You will need to check it shows ‘ready’ before calling the agent.

Shape the Caller Experience

Each example includes a receptionist profile that defines what callers hear. Change the agent name, company name, greeting and voice to match your business.

The profile also controls how the agent speaks and handles calls. For example:

  • Agent role: Set the instructions, language and reply style.
  • Call actions: Decide whether it can transfer calls or end them.
  • PBX tools: Choose the PBX information it can use, such as phonebook lookup.
  • Call screening: Enable screening and availability checks before transfers.
  • Difficult callers: Set rules for spam, hostile or non-cooperative callers.

Create separate profiles for different teams, call types or languages without changing the 3CX connection.

Test 3CX Programmable Extensions With a Real Call

Once your Programmable Extension is set up, and the startup log shows a successful setup, trigger a call to your Service Principal Client ID from the 3CX Web Client. Your Programmable Extension will respond as instructed inside its prompt.

This test effectively checks the full path: Caller > PBX > AI provider > PBX > Caller.

Start with the supplied example, confirm a successful conversation with default settings, then adjust one setting at a time. This makes it easier to compare providers, voices, settings and profiles while keeping the 3CX side of the test consistent.

Join the Discussion

Join the 3CX discussion in our dedicated Partner or Customer Forums. Follow us on X and LinkedIn to stay-up-to date on latest news and feature releases.