• Posted on
  • By
  • In 3CX

Building Custom AI Voice Agents on 3CX: Programmable Extensions & the Call Control API

A custom AI voice agent on 3CX is an externally hosted application that connects to your PBX, streams the caller’s audio in both directions, and controls call routing — combining two 3CX developer surfaces with an external AI provider. Those two surfaces have very different release statuses, and getting them straight is the whole point of this article. Programmable Extensions — the officially sanctioned way to run an external app as a 3CX extension for AI voice — shipped in V20 Update 10 as ALPHA (announced 2026-07-30), for testing and evaluation only, not for production. The Call Control API it builds on has been GA (generally available) since V18 and is production-grade today. This post explains how the pieces fit, what is stable versus preview, and how ECOLOR can architect, build, integrate, test, monitor and support a voice agent for you.

The two building blocks — and why their status differs

Every custom AI voice agent on 3CX rests on two native developer capabilities plus one external brain. Keep the release status of each one distinct — do not let a vendor blur an Alpha feature into a production promise.

  • Programmable Extensions — ALPHA (V20 Update 10 Alpha, announced 2026-07-30). An externally hosted application that connects to the PBX and operates like a native extension: it can join calls, receive audio, stream audio bidirectionally, and drive routing through the Call Control API. This is the officially documented architecture for AI voice agents on 3CX — but as of August 2026 it is for testing and evaluation only and must not be installed on production systems. To try it, a PBX must already be on V20 Update 9, then opt into Update 10 Alpha.
  • Call Control API — GA since V18 (production). The mature developer surface for programmatic call control: make, answer, route, transfer, drop and monitor calls, and retrieve participant information. It is exposed as the Call Control Web API plus an official TypeScript SDK, @3cx/call-control-sdk. It requires an 8SC+ Enterprise license and Call Flow Designer (CFD) access. This is the stable foundation the Alpha voice features are built on.
  • An external AI provider (bring-your-own key). 3CX itself never performs the speech-to-text, reasoning, or text-to-speech in the custom-agent path. That intelligence always comes from an external real-time voice provider you connect and pay for directly.

In short: the plumbing that carries audio and controls the call (Call Control API) is production-ready; the Programmable Extensions path that packages an external app as an extension is still Alpha. We build and validate against both, but we position production rollouts honestly around what has reached a stable release.

The four external AI providers 3CX officially documents

3CX officially documents and demonstrates exactly four external real-time voice providers through its own agentic-call-control GitHub repository. Each is a developer-built, bring-your-own-key pattern — you supply the provider account and API key, and the provider handles speech recognition, reasoning and speech synthesis in a single real-time bidirectional stream:

  • OpenAI Realtime API
  • Google Gemini Live API
  • xAI Grok Voice Agent API
  • Alibaba Cloud Qwen Omni Realtime (DashScope)

We do not claim any provider beyond these four as officially supported. Each provider carries its own release status, regional availability, pricing and billing — those are confirmed during solution design, and the AI usage is billed to you by the provider, not by 3CX.

Reference architecture: how a custom AI voice agent is assembled

The officially recommended pattern for a custom agent is an external Programmable Extension that runs entirely on your own infrastructure — no 3CX source code or modifications required. Audio flows as PCM, 8 kHz, 16-bit, mono, and the orchestrator connects to 3CX over a WebSocket with automatic reconnection. A typical build looks like this:

  1. Register a Service Principal in 3CX. In the Web Client, go to Admin → Integrations → API, add a service principal, set a Client ID, enable Call Control API access for the application, optionally assign a DID and select the extensions it may control, then capture the Client Secret (shown once).
  2. Stand up the orchestrator app. Using @3cx/call-control-sdk, the external application connects with the app ID, app secret and PBX base URL, then joins calls as a Programmable Extension.
  3. Bridge audio to the AI provider. The orchestrator streams the caller’s PCM audio out to one of the four documented real-time providers and streams the provider’s synthesized voice back into the call — bidirectionally, in real time.
  4. Give the agent tools. Wire up local call-control actions (transfer, voicemail, drop, screening) and, optionally, lookups such as phonebook access, plus custom tools for CRM or calendar workflows.
  5. Route intelligently. Use the Call Control API to escalate to a human queue, transfer to the right department, or fall back to an IVR when the conversation calls for it.

