3CX Developer & AI · ECOLOR Technologies

Custom AI voice agents on 3CX

3CX Programmable Extensions and the Call Control API let an external application join calls, control routing and exchange audio with the caller — the officially-sanctioned path to building an AI voice agent on 3CX. ECOLOR Technologies designs, develops, integrates and supports these solutions with a Saudi-based technical team.

A precise note: Programmable Extensions are still Alpha (for testing and evaluation), while the Call Control API has been GA for years.

Book a consultation Call us9200 33987 WhatsApp

MENA 3CX Solution Provider
Call Control API — GA
Programmable Extensions — Alpha
OpenAI · Gemini · Grok · Qwen
Saudi-based development team

01 · Definition

What Programmable Extensions and 3CX AI voice agents are

Programmable Extensions is an official 3CX feature that lets an external application — running on your own infrastructure — connect to a 3CX PBX and behave like a native extension: it joins calls, receives them, streams PCM audio bidirectionally with the caller, and controls routing through the Call Control API. This is the official path for building an AI voice agent on 3CX.

It is essential to separate two layers that do NOT share a release status: Programmable Extensions shipped in V20 Update 10 as Alpha — for testing and evaluation only, not for production. The Call Control API, by contrast, is the mature developer surface that has been generally available since V18, and it is the stable foundation the newer features build on. We keep that distinction clear across this page.

The AI itself — speech-to-text, reasoning and text-to-speech — is never done by 3CX. 3CX provides telephony, routing, transfers, SIP trunks and DIDs; speech understanding and voice generation come from an external AI provider that you connect with your own API key. Any AI voice agent ECOLOR builds this way is custom development on top of 3CX — not a native 3CX agent.

02 · Release status

Release status, made explicit — Programmable Extensions (Alpha) vs Call Control API (GA)

As of August 2026, 3CX has released Programmable Extensions as part of V20 Update 10 Alpha — which 3CX states is «intended for testing and evaluation only and should not be installed on production systems». The current stable release is V20 Update 9 (Final). We therefore treat Programmable Extensions today as an evaluation and pilot path, not a production-ready solution.

The Call Control API, in contrast, has been generally available (GA) since V18, with an official TypeScript SDK named @3cx/call-control-sdk, and it requires an Enterprise license at 8SC or above plus Call Flow Designer (CFD) access. This surface can be relied on in production within its limits and requirements.

Our practical position: today we can design and build an evaluation environment for a 3CX AI voice agent, pilot it, measure it and prepare its architecture; then move it to production once Programmable Extensions reaches a stable release. We make no production, performance or availability guarantees for a feature still in Alpha.

Programmable Extensions — Alpha (V20 Update 10): testing and evaluation only, not for production.
Call Control API — GA since V18: mature foundation, requires Enterprise 8SC+ and CFD access.
Current stable release — V20 Update 9 (Final).
The AI (STT · reasoning · TTS) — from an external provider with your key, not from 3CX.

03 · Capabilities

What this developer layer makes possible

Capabilities attributed precisely between what is official in 3CX and what ECOLOR builds:

An app that acts like a native extension

Via Programmable Extensions (Alpha), an external app on your infrastructure connects to 3CX and behaves like a native extension — monitoring, receiving and controlling the path of calls.

Real-time bidirectional audio

PCM 8 kHz 16-bit mono audio streamed both ways between caller and agent, which is what makes a natural spoken conversation with the AI possible.

Full call control

Via the Call Control API (GA): answer, route, transfer, drop and monitor, plus reading participant data and call state over a WebSocket with automatic reconnect.

An official developer SDK

The official TypeScript SDK @3cx/call-control-sdk provides call joining, audio read/write streaming and transfers — a stable base on which we build the agent logic.

An external AI provider

Speech understanding, reasoning and voice generation come from an external provider (OpenAI · Gemini · Grok · Qwen) over a single real-time audio stream, with your own API key.

Tools and system connections

In-call tool calls: transfer, drop or screen; phonebook lookup via the 3CX MCP server; and CRM or calendar connections via additional MCP servers.

04 · Components

The terms and components you will meet

Architectural building blocks of a 3CX AI voice agent:

