3CX Programmable Extensions는 외부 서버에서 실행되는 AI 애플리케이션을 3CX의 내선처럼 연결해, AI가 실제 고객 전화를 받고 상담하고 담당자에게 돌려주게 하는 기능입니다. 3CX V20 Update 10과 AI Edition 8SC 라이선스부터 사용할 수 있습니다.
핵심 요약
- 3CX Programmable Extensions란 무엇인가요?
- 3CX 바깥 서버에서 실행되는 애플리케이션이 3CX에 연결해 일반 내선처럼 동작하게 하는 기능입니다. 전화를 받고, 양방향으로 음성을 주고받으며, 3CX Call Control API로 통화를 돌려주거나 종료할 수 있어 실시간 AI 음성 상담원을 만들 때 씁니다.
- 어떤 라이선스가 필요한가요?
- 3CX V20 Update 10과 3CX AI Edition 8SC(동시통화 8개) 이상 라이선스가 필요하며, Call Control API 권한이 있는 Service Principal을 만들어야 합니다.
- 어떤 AI를 연결할 수 있나요?
- 3CX 공식 예제는 OpenAI Realtime, Google Gemini Live, xAI Grok Voice Agent, Alibaba Qwen Omni Realtime을 제공합니다. 실시간 음성 세션 하나에서 음성 인식, 응답 생성, 음성 합성을 함께 처리합니다.
사용 조건 — AI Edition 8SC부터
| 항목 | 조건 |
|---|---|
| 3CX 버전 | V20 Update 10 이상 (2026년 11월 11일 정식 출시) |
| 라이선스 | 3CX AI Edition 8SC(동시통화 8개) 이상, Call Control API 사용 권한 |
| 3CX 설정 | 관리자 계정으로 Call Control API 권한이 있는 Service Principal 생성 |
| 애플리케이션 서버 | Node.js 20 이상이 설치된 외부 서버, 3CX 주소(HTTPS)와 AI 공급자 WebSocket에 접속 가능한 네트워크 |
| AI 공급자 | OpenAI, Google Gemini, xAI Grok, Alibaba Qwen 중 하나 이상의 API 키와 사용 한도 |
1. 어떻게 동작하나요
고객이 전화를 걸면 3CX가 통화를 Programmable Extension으로 넘기고, 외부 애플리케이션이 그 통화를 받아 AI와 실시간으로 대화합니다.
| 구성 요소 | 역할 |
|---|---|
| 3CX | 전화 연결, 통화 라우팅, 내선·SIP 트렁크·대표번호(DID) 관리 |
| 외부 애플리케이션 | 3CX Call Control API와 SDK로 통화를 받고 제어하는 Node.js 앱 (3CX 공식 예제 기반) |
| AI 공급자 | 실시간 음성 세션 하나에서 음성 인식, 응답 생성, 음성 합성을 처리 |
| 3CX MCP | AI가 사용할 수 있는 도구(예: 전화번호부 검색)를 허용 목록 방식으로만 제공 |
| 추가 MCP 서버(선택) | 일정 관리 등 외부 업무 시스템 도구를 추가로 연결 |
2. 할 수 있는 일
- 전화 받기: 내부에서는 Client ID 번호로, 외부에서는 지정한 대표번호(DID)로 걸려온 전화를 받습니다.
- 실시간 음성 상담: 선택한 AI가 고객과 자연스럽게 대화하고, 고객이 말을 끊으면(barge-in) 바로 반응합니다.
- 담당자 찾기·연결: MCP로 3CX 전화번호부를 검색해 담당자를 찾고 통화를 돌려줍니다.
- 음성사서함·종료: 담당자가 부재 중이면 음성사서함으로 보내거나 통화를 종료합니다.
- 업무 시스템 연동: 추가 MCP 서버를 연결해 일정 조회 등 외부 업무 기능을 AI가 쓰도록 할 수 있습니다.
3. 3CX 공식 예제가 지원하는 AI
| AI 공급자 | 예제 폴더 | 필요한 키 |
|---|---|---|
| OpenAI Realtime | examples/openai-realtime | OpenAI API 키 |
| Google Gemini Live | examples/gemini-realtime | Google AI Studio API 키 |
| xAI Grok Voice Agent | examples/xai-realtime | xAI API 키 |
| Alibaba Qwen Omni Realtime | examples/alibaba-qwen-realtime | DashScope API 키 (지역별로 키와 접속 주소가 달라짐) |
예제 소스는 3CX가 GitHub에 공개한 Agentic Call Control 저장소에 있습니다. 모델, 음성, 발화 감지 설정과 공급자별 요금·사용 한도는 각 예제 문서에서 확인합니다.
4. 설정 절차
3CX 관리 콘솔
- 3CX 웹 클라이언트에서 Admin > Integrations > API로 이동해 Add를 누릅니다.
- Client ID를 입력합니다(예:
ai-receptionist). 이 값이 앱의appId가 되고, 내부에서 거는 번호가 됩니다. - 3CX Call Control API 접근을 켭니다.
- 외부 전화를 바로 받으려면 DID(대표번호)를 지정합니다(선택).
- 앱이 감시·제어할 내선을 업무에 필요한 범위로만 지정합니다(선택).
- 저장 후 생성된 API 키(Client Secret)를 바로 복사합니다. 한 번만 표시되며, 앱의
appSecret이 됩니다.
애플리케이션 서버
- Agentic Call Control 저장소를 내려받고, 저장소 최상위에서
yarn install을 실행합니다. - 사용할 AI 예제 폴더의
config.yaml.example을config.yaml로 복사합니다. appId,appSecret,pbxBase(3CX 주소),companyName,agentName,initialGreeting과 AI 공급자 키를 입력합니다.- 예제를 실행합니다(예:
yarn start:openai,yarn start:gemini,yarn start:xai). - 시작 로그에서 3CX 인증, Call Control·WebSocket 연결, 3CX MCP 연결, MCP 도구 로딩이 모두 정상인지 확인합니다.
상담원의 말투, 인사말, 언어, 통화 선별, 연결 전 부재 확인, 연결 금지 내선, 스팸·폭언 대응 같은 세부 동작은 예제의 상담원 프로필(기본 receptionist.yaml)에서 정합니다. 프롬프트에 “할 수 있다”고 적어도 Service Principal에 권한이 없으면 동작하지 않으므로, 프롬프트와 권한을 함께 맞춰야 합니다.
5. 운영 전 시험 항목
- 인사말이 정상적으로 나오는지
- 담당자 이름으로 전화번호부 검색이 되는지
- 통화 돌려주기가 성공하는지, 부재 시 음성사서함으로 넘어가는지
- 고객이 AI 말을 끊고 말할 때 자연스럽게 반응하는지
- 통화 종료가 깔끔하게 처리되는지
- AI 공급자 장애·연결 끊김 시 AI를 거치지 않는 대체 경로(상담원 대기열 등)로 넘어가는지
6. 보안과 개인정보
- 비밀 정보 보호:
config.yaml에는 API 키가 들어 있으므로 외부에 공유하지 말고, 운영 환경에서는 비밀 정보 관리 도구를 사용합니다. 키는 주기적으로 교체합니다. - 최소 권한: Service Principal 권한과 제어 가능한 내선을 업무에 필요한 만큼만 부여합니다.
- AI 도구 제한: AI에는 필요한 MCP 도구만 노출하고, 되돌릴 수 없는 작업에는 승인 절차를 둡니다.
- 개인정보: 통화 음성이 AI 공급자로 전송되므로 공급자의 데이터 처리·보관·지역 정책을 확인하고, 필요한 경우 녹음·AI 응대 사실을 고객에게 고지합니다.
7. 자주 생기는 문제
| 증상 | 확인할 것 |
|---|---|
| 3CX에서 401·403 오류 | appId·appSecret·pbxBase가 Service Principal과 일치하는지, Call Control API 권한과 라이선스가 맞는지 |
| 앱은 켜졌는데 전화가 안 들어옴 | 앱 실행 여부, 올바른 Client ID로 걸었는지, 외부 시험이면 DID가 지정됐는지 |
| 돌려주기·음성사서함 실패 | 대상 내선이 유효하고 Service Principal이 접근할 수 있는지 |
| AI 공급자 연결 거부 | API 키, 결제 상태, 모델 사용 권한, 지역, 사용 한도, WebSocket 연결 |
| 음성 지연·잦은 끊김 | 앱 서버·3CX·AI 공급자 사이의 지연과 패킷 손실, 발화 감지(VAD) 설정 |
8. 다른 AI 방식과 비교
- 3CX 기본 AI 에이전트: 설정만으로 쓰는 AI 리셉셔니스트·상담 에이전트입니다.
- AI Call Scripts: 3CX 서버 안에서 실행되는 맞춤 스크립트입니다.
- Programmable Extensions: 고객이 관리하는 외부 서버에서 실행되어 외부 시스템 연동과 자체 로직 구현이 자유롭습니다.
네 가지 방식의 상세 비교는 AI 도입 방식 비교 페이지를 참고하십시오. 데모 대표번호 070-7919-7915에서 3번을 누르면 Programmable Extensions 방식(1번 Gemini, 2번 Grok)을 직접 체험할 수 있습니다.
자주 묻는 질문
AI Call Scripts와 무엇이 다른가요?
AI Call Scripts는 3CX 서버 안에서 실행되는 맞춤 스크립트이고, Programmable Extensions는 고객이 관리하는 외부 서버에서 실행되는 애플리케이션입니다. 외부 업무 시스템 연동, 자체 로직, 별도 서버 운영이 필요하면 Programmable Extensions가 적합합니다.
AI 공급자에 장애가 나면 통화는 어떻게 되나요?
3CX 문서는 운영 적용 시 시간 초과·재시도 처리와 AI를 거치지 않는 대체 경로(예: 상담원 대기열, 음성사서함)를 반드시 두도록 권장합니다. 컴네트워크는 구축 시 장애·연결 끊김 경로까지 시험합니다.
통화 내용은 어디로 전송되나요?
통화 음성은 애플리케이션을 거쳐 선택한 AI 공급자로 전송됩니다. 공급자의 데이터 처리·보관·지역 정책을 확인하고, 필요하면 녹음·AI 응대 사실을 고객에게 고지해야 합니다.
문의
Programmable Extensions 기반 AI 상담원 구축, 한국어 통화 품질 검증, 국내 번호 연동 상담은 문의 페이지 또는 070-7919-7914로 연락 주십시오.