Crucially, this is ECOLOR custom development, not a native 3CX AI agent. 3CX supplies the telephony, routing, extensions, SIP trunks and DIDs; the external provider supplies the intelligence; and the orchestration, prompts, tools and business logic are engineered per project. We never describe an ECOLOR-built or bring-your-own-key agent as a native 3CX feature.

Security, data control and production considerations

Because the agent runs on your own infrastructure and calls an external AI provider, security and data governance are design decisions, not defaults. We plan for authenticated Service Principal credentials with least-privilege extension scoping, encrypted transport for the audio and control channels, careful handling of call audio and transcripts, and clear boundaries on what the AI provider retains. Hosting location and data-residency options are confirmed during solution design; the architecture is built to support your governance and compliance efforts, but no configuration can by itself make an organization compliant with any specific regulation.

For scalability and production readiness, we consider concurrency against your simultaneous-call (SC) licensing, orchestrator autoscaling and reconnection behaviour, latency budgets across the audio bridge, graceful human hand-off, observability, and provider rate limits and failover. And we keep the release-status line bright: while Programmable Extensions remain Alpha, we deliver evaluation and pilot environments today, and schedule production rollout for when the feature reaches a stable 3CX release. There are no guarantees of uptime, latency or savings — targets are validated against your specific environment.

How ECOLOR delivers your AI voice agent

As a MENA 3CX Solution Provider, ECOLOR Technologies offers end-to-end delivery: solution architecture, development, provider integration, rigorous testing, monitoring and ongoing support — with a Saudi-based technical team providing Arabic and English support. We handle the Service Principal setup, the orchestrator, the provider bridge, the routing logic, and the observability so your team gets a working agent rather than a stack of SDKs.

Beyond native 3CX capabilities, ECOLOR also offers its own AI Voice Agent — an ECOLOR-developed conversational voice agent with deep integration — and AutoConnect, ECOLOR’s proprietary communication-automation platform (AutoDialer, AutoDistributor / Ready Distributor, Evaluation, Smart Routing, dashboards and API/webhook workflows). Both extend 3CX and integrate with it; neither is a native 3CX feature. This lets us match the right approach to your requirements — a native path, a custom Programmable-Extension agent, ECOLOR’s own AI Voice Agent, or AutoConnect automation — instead of forcing one model onto every use case. See our 3CX Programmable Extensions & AI voice agents page, the broader 3CX AI Agents hub, ECOLOR’s AI Voice Agent, the AutoConnect platform, the Alpha 3CX AI Customer Service Agent, and how it all sits on your 3CX phone system in Saudi Arabia.

FAQ

Is a custom AI voice agent on 3CX production-ready today?

The Call Control API it relies on is GA and production-grade (since V18). The Programmable Extensions path that packages an external AI app as a 3CX extension is Alpha in V20 Update 10 (announced 2026-07-30) — for testing and evaluation only, not for production. ECOLOR can build evaluation and pilot environments today and schedule production rollout for when Programmable Extensions reach a stable release.

Which AI providers does 3CX officially support for voice agents?

3CX officially documents four external real-time voice providers via its agentic-call-control repository: OpenAI Realtime, Google Gemini Live, xAI Grok, and Alibaba Qwen Omni. All are bring-your-own-key patterns — you supply and fund the provider account. We do not present any other provider as officially supported.

What 3CX license do I need?

The Call Control API requires an 8SC+ Enterprise license and Call Flow Designer (CFD) access. The Programmable Extensions / AI voice-agent path additionally needs the V20 Update 10 feature set, and each external AI provider requires its own account and API key. Exact licensing is confirmed per project.

Does 3CX do the speech recognition and AI reasoning itself?

No. In the custom-agent path, 3CX provides only the telephony, routing, extensions, SIP trunks and DIDs. Speech-to-text, reasoning and text-to-speech are always handled by the external AI provider you connect, over a real-time bidirectional PCM audio stream.

Is ECOLOR’s AI Voice Agent the same as the native 3CX AI Agents?

No. ECOLOR’s AI Voice Agent and AutoConnect are ECOLOR-developed products that extend and integrate with 3CX; they are not native 3CX features. The native 3CX AI Agents are a separate, 3CX-provided capability. We always keep that attribution explicit.

Book a Consultation

Ready to explore a custom AI voice agent on 3CX — an evaluation pilot now, a production plan for when the platform is ready? ECOLOR Technologies will architect, build, integrate, test, monitor and support it for you. Book a consultation or call our unified number 920033987 to talk with our Saudi-based team.