Programmable Extensions (Alpha) — external app as an extension
Call Control API (GA) — controlling the call
@3cx/call-control-sdk — the official SDK (TypeScript)
PCM 8 kHz 16-bit mono audio, bidirectional
WebSocket connection with automatic reconnect
Service Principal — app ID and secret (appId · appSecret)
Enterprise license at 8SC+ plus CFD access
3CX MCP server — phonebook lookup and contact management
Additional MCP servers — CRM and calendar connections
External AI provider with your own key (BYO key)
The official reference repo agentic-call-control
Alternative: AI Call Scripts on the 3CX server (also Alpha)

05 · Scenarios

Where a custom AI voice agent fits

◆
A voice reception agent greets the caller in Arabic, understands intent, answers frequent questions, then hands off to the right department — as an evaluation build today, production once the feature matures.
◆
A bookings or appointments line that talks to the caller by voice, checks availability via a calendar connection, and confirms the slot or transfers complex cases to a person.
◆
Inbound or outbound call screening that gathers initial details (order number, enquiry type) before transfer, so the caller reaches an agent with context ready.
◆
A lead-qualification agent that speaks with the caller, logs the enquiry in the CRM via an MCP server, then routes qualified leads to sales.
◆
An after-hours line that handles simple enquiries by voice and leaves structured messages or creates tickets for cases needing human follow-up.
◆
A multilingual agent serving callers in Arabic and English through a real-time-capable AI provider, with seamless handoff between agent and staff.
◆
A proof-of-concept to measure audio quality, latency and comprehension accuracy before any decision to scale or move to production.

06 · Architecture

How an external AI app connects to 3CX

The officially-recommended path for custom agents is an external Programmable Extension: a call reaches the 3CX PBX, then a control channel opens over a WebSocket to an orchestrator that runs on your own infrastructure. The orchestrator uses @3cx/call-control-sdk to join the call and read and write PCM audio in both directions. For setup, a Service Principal is created from the admin console (Admin → Integrations → API), giving you an appId, an appSecret and a pbxBase.

The orchestrator passes audio to an external AI provider over a single real-time stream; the provider handles speech understanding, reasoning and voice generation, then returns audio to the caller through 3CX. 3CX officially documents four providers for this pattern via its agentic-call-control reference repository: OpenAI Realtime API, Google Gemini Live API, xAI Grok, and Alibaba Qwen Omni Realtime. All are developer-built-via-API with your own key — no other provider may be presented as official.

During a call the agent can invoke local tools (transfer · drop · screen), look up the phonebook via the 3CX MCP server, and connect additional systems (CRM · calendar) via other MCP servers. There is also an alternative path, AI Call Scripts, which runs on the 3CX server itself and connects to supported OpenAI, Gemini and xAI voice services — this is likewise Alpha within Update 10 and requires the AI Edition. What is native to 3CX here: telephony, routing, transfers, SIP trunks, DIDs and the Call Control API. The agent logic and the AI are external development and the provider’s work.

Caller → 3CX PBX → WebSocket control channel → orchestrator on your infrastructure.
Orchestrator → provider bridge (OpenAI · Gemini · Grok · Qwen) with your own key.
Call tools: transfer · drop · screen + 3CX MCP server (phonebook) + additional MCP servers (CRM · calendar).
Native to 3CX: telephony, routing, SIP, DIDs and the Call Control API — not the AI itself.

07 · Security, scalability & production

Security, scalability and production considerations — honestly, no guarantees

Because the application runs outside 3CX on your infrastructure, its security is your responsibility and your implementation partner’s: protecting the appSecret and provider keys, isolating the orchestrator environment, securing the control channel, and scoping permissions at the Service Principal level and the transfers allowed. When the 3CX MCP server is used for phonebook lookup, the permissions of the authorizing 3CX user’s role are respected and role-based access controls apply. We design these layers within sound operating practices — with no claim of absolute security or privacy.

Privacy and data residency are central: call audio passes through an external AI provider (with its own account, key, billing and release status), and some providers are region-locked for their access endpoints. These options, their locations and data flows are confirmed during solution design, subject to your policies — and we make no compliance guarantee; we provide tools and practices that support your governance efforts.

On production and scalability: Programmable Extensions is still Alpha, so we do not recommend it for critical production loads today, and we treat it as an evaluation and proof-of-concept environment with continuous monitoring of audio quality, latency and stability. Scalability depends on license capacity (SC), orchestrator resources and the AI provider’s limits — measured and confirmed during technical evaluation, not assumed in advance. When the feature reaches a stable release, we move the solution to production on a tested architecture.

08 · Why ECOLOR

Why ECOLOR builds and supports these solutions

Building a 3CX AI voice agent is engineering work — not a one-click setup:

Real architecture and developmentWe design and build the orchestrator with the official @3cx/call-control-sdk, and wire in the AI provider, call tools and MCP servers — with genuine 3CX engineering depth, not just configuration.
Integration, testing and monitoringWe integrate systems (CRM · calendar), test audio quality, latency and comprehension, and monitor stability — a proof-of-concept methodology before any decision to scale.
Release-status disciplineWe keep Programmable Extensions (Alpha) clearly distinct from the Call Control API (GA), so we never promise you production on an Alpha feature, and we set out a realistic path to production.
Tied to ECOLOR’s own solutionsWe connect these capabilities to ECOLOR’s AI Voice Agent and AutoConnect platform — both ECOLOR-developed on top of 3CX, not native 3CX features — and keep supporting them.

Considering a 3CX AI voice agent? Let us design an evaluation environment today and map the path to production together.

Book a consultation

09 · FAQ

Programmable Extensions and AI voice agents — FAQ

What are Programmable Extensions in 3CX, and what is their status?

They are an official 3CX feature that lets an external app on your infrastructure behave like a native extension: joining calls, exchanging audio both ways and controlling routing. Their status is Alpha within V20 Update 10 — for testing and evaluation only, not for production.

What is the Call Control API, and is it also in Alpha?

No. The Call Control API is the mature developer surface for controlling calls (answer · route · transfer · drop · monitor), generally available (GA) since V18 with the official @3cx/call-control-sdk. Programmable Extensions (Alpha) build on top of this stable surface — the distinction between them is fundamental.

Which AI voice providers are official with 3CX?

3CX officially documents four providers via its agentic-call-control reference repository: OpenAI Realtime, Google Gemini Live, xAI Grok, and Alibaba Qwen Omni. All are developer-built-via-API with your own key. We do not present any other provider as official.

Is the custom voice agent a native 3CX agent?

No. The custom agent is external development on top of 3CX: 3CX provides telephony, routing and the control surface, while speech understanding, reasoning and voice generation come from an external provider with your key. Any agent ECOLOR builds this way is not a native 3CX feature, and we do not represent it as one.

What license and requirements are needed?

The Call Control API requires an Enterprise license at 8SC or above with CFD access, and a Service Principal is created to obtain the appId and appSecret. The voice-agent path additionally needs the Update 10 feature set and an external AI provider key. Details are confirmed during technical evaluation.

Is this production-ready today?

Programmable Extensions is still Alpha, so we do not recommend it for critical production loads now. We can build an evaluation and proof-of-concept environment today, measure performance and prepare the architecture, then move to production once the feature reaches a stable release — with no production guarantees on an Alpha stage.

How does ECOLOR help specifically?

We design the architecture and develop the orchestrator with the official SDK, wire in the AI provider, call tools, MCP servers and systems, test and monitor audio quality and latency, and provide support. Where useful, we also connect it to ECOLOR’s AI Voice Agent and AutoConnect platform.

What is the difference between this path and AI Call Scripts?

AI Call Scripts is an alternative that runs on the 3CX server itself and connects to supported voice services (OpenAI · Gemini · xAI); it is also Alpha within Update 10 and requires the AI Edition. An external Programmable Extension runs on your infrastructure and gives deeper control of the agent logic — we help you choose the right fit for your case.

A 3CX AI voice agent — built honestly, on sound architecture

From the Service Principal setup and the official @3cx/call-control-sdk, to connecting an external AI provider, call tools and MCP servers, ECOLOR Technologies designs, develops, integrates, tests, monitors and supports custom voice agents on 3CX — with a clear separation between Programmable Extensions (Alpha) and the Call Control API (GA), and no production guarantees on anything still in Alpha.