CX Voice Onboarding Guide (Complete)

ExpertFlow CX Voice — New Team Member Onboarding Guide

Purpose: This document explains every major component of the CX Voice platform, why it exists, and how the pieces interact. It is designed for engineers who are new to the team and need to understand the full stack from the media server up to the routing engine.

Last Updated: 2026-06-01 (Major expansion: component push matrix, config precedence, CIM field reference, complete recording architecture with SIPREC, EFSWITCH/ELEVEO backends, encryption, and retrieval flow)

Table of Contents

1. The Big Picture

2. FreeSWITCH — The Media Server

3. Voice Connector — The Bridge

   • Voice Connector Configuration

   • How tenantId Is Resolved

4. CCM (Routing Engine) — The Brain

   • How Voice Conversations Are Created in CX

   • What Every Component Pushes to CX

5. Dialplans & Call Flows

6. Outbound Dialer & Voice Connector Integration

   • What is the Outbound Dialer?

   • Dialer Architecture

   • Dialer Database Schema

   • Dialer Configuration

   • Dialer REST API

   • Dialer ↔ FreeSWITCH ESL

   • Dialer ↔ Voice Connector

   • Campaign Types: IVR vs AGENT

   • Progressive Dialing

   • Predictive Dialing

   • Voice Connector Outbound Flow

   • Campaign Lifecycle Summary

7. Unified Agent — The Agent Desktop

   • What is the Unified Agent?

   • Voice Configuration

   • Architecture & Key Services

   • Normal Inbound Call Workflow

   • Outbound Call Workflow (Agent-Initiated)

   • Outbound Campaign Workflow

   • Cisco Finesse Integration

   • Call Controls & Actions

   • CIM Event Generation

   • Socket Event Handling

8. Recording Architecture

   • Recording Retrieval Architecture

   • EFSWITCH vs ELEVEO Recording Backends

   • SIPREC-Based Recording

   • Recording Encryption

   • Recording Configuration Reference

9. RONA & Voicemail Deep Dive

10. Component Interaction Map

11. Key Code Locations

12. Complete CIM Message Field Reference

13. Glossary

1. The Big Picture

CX Voice is ExpertFlow's contact-center voice solution. At its core, it connects customers calling from the PSTN (or WebRTC) to agents sitting in front of the CX desktop application. Three systems make this possible:

Why three systems instead of one?

• FreeSWITCH is the best open-source soft-switch for SIP/RTP but knows nothing about our routing logic.

• CCM knows everything about queues, skills, agents, and conversations but knows nothing about SIP.

• The Voice Connector exists because we need a stable, long-lived ESL connection to FreeSWITCH. ESL (Event Socket Library) is FreeSWITCH's native TCP protocol. If we let CCM talk directly to FreeSWITCH, every CCM instance would need its own ESL connection, and failover/reconnection would be fragile. The Voice Connector centralizes this.

2. FreeSWITCH — The Media Server

2.1 What is FreeSWITCH?

FreeSWITCH is an open-source soft-switch (think of it as a programmable telephone exchange). It speaks SIP to carriers, handles the actual audio streams (RTP), and executes Lua scripts that decide what happens to a call.

2.2 ESL (Event Socket Library)

ESL is FreeSWITCH's TCP control channel. The Voice Connector opens an inbound ESL connection to each FreeSWITCH instance. Through ESL we can:

• Transfer calls (uuid_transfer)

• Set channel variables (uuid_setvar / uuid_setvar_multi)

• Play files / record sessions (uuid_broadcast)

• Schedule hangups (sched_hangup)

Key ESL commands we use:

2.3 Lua Scripts

All call logic is written in Lua scripts deployed to /usr/share/freeswitch/scripts/ on the media server.

2.4 Dialplans

Dialplans are XML configurations that tell FreeSWITCH "when a call arrives for number X, execute actions Y." They are not in the freeswitch-scripts repo; they are deployed separately per tenant.

Key dialplan concepts:

• A call arrives on a DID (e.g., +1-800-555-0199).

• The dialplan matches the destination_number and routes it to lua cxIvr.lua.

• When the Voice Connector transfers a call to an agent extension (e.g., 1001), the dialplan matches ^1001$ and bridges to the registered SIP endpoint for that agent.

• The agent extension dialplan sets originate_timeout (typically 30 seconds) — this is the RONA timeout.

Important number prefixes (hard-coded in scripts):

3. Voice Connector — The Bridge

Repository: ecx_generic_connector
Technology: Spring Boot 3.4.10, Maven, Java
Key Responsibility: Own the ESL connection to FreeSWITCH and translate between FreeSWITCH events and CCM CIM messages.

3.1 Architecture

The Voice Connector is a small, stateless Spring Boot service. It exposes REST endpoints that FreeSWITCH Lua scripts call, and it receives CIM messages from CCM via a POST endpoint.

3.2 Endpoints

3.3 Key Java Classes

VcService.java

The heart of the Voice Connector.

• requestAgent(CallDetails) — Receives call details from FreeSWITCH, builds an ASSIGN_RESOURCE_REQUESTED CIM message, and POSTs it to CCM. Includes voicemail metadata (isVoiceMailEnable, agent_extension, DID_number) if present.

• routeAgent(...) — Receives AGENT_RESERVED or NO_AGENT_AVAILABLE from CCM and decides what to do: INBOUND / DIRECT_TRANSFER → handleAgentForInbound() uses ESL uuid_transfer to move the parked customer call to the agent. OUTBOUND → handleAgentForOutbound() POSTs agent details to the Dialer API.

• handleAgentForInbound(...) — Sets queue headers via uuid_setvar_multi, then transfers the call. If agentExtension is empty, plays "no agent available" and hangs up after 6 seconds.

• sendSyncEslCommand(...) — Sends synchronous ESL commands through a static Client inboundClient.

OutboundController.java

Receives CIM messages from CCM on /ccm-msg/receive/cim-messages.

• VOICE type → saves contact to dialer (vcService.saveContact())

• NOTIFICATION type → handles AGENT_RESERVED and NO_AGENT_AVAILABLE AGENT_RESERVED + voicemail enabled → voicemailService.setVoicemailContext() then normal routing NO_AGENT_AVAILABLE + voicemail enabled → voicemailService.handleVoicemail() (redirect immediately)

VoicemailService.java

Independent voicemail logic with its own ESL client (to avoid interfering with VcService's connection).

• isVoicemailEnabled(CimMessage) — Case-insensitive check for isvoicemailenabled in CCM metadata.

• setVoicemailContext(CimMessage) — Called on AGENT_RESERVED. Sets two channel variables on FreeSWITCH: voicemail_dn — the destination number to transfer to if RONA happens voicemail_agent_extension — the agent's extension (for voicemail metadata)

• handleVoicemail(CimMessage) — Called on NO_AGENT_AVAILABLE. Immediately transfers the call to the voicemail DN via ESL.

• extractAgentIdentifier(...) — Priority: agent_extension → DID_number → hardcoded "1002".

CallDetails.java

DTO that FreeSWITCH sends to /request-agent.

Contains AdditionalDetails with:

• agentExtension — for Extension-based voicemail

• isVoiceMailEnable — boolean flag

• DID_number — for DID-based voicemail

3.4 Authentication

The Voice Connector can authenticate with CCM using Keycloak tokens. Tokens are cached per tenant domain and refreshed on 401.

3.5 Why a Separate ESL Client for Voicemail?

VoicemailService creates its own Client inboundClient = new Client() rather than reusing VcService's static client. This guarantees that voicemail operations never interfere with the main ESL connection. If the main ESL connection is busy or locked, voicemail can still set variables or transfer calls.

3.6 Voice Connector Configuration

The Voice Connector's configuration is entirely application-level (no per-tenant webhooks). All settings are loaded from application.properties or environment variables at startup.

application.properties

GlobalProperties.java

GlobalProperties is a Spring @Component that reads the properties above and builds runtime URLs:

Important: The Voice Connector has no per-tenant webhook configuration. It relies entirely on the tenantid HTTP header (or the FQDN subdomain in the dialer) to resolve which tenant a request belongs to. The rootDomain field is used only to decide whether to construct a SaaS-style URL (https://tenant.domain/...) or use the raw on-prem URL.

3.7 How tenantId Is Resolved in the Voice Connector

The RestRequestInterceptor extracts tenantId from HTTP headers only:

Despite a log message that says "Tenant ID not found in FQDN or headers", there is no FQDN parsing logic in the current interceptor. Every request to the Voice Connector must include the tenantid header. FreeSWITCH scripts set this header on all HTTP POSTs to the Voice Connector.

The tenantId is then used to:

1. Build the per-tenant CCM API URL (for SaaS deployments)

2. Set the tenantid header on outbound HTTP requests to CCM and the Dialer

3. Populate ContactDto.tenantId when sending campaign contacts to the Dialer

4. CCM (Routing Engine) — The Brain

Repository: customer-channel-manager
Technology: Spring Boot, Java, ActiveMQ, Redis, MongoDB
Key Responsibility: Route voice tasks to the right agent based on skills, queues, availability, and business rules.

4.1 How CCM Receives Voice Requests

When the Voice Connector sends ASSIGN_RESOURCE_REQUESTED to CCM, it contains:

This is represented by AssignResourceRequestedDTO.java.

4.2 CCM Events the Voice Connector Cares About

CCM publishes events via JMS / CIM messages. The Voice Connector listens for two specific notification types:

AGENT_RESERVED

AgentReserved.java in CCM receives the event from the routing engine, wraps it in a CimMessage with NotificationType.AGENT_RESERVED, and sends it to the Voice Connector.

The payload contains:

• AgentReservedDto with the reserved agent's details

• TaskMedia in RESERVED state

• The agent's extension from Keycloak attributes (ccUser.keycloakUser.attributes.agentExtension)

• The queue name

What the Voice Connector does:

1. Extracts agentExtension and queueName

2. If voicemail is enabled → calls voicemailService.setVoicemailContext() to set voicemail_dn on FreeSWITCH

3. Calls vcService.routeAgent() → ESL uuid_transfer to the agent

NO_AGENT_AVAILABLE

NoAgentAvailable.java in CCM handles this. It looks up the conversation in Redis, finds the customer's ChannelSession, and sends NO_AGENT_AVAILABLE to the Voice Connector.

What the Voice Connector does:

1. If voicemail is enabled → voicemailService.handleVoicemail() → immediate ESL transfer to voicemail DN

2. Otherwise → routeAgent() with empty agentExtension → FreeSWITCH plays "no agent available" and hangs up after 6 seconds

4.3 Conversation Events (JMS → CIM)

CCM uses JMS (ActiveMQ) internally and converts events to CIM messages for external consumers like the Voice Connector. Key events:

4.4 Reason Codes

VoiceChannelReasonCode.java defines all the reason codes used when a channel session ends:

4.5 How Voice Conversations Are Created in CX

This is the heart of the system. Understanding how a voice call becomes a Conversation in CX, how ChannelSessions are created, and how Activities are tracked is essential for debugging voice issues.

The CX Data Model (Quick Primer)

Inbound Voice Conversation Creation Flow

Key insight: The conversation is created once, when ASSIGN_RESOURCE_REQUESTED arrives. Even if the call is requeued after RONA, the same conversation and channel session are reused. The routing engine just publishes a new FIND_AGENT event.

Outbound Voice Conversation Creation Flow

Outbound Campaign Conversation Creation: For campaign-based outbound (progressive/predictive), the flow is slightly different:

1. Campaign Scheduler creates CIM with START_CONVERSATION or VOICE type

2. CCM creates ChannelSession with Direction.OUTBOUND

3. Voice Connector receives VOICE type → saveContact() → sends to Dialer

4. The Dialer creates the actual call leg; when customer answers, it calls back to Voice Connector

5. When the customer answers (or the phone rings), the Agent Desktop (unified-agent) sends CALL_LEG_STARTED or CALL_ALERTING to CCM

6. CCM updates the existing ChannelSession (doesn't create a new one)

How the Routing Engine Finds an Agent

The routing engine is a separate service that listens to JMS events published by CCM. Here's the sequence:

1. CCM publishes FIND_AGENT event — contains:

   • FindAgentDto with requestType (mode=QUEUE/AGENT, direction=INBOUND/OUTBOUND)

   • queue (type=ID/NAME, value=queue identifier)

   • additionalDetails (callId, metadata like uuid, eslHost)

2. Routing Engine receives FIND_AGENT — creates a Task:

   • Task gets enqueued in the specified queue

   • TaskEnqueued event is published back to CCM

   • TaskEnqueued.java handler sends TASK_ENQUEUED notification to the Voice Connector

3. Routing Engine monitors agent availability — agents publish their state (READY, NOT_READY, etc.)

4. When an agent matches — the routing engine:

   • Reserves the agent

   • Publishes AGENT_RESERVED event to JMS

   • The task state moves from QUEUED → RESERVED

5. If no agent matches within timeout — the routing engine:

   • Publishes NO_AGENT_AVAILABLE event to JMS

   • The task state moves to NO_AGENT_AVAILABLE

6. If agent doesn't answer (RONA) — the Voice Connector sends CANCEL_RESOURCE_REQUESTED:

   • CCM publishes CANCEL_RESOURCE_REQUESTED to JMS

   • Routing Engine cancels the reservation and either: Requeues the task (for queue-based transfers) Marks it as failed (for named transfers)

How Voice Activities Are Created

Activities are timestamped events stored in the Conversation Manager. They represent everything that happened in a conversation. For voice, activities come from multiple sources:

Source 1: IVR Activities (cxIvr.lua / outboundIvr.lua)

When a customer navigates the IVR, FreeSWITCH tracks every menu selection:

On hangup or transfer, the script sends IVR_AGGREGATED_ACTIVITY to CCM:

CCM's MessageProcessor.handleIvrAggregatedActivity() forwards this to the Conversation Manager:

Source 2: Call Results / Delivery Notifications

When a call ends, the Voice Connector (or Dialer) sends a delivery notification to CCM. CCM routes it to the Conversation Manager:

Source 3: Conversation Events

Every CimEvent published by CCM is also stored in the Conversation Manager:

• CHANNEL_SESSION_STARTED — call began

• CHANNEL_SESSION_ENDED — call ended (with reason code)

• AGENT_RESERVED — agent was assigned

• NO_AGENT_AVAILABLE — no agent found

• TASK_ENQUEUED — call entered queue

• CALL_HOLD / CALL_RESUME — agent put customer on hold

• CALL_LEG_STARTED / CALL_LEG_ENDED — for outbound/consult legs

These events are published to JMS and the Conversation Manager persists them as the conversation timeline.

How CCM Sends Notifications Back to the Voice Connector

This is the reverse path — when CCM needs to tell the Voice Connector something (like AGENT_RESERVED), how does the message get there?

Why the webhook URL works: When an admin configures a Voice channel in CX, they set up a ChannelConnector with a ChannelProviderInterface. The provider webhook points to the Voice Connector's ingress URL. This is stored in MongoDB and cached in Redis. CCM reads it from the ChannelSession when sending outbound messages.

Redis Storage for Voice

CCM stores voice state in Redis. Here are the key patterns:

Why Redis?

• Speed: Voice requires sub-second response times

• TTL support: Sessions can auto-expire

• Pub/Sub: JMS events are fast, but Redis provides a local cache

• Resilience: If JMS is down, Redis still has the conversation state

Call Leg Lifecycle: CALL_ALERTING, CALL_LEG_STARTED, CALL_LEG_ENDED

Voice calls are not single events — they have a lifecycle with multiple legs. A "leg" is a single connection endpoint (customer, agent, consult target, conference participant). CCM tracks each leg via three key intents.

CALL_ALERTING — "The Phone is Ringing"

Who sends it:

What it means: The call leg has been created and is alerting (ringing) but has not been answered yet.

CCM processing (MessageProcessor.handleCallAlertingIntent()):

Key difference from ASSIGN_RESOURCE_REQUESTED: CALL_ALERTING creates the ChannelSession before any routing happens. The call exists in CX as a "ringing" session. When the customer answers, CALL_LEG_STARTED follows. For inbound calls, ASSIGN_RESOURCE_REQUESTED is what triggers routing — it happens after the call is already connected to the IVR.

When CALL_ALERTING is used vs ASSIGN_RESOURCE_REQUESTED:

CALL_LEG_STARTED — "Someone Answered"

Who sends it:

What it means: The call leg has transitioned from ringing to active. Someone picked up the phone.

CCM processing (MessageProcessor.handleCallLegStartedIntent()):

This method is nearly identical to handleCallAlertingIntent():

Why nearly identical? Both intents create a new ChannelSession if one doesn't exist. The difference is purely semantic:

• CALL_ALERTING = "We are trying to reach someone"

• CALL_LEG_STARTED = "Someone answered, the leg is now active"

What the Voice Connector does with these events: The Voice Connector is not involved in CALL_ALERTING or CALL_LEG_STARTED at all. These CIM messages flow directly from the Agent Desktop (or Cisco Connector) to CCM / Conversation Manager. The Voice Connector only handles ASSIGN_RESOURCE_REQUESTED, CANCEL_RESOURCE_REQUESTED, END_CHAT, and IVR_AGGREGATED_ACTIVITY.

CALL_LEG_ENDED — "Someone Hung Up"

When it's sent: This is the most complex of the three. It can come from multiple sources:

FreeSWITCH CALL_LEG_ENDED payload (from scripts):

CCM processing (MessageProcessor.handleCallLegEndedIntent()):

Secondary Ending Reason Codes: These are "helper" events that indicate a sub-leg ended, but the main conversation may continue:

Main Dialog Ending Reason Codes: These indicate the primary customer-facing session is over:

Why the distinction matters: When an agent does a consult transfer, three events happen:

1. CONSULT_ENDED — the consult leg ends (secondary, main call continues)

2. CONSULT_TRANSFER — the transfer completes (secondary, main call continues with new agent)

3. Later: DIALOG_ENDED — the customer finally hangs up (main dialog ends)

If CCM ended the ChannelSession on CONSULT_ENDED, the new agent would lose the conversation context. The session must stay active until DIALOG_ENDED.

CALL_LEG_ENDED for Normal Calls vs Campaign Calls

Normal Inbound Call:

Normal Outbound Call (Agent-Initiated):

Progressive Campaign Call:

Predictive Campaign Call:

Consult Call:

Summary: Which Intent Creates What Activity?

4.6 What Every Component Pushes to CX — Complete Component Matrix

This section documents exactly what data each component in the voice stack sends to CX (CCM or Conversation Manager), including the HTTP endpoint, the CIM intent, and the payload structure. This is the authoritative reference for debugging "who sent what to whom."

4.6.1 FreeSWITCH Scripts → CCM

FreeSWITCH Lua scripts send CIM messages directly to CCM's /ccm/message/receive endpoint. They bypass the Voice Connector.

FreeSWITCH → CCM Authentication: Scripts use auth_token.lua to fetch a Keycloak bearer token from {cxFqdn}/unified-admin/keycloakLogin (if auth_enabled is true in the tenant env file). The token is cached per tenant.

4.6.2 FreeSWITCH Scripts → Voice Connector

These are HTTP POSTs from FreeSWITCH Lua scripts to the Voice Connector's REST API. The Voice Connector then translates them into CIM messages for CCM.

What the Voice Connector does with these:

• /request-agent → builds ASSIGN_RESOURCE_REQUESTED CIM → POSTs to CCM

• /cancel-agent → builds CANCEL_RESOURCE_REQUESTED CIM → POSTs to CCM

4.6.3 Voice Connector → CCM

The Voice Connector sends CIM messages to CCM at POST {ccmApi}/ccm/message/receive.

Voicemail fields in ASSIGN_RESOURCE_REQUESTED: When voicemail is enabled, the Voice Connector adds these to body.additionalDetail:

• isVoiceMailEnable: true — tells CCM that RONA/no-agent should redirect to voicemail

• agent_extension — Extension-based voicemail destination

• DID_number — DID-based voicemail destination

CCM forwards these fields back in the AGENT_RESERVED / NO_AGENT_AVAILABLE notification data.

4.6.4 Voice Connector → Dialer

The Voice Connector sends contacts and agent details to the Dialer via REST.

ContactDto fields (from schedulingMetaData):

4.6.5 Dialer → Voice Connector

The Dialer sends call progress events and agent requests back to the Voice Connector.

CallDetails sent by Dialer:

Note: The Dialer's /cancel-agent endpoint is not implemented. There is no code in the Dialer that sends cancel-agent requests to the Voice Connector.

4.6.6 Agent Desktop → CCM

The Unified Agent (CX Desktop) sends CIM messages directly to CCM. These do not go through the Voice Connector.

4.6.7 Cisco Connector → Conversation Manager

The Cisco Connector (for UCCE/UCCX integrations) sends voice activities directly to the Conversation Manager, bypassing CCM's message processor.

4.6.8 Dialer → External Webhooks

The Dialer sends call progress events to external systems (e.g., campaign management, CRM).

CallProgressEvent payload:

4.6.9 Summary: Who Talks to Whom?

5. Dialplans & Call Flows

5.1 Inbound Call Flow

5.2 Outbound Call Flow

1. CCM creates an outbound contact and sends it to the Voice Connector (VOICE type message).

2. Voice Connector POSTs the contact to the Dialer API (/contact).

3. The Dialer calls the customer via FreeSWITCH.

4. When the customer answers, the Dialer bridges the call to an agent.

5. Agent details are sent from Voice Connector to Dialer (/agent).

5.3 Direct Transfer Flow

An agent wants to transfer a customer to another queue:

1. Agent dials 99887766-SalesQueue from their CX desktop.

2. FreeSWITCH dialplan matches the 99887766 prefix and runs lua customTransfer.lua.

3. customTransfer.lua sets the transfer type and calls session:transfer() to the queue number.

4. The call hits the inbound dialplan for that queue and runs lua vcApi.lua directTransfer.

5. vcApi.lua POSTs to /request-agent with direction=DIRECT_TRANSFER.

6. CCM finds a new agent and sends AGENT_RESERVED.

7. Voice Connector transfers the customer to the new agent.

5.4 Consult Flow

An agent wants to consult with another agent before transferring:

1. Agent dials another extension.

2. FreeSWITCH sets sip_h_X-CallType=CONSULT.

3. The original agent and the consulted agent are bridged.

4. bind_meta_app is set up on DTMF keys: A → consult transfer (consult_conf.lua CONSULT_TRANSFER) C → consult conference (consult_conf.lua CONSULT_CONFERENCE)

5. If the agent presses A, the original agent drops and the customer is bridged to the consulted agent.

5.5 Silent Monitoring Flow

1. Supervisor dials *44{agentExtension}.

2. Dialplan runs lua eavesdrop_custom.lua {agentExtension}.

3. The script queries FreeSWITCH's internal SQLite database (channels table) to find the customer's UUID.

4. It checks call states to ensure neither party is on hold.

5. session:execute("eavesdrop", customerUuid) — supervisor hears the call.

6. DTMF B is bound to lua barge.lua — supervisor can press B to join as a 3rd party.

6. Outbound Dialer & Voice Connector Integration

This section covers the Outbound Dialer (outbound-dialer), the Voice Connector's role in outbound campaigns, and how they work together. The Dialer is a separate Spring Boot service that manages outbound call campaigns. The Voice Connector acts as the bridge between CCM's campaign orchestration and the Dialer.

What you will learn in this section:
- How a contact flows from CCM → Voice Connector → Dialer → FreeSWITCH → Agent
- Which delivery notifications are passed at every stage and what they contain
- How Call Progress Analysis (AMD/CPA) information flows through the system
- The complete contact lifecycle (ingestion, dialing, result tracking, cleanup)
- The exact difference between Progressive and Predictive dialing modes
- How campaigns are divided, scheduled, and managed internally

6.1 What is the Outbound Dialer?

The Outbound Dialer is a Spring Boot 3 application (outbound-dialer) that automates outbound communication. It sits between CCM and FreeSWITCH:

• Receives contacts from the Voice Connector (which got them from CCM)

• Stores contacts in a PostgreSQL database

• Dials contacts via FreeSWITCH ESL (Event Socket Library)

• Tracks call results (answered, busy, no answer, failed, machine detected)

• Manages campaigns (start, stop, purge)

• Supports multi-tenancy — each tenant has its own call configuration

Tech Stack:
| Component | Technology |
|-----------|------------|
| Framework | Spring Boot 3 |
| Database | PostgreSQL (contacts table) |
| FreeSWITCH Integration | ESL Java Client (esl-client.jar) |
| Build | Maven |

6.2 Dialer Architecture

Key Components:

6.3 Complete Dialer Workflow (End-to-End)

This is the master flow that every outbound contact follows, regardless of campaign type. Study this first; the subsequent sections break down each stage in detail.

6.4 Delivery Notifications — Complete Reference

Delivery notifications are the mechanism by which the Dialer reports call outcomes back to CCM (via the Voice Connector). There are three types of notifications the Dialer sends:

6.4.1 Delivery Notification (/send-delivery-notification)

Sender: DialerService.sendCallResults()
Receiver: Voice Connector InboundController.sendDeliveryNotification()
When: After every call ends (CHANNEL_DESTROY), IF AMD detected HUMAN or no AMD was performed.

Why suppress on machine? If AMD detects an answering machine, the call is considered non-productive. No delivery notification is sent to CCM, but a CallProgressEvent is sent to the external webhook.

Payload:

Common callResult values:

Voice Connector mapping to CCM:

Only NORMAL_CLEARING maps to CONNECTED. Everything else is FAILED.

6.4.2 End Chat (/end-chat)

Sender: DialerService.sendEndChat()
Receiver: Voice Connector InboundController.sendEndChat()
When: Call ends AND the call was an AGENT campaign AND the call was never bridged (no variable_bridge_hangup_cause in CHANNEL_DESTROY headers).

Why? If a call was placed but never connected to an agent (e.g., AMD detected machine, or customer hung up before bridge), CCM needs to know the conversation is over so it can clean up the ChannelSession.

Payload:

Voice Connector action: Builds END_CHAT CIM message and POSTs to CCM.

6.4.3 Call Progress Event (External Webhook)

Sender: DialerService.sendCallEventToWebhook()
Receiver: Customer-provided webhook URL (from schedulingMetadata.callEventsWebhookUrl)
When: After AMD completes (amd::done event), regardless of whether the call was human or machine.

Why? This allows external CRM/campaign systems to track call outcomes in real-time, even for answering machines.

Payload:

Events sent: HUMAN or ANSWERING_MACHINE

6.5 CPA (Call Progress Analysis) / AMD Deep Dive

The Dialer uses FreeSWITCH's built-in AMD (Answering Machine Detection) module for Call Progress Analysis. There is no separate CPA engine in the Java code.

6.5.1 How AMD Is Triggered

AMD is only enabled for AGENT campaigns (not IVR campaigns). The originate command routes the call to the agent_amd dialplan context:

The agent_amd dialplan runs the AMD application before bridging the call.

6.5.2 AMD Event Flow

6.5.3 AMD Result Handling Decision Matrix

Critical logic in hangupCallHandler():

This means:
- If AMD was not run (IVR campaigns, or amdResult is null) → delivery notification IS sent.
- If AMD detected HUMAN → delivery notification IS sent.
- If AMD detected MACHINE → delivery notification is NOT sent. Only the external webhook gets the event.

6.6 Contact Lifecycle — What the Dialer Does with Contacts

The contacts table is the heart of the Dialer. Every contact goes through a well-defined state machine.

6.6.1 Contact States

6.6.2 State Machine Diagram

6.6.3 Duplicate Contact Prevention

A customer can only have one active contact per tenant at any time:

If a duplicate arrives:
- DialerController.receiveContact() returns 406 NOT_ACCEPTABLE
- Log message: "CONTACT {number} ALREADY EXISTS WITH CALL IN PROGRESS"

6.6.4 Contact Retrieval & Fair Campaign Division

For predictive dialing, contacts are retrieved in batches by the retrieveContacts() method (currently invoked manually or externally; the @Scheduled annotation is commented out).

Per-tenant flow:

campaignDivision() — Fair Allocation Algorithm:

This ensures equal weightage across campaigns. If one campaign has 1000 contacts and another has 10, both get the same number of dial slots in each batch.

Round-robin retrieval when slots < campaigns:

This query picks the oldest pending contact from EACH campaign, then orders them by received_time. It guarantees no campaign starves.

6.6.5 Stale Contact Cleanup

Every 10 minutes, clearOldContactsForAllTenants() runs:

Why? If a call is stuck in dialed or agent_pending for longer than maxCallTime minutes (e.g., FreeSWITCH crashed, ESL event was lost), the contact is reset to pending so it can be retried.

6.7 Campaign Architecture Deep Dive

6.7.1 Campaign Data Model

There is no separate campaigns table. Campaigns are implicitly defined by the campaignId field on ContactEntity.

This design means:
- Campaigns are created simply by sending contacts with the same campaignId
- Campaign "size" is dynamic (changes as contacts are added/dialed)
- Campaign lifecycle is managed entirely through contact status updates

6.7.2 Campaign Control API

Note: purge only deletes pending contacts. Contacts that are already dialed, ended, or failed are preserved for reporting.

6.7.3 Campaign Lifecycle

6.7.4 Multi-Tenancy & Campaign Isolation

Every contact query includes tenant_id = ?. This ensures:
- Campaign IDs from different tenants never collide
- Call counters are per-tenant (ConcurrentHashMap<String, AtomicInteger>)
- Gateway checks are per-tenant (same gateway UUID might be used by multiple tenants)
- Throttling is per-tenant (callsPerSecond from tenant config)

6.8 Progressive vs Predictive Dialing — Detailed Comparison

The Dialer supports two dialing modes via ContactDto.dialingMode. Both modes use AMD and agent bridging, but they differ in when and how calls are placed.

6.8.1 Progressive Dialing

Core principle: One contact is dialed at a time, immediately upon receipt.

Flow:

Key characteristics:
- dialAgentAmd() is called synchronously inside saveContact()
- The customer is called before an agent is reserved
- If no agent is available, the call result is NO_AGENT_AVAILABLE
- Uses callsPerSecond throttling via sendOriginateCommand()

6.8.2 Predictive Dialing

Core principle: Multiple contacts are batched and dialed simultaneously by a scheduled task. Agents are reserved before the customer is bridged.

Flow:

Key characteristics:
- retrieveContacts() is designed to run on a schedule (currently @Scheduled is commented out; invoked externally)
- Multiple calls are placed simultaneously up to maxConcurrentCalls
- Agent is reserved before the customer call is originated with agent extension
- If NO_AGENT_AVAILABLE, the contact gets call_result = "NO_AGENT_AVAILABLE" and END_CHAT is sent

6.8.3 Critical Difference: When Is the Customer Called?

Important: The dialingMode value is passed as a SIP header (X-CallType) to FreeSWITCH. The actual behavioral difference (progressive vs predictive) is primarily in when sendAgentRequest() is called relative to dialAgentAmd(). In the current codebase, both modes call dialAgentAmd() immediately in saveContact(), but predictive mode additionally uses retrieveContacts() for batching.

6.9 Dialer ↔ FreeSWITCH ESL Interaction

The dialer connects to FreeSWITCH via the ESL inbound client (esl-client.jar).

6.9.1 ESL Connection Lifecycle

Subscribed Events:
- CHANNEL_DESTROY — Fires when a call channel is destroyed (call ended)
- GENERAL — Used for AMD events (amd::done)

6.9.2 Originate Command Format

IVR-based campaign:

Agent-based campaign (with AMD):

Agent-based campaign (after agent reserved):

6.9.3 Call Pacing & Throttling

This ensures the dialer never exceeds callsPerSecond originate commands per second.

6.9.4 ESL Event Handlers

CHANNEL_DESTROY → hangupCallHandler():
1. Extract Unique-ID (call UUID) and variable_domain_name (tenant)
2. Verify contact exists in DB (checkContactExistsWithId)
3. Decrement tenant call counter
4. Get variable_hangup_cause (call result)
5. Special case: NORMAL_CLEARING + Caller-Channel-Answered-Time == 0 → NO_ANSWER
6. Update DB: status = 'ended', call_result = <hangup_cause>
7. If AMD result is HUMAN (or null), send call results to Voice Connector
8. If sip_h_X-CallType exists and no bridge_hangup_cause, send END_CHAT

GENERAL (amd::done) → amdResultHandler():
1. Extract variable_amd_result
2. If not HUMAN, set to ANSWERING_MACHINE
3. Send call event to webhook URL (from schedulingMetadata.callEventsWebhookUrl)

6.10 Dialer ↔ Voice Connector Interaction

6.10.1 Voice Connector → Dialer

6.10.2 Dialer → Voice Connector

Voice Connector forwards to CCM:
- /request-agent → ASSIGN_RESOURCE_REQUESTED CIM message → CCM
- /send-delivery-notification → DeliveryNotification CIM message → CCM
- /end-chat → END_CHAT CIM message → CCM

6.11 Dialer Database Schema

The dialer uses a single PostgreSQL table: contacts

6.12 Dialer Configuration

6.12.1 Environment Variables

6.12.2 Per-Tenant Dynamic Configuration

The dialer supports multi-tenant operation via webhooks from Unified Admin:

Webhook: POST /webhooks/tenants/created

Stored in-memory: DialerApplication.settings.tenantDialerConfigs[tenantId] = CallConfigs

Webhook: POST /webhooks/tenants/deleted
Removes the tenant's dialer config from memory.

Tenant Bootstrapper (TenantBootstrapper.java):
- On startup, fetches all tenants from CX_TENANT_URL
- Parses dialer config for each tenant
- Populates settings.tenantDialerConfigs

6.12.3 Configuration Precedence

Which one wins? Tenant-level always takes precedence. In fact, the application-level values for most dialer-specific settings (serviceIdentifier, maxConcurrentCalls, callsPerSecond, maxCallTime) are effectively dead code — the code always reads from tenantDialerConfigs.

Exception: ESL connection settings (esl.ip, esl.port, esl.pass), Voice Connector URL, and default IVR are global application-level only.

6.13 Campaign Lifecycle Summary

6.14 Why a Separate Dialer?

FreeSWITCH can originate calls, but it doesn't do:
- Call pacing algorithms (callsPerSecond throttling)
- Multi-tenant call slot management (maxConcurrentCalls per tenant)
- Contact list persistence and state tracking
- Campaign management (start/stop/purge)
- Fair call allocation across multiple campaigns
- AMD (Answering Machine Detection) result handling
- Automatic retry of stale contacts (clearOldContactsForAllTenants)
- Gateway health checking before each call
- Delivery notification routing to CCM

The Dialer provides:
- A persistent queue of contacts (PostgreSQL)
- Call pacing (throttle to N calls per second)
- Tenant isolation (separate counters and configs per tenant)
- Campaign fairness (equal allocation of call slots across campaigns)
- Stale contact cleanup (auto-reset contacts stuck for > maxCallTime)
- Gateway validation (check gateway UP before every originate)
- AMD integration (detect machines, route humans to agents)
- Call result tracking (hangup causes, delivery notifications)
- External webhook integration (CRM call progress events)

FreeSWITCH is the "dumb pipe" that places the actual SIP calls. The Dialer is the "smart brain" that decides when, who, and how fast to call.

7. Unified Agent — The Agent Desktop

The Unified Agent (unified-agent) is the Angular-based desktop application that agents use to handle customer interactions. For voice, it is the source of CALL_ALERTING, CALL_LEG_STARTED, and CALL_LEG_ENDED events — it detects call state changes from the SIP stack (or Cisco Finesse CTI) and sends CIM messages directly to CCM.

7.1 What is the Unified Agent?

The Unified Agent is an Angular 8+ single-page application that serves as the agent's primary interface. It supports multiple channels (chat, email, voice, social) but for voice specifically, it provides:

• Call control UI — answer, hangup, hold, mute, transfer, consult, conference

• SIP/WebRTC phone — registers as a SIP endpoint via WebSocket

• Cisco Finesse integration — alternative CTI mode for Cisco UCCE/UCCX environments

• Customer identification — resolves caller ID to customer record via CIM Customer API

• Real-time event stream — receives tasks, channel sessions, and CIM events via WebSocket

• Call timers & recording controls — visual indicators for hold time, talk time, recording status

Voice modes: The agent desktop supports three voice backends:

Note: isCxVoiceEnabled and isCiscoEnabled are mutually exclusive — only one voice mode is active per deployment.

7.2 Voice Configuration

Voice settings are loaded from src/assets/config.json at runtime:

Key Voice Configuration Fields:

7.3 Architecture & Key Services

Key Services:

7.4 Normal Inbound Call Workflow

This describes the CX Voice (SIP) inbound call flow through the agent desktop:

Key Methods in SipService:

Customer Identification Flow:

Call Type Assignment (Inbound):

7.5 Outbound Call Workflow (Agent-Initiated)

Agents can make manual outbound calls from the desktop:

Key Methods:

Manual Outbound CIM Message:

7.6 Outbound Campaign Workflow

For campaign calls (progressive/predictive), the agent desktop receives calls that were initiated by the Dialer:

Campaign vs Manual Outbound:

7.7 Cisco Finesse Integration

In Cisco-mode (isCiscoEnabled: true), the agent desktop uses FinesseService instead of SipService. It communicates with Cisco Finesse via the Finesse REST API and XMPP (BOSH).

Architecture:

Key Differences from SIP Mode:

Finesse Call Type Detection:

Finesse-Specific Call Types:

State Synchronization:

7.8 Call Controls & Actions

The CallControlsComponent provides the UI for voice call actions. It works with both SipService and FinesseService.

Available Actions:

Transfer/Consult Number Prefixes (config-driven):

7.9 CIM Event Generation

The Unified Agent is the source of the three call leg lifecycle events. Both SipService and FinesseService use the same createCIMMessage() pattern.

createCIMMessage() Structure

CCM API Call

Summary of CIM Events Sent:

7.10 Socket Event Handling

SocketService maintains a WebSocket connection to the CX backend and handles voice-related events:

Events Received:

Voice Channel Detection:

CX_VOICE MRD State Management:

8. Recording Architecture

Recording in CX Voice is event-based, not always-on. This means we do not record the IVR, hold music, or ringing — we only record when the customer and agent are actually bridged together. This saves storage and ensures compliance (you don't want to record a customer saying their credit card number to an IVR).

8.1 Philosophy: Why Event-Based?

We chose event-based because contact-center regulations often require that recordings contain only the actual agent-customer conversation, with holds excluded.

8.2 FreeSWITCH Events That Drive Recording

FreeSWITCH fires events for every significant call state change. We hook into three specific events:

These are not run as dialplan actions — they are registered as event hooks in the FreeSWITCH configuration (e.g., via switch.conf.xml or the dialplan's lua action with event bindings).

8.3 The Recording Lifecycle by Script

Step 1: set_recording_name.lua — Preparation Before Bridge

This script runs before a call is bridged. It sets up the recording filename and command as channel variables so that channel_bridge.lua knows what to do when the bridge happens.

Key behaviors:

• For CONSULT calls: stops any existing recording, generates a new filename using the channel UUID

• For MONITOR calls: explicitly returns — no recording for silent monitoring

• For OUTBOUND calls: uses the customer leg UUID as the filename to keep both legs aligned

• For INBOUND calls: uses the channel UUID; if a file already exists, appends _1, _2, etc. to avoid collisions

Why nolocal:execute_on_answer? This is a FreeSWITCH channel variable prefix that tells FreeSWITCH: "when this leg answers, execute the record_session application." It ensures recording starts at the exact moment the bridge is established.

Step 2: channel_bridge.lua — Recording Starts

This is the most important recording script. It fires on every CHANNEL_BRIDGE event and determines what kind of call this is and who is the agent vs customer.

Call type detection logic:

Recording filename generation:

Example: abc-123-xyz:1005:+18005550199:1717234567.wav

Starting the recording:

Why broadcast twice? The first uuid_broadcast starts recording immediately. The sched_api +2 schedules a second broadcast 2 seconds later as a safety net — if the first one missed due to a race condition, the second one catches it.

Codec renegotiation for outbound: For manual outbound calls, channel_bridge.lua explicitly renegotiates the codec between the two legs to ensure both sides use the same codec. This prevents recording corruption.

Step 3: channel_state.lua — Hold / Resume

When an agent presses the "Hold" button on their phone, FreeSWITCH fires a CHANNEL_CALLSTATE event with state HELD. When they resume, it fires UNHELD.

Why check the other leg? In a 3-way conference or when both parties are on hold, we don't want to resume recording until both legs are unheld.

Step 4: channel_unbridge.lua — Stop Recording

When the call ends (agent hangs up, customer hangs up, or transfer happens), FreeSWITCH fires CHANNEL_UNBRIDGE.

The recording_filename variable is cleared so that if the channel is reused (rare but possible), it won't accidentally continue recording under the old filename.

Step 5: consult_conf.lua — Recording During Consult

When a consult transfer or consult conference happens, the original agent (A1) is replaced by a new agent (A2). The recording needs to handle this transition.

startNewRecording(uuid, agent, startTime, record_path):

• Generates a new filename using the original c1DialogId (customer's call ID), the new agent's extension, and the customer's number

• Sets the recording_filename variable on the new agent's channel

• Starts recording via uuid_broadcast record_session

getA1C1recording(uuid):

• For external consult conference: retrieves the existing recording filename from the A1-C1 call

• Resumes the same recording file after the external consultant joins the conference

• This ensures the recording is continuous even as conference members change

Consult transfer behavior:

8.4 Recording Per Call Type

8.5 File Storage & Permissions

Recordings are stored on the FreeSWITCH media server at:

The record_path channel variable is set in the dialplan and determines the subdirectory.

Permissions:

This is done in both channel_state.lua and channel_unbridge.lua to ensure the recording middleware and uploader containers (which may run as different users) can read the files.

8.6 Recording Retrieval Architecture

Recording is a two-phase process in CX Voice:

1. Creation Phase: FreeSWITCH writes audio files to disk (event-based, as described above).

2. Retrieval Phase: CX needs to play those recordings back in the agent/supervisor desktop.

Three services participate in the retrieval phase:

8.6.1 Overview: How Recordings Get to the Agent Desktop

Why two separate services?

• recording-middleware is a stateless file server — it only knows how to find and return a file given a legId.

• recording-link-activities is a batch matcher — it correlates CX conversation data with recording files and pushes the link. This is done asynchronously because recording files may not be immediately available after a call ends (file flush, network latency, third-party platform delay).

8.6.2 recording-middleware — Recording File Server

Repository: recording-middleware
Framework: Spring Boot 3.4.5, Java 17
Type: Web application (REST API)

The middleware is a read-only recording retrieval proxy. It does not initiate, control, or stream recordings in real time. Its sole purpose is to expose a single HTTP endpoint that returns call recording audio files from one of two backends.

Endpoint:

The legId format:

Example: abc-123-xyz:1005:+18005550199:1717234567.wav

The middleware splits the legId on the last three colons to extract:

1. dialogId — the SIP Call-ID / conversation identifier

2. agentExtension — the agent's extension

3. customerNumber — the customer's ANI

4. startTime — the call start timestamp (used for closest-match lookup)

Backend Selection (Strategy Pattern):

The concrete implementation is selected at runtime by Spring's @ConditionalOnProperty:

EFSWITCH Backend (EfswitchRecordingService)

How it finds a recording:

1. Parse legId → extract dialogId, agent, ani, cxLegStartTime

2. Query FusionPBX DB (v_xml_cdr table):SELECT record_path, json->'variables'->>'sip_h_X-CALL-ID' as call_id, json->'variables'->>'record_path' as path FROM v_xml_cdr WHERE insert_date > '${timeLimit}' AND ((json->'variables'->>'sip_h_X-CALL-ID' in ('${dialogId}','${encodedDialogId}')) OR (sip_call_id in ('${dialogId}','${encodedDialogId}')) OR (xml_cdr_uuid::text in ('${dialogId}','${encodedDialogId}')));

3. Scan filesystem for files matching dialogId:agent:ani:* in the returned path

4. Find closest match by startTime

5. Return file:

   • If encryption=true → decrypts AES/CFB/NoPadding and returns decrypted file from cache

   • If encryption=false → returns raw FileSystemResource

Encryption:

The encrypted file format: 16-byte IV prefix followed by ciphertext.

Docker volume:

ELEVEO Backend (EleveoRecordingService)

How it finds a recording:

1. Authenticate with Eleveo: POST {eleveo.url}/callrec/loginservlet → JSESSIONID POST {eleveo.url}/enc-fwk-data/api/v2/authenticate → Bearer token

2. Search conversations:POST {eleveo.url}/enc-fwk-data/api/v2/conversations/client-search Body: metadata filter on JTAPI_CISCO_ID = {dialogId}

3. Parse conversation events (METADATA, STARTED_CALL, JOINED_CALL) to build EleveoCallLeg objects

4. Merge fragmented legs caused by: HOLD → mergeHoldEndedLegs() — stitches legs with same agent/extension TRANSFER/RETRIEVE → mergeRetrievedLegs() — stitches retrieved legs CONFERENCE → mergeConferenceLegs() — merges conference participants

5. Download audio:

   • Get download token from /callrec/downloadtoken

   • Download bytes from /callrec/sendcallfile.mp3

   • If multiple leg IDs were merged, concatenates byte arrays into a single audio file

Why leg merging matters: Eleveo treats hold, transfer, and conference as separate call legs. The CX desktop expects a single continuous recording per conversation. The middleware reconstructs the full conversation by concatenating fragments.

8.6.3 recording-link-activities — Recording Link Uploader

Repository: recording-link-activities
Framework: Spring Boot 3.4.5, Java 17
Type: Non-web application (spring.main.web-application-type=NONE)

This service has no HTTP endpoints. It runs as a batch worker that fires once on startup (@PostConstruct), processes all recordings in its time window, pushes links to CX, and then exits. In production, it is deployed as a Kubernetes CronJob or a Docker container with restart: always.

Execution trigger:

Core flow (both backends):

1. Calculate time window

   • Reads lastPushedTime from MongoDB pushingCache collection

   • Computes startTime = lastPushedTime, endTime = now - retrievalInterval

   • If interval < 1 minute → aborts (prevents duplicate processing)

2. Fetch CX voice call legs

   GET {cxFqdn}/conversation-manager/activities/voice?startTime=...&endTime=...&limit=500

   Returns all voice call legs within the window.

3. Match recordings (backend-specific)

   EFSWITCH mode:

   • Queries FusionPBX v_xml_cdr and v_domains tables

   • Scans /var/lib/freeswitch/recordings/ for files matching each dialogId

   • Filters by tenant domain (validates local domains against CX Tenant API)

   ELEVEO mode:

   • Authenticates with Eleveo

   • Calls client-search API for each tenant

   • Extracts recording URIs from conversation events

   • Merges hold/transfer legs

4. Build and send VOICE_RECORDING CIM message

   CimMessage recordingLinkPayload = createRecordingLinkPayload(legId, middlewareApi); // intent = "VOICE_RECORDING" // body.legId = legId // body.voiceRecordingUrl = "{middlewareApi}/{legId}/recording-file"

   Sent to:

   POST {cxFqdn}/conversation-manager/activities

5. Update pushingCache in MongoDB with new lastPushedTime

MongoDB pushingCache document:

Authentication with CX APIs:

• Obtains Bearer token from {cxFqdn}/agent-manager/agent/login

• Caches tokens per tenant domain in a ConcurrentHashMap

• Retries on 401

8.6.4 The VOICE_RECORDING CIM Message

When recording-link-activities finds a match, it sends this CIM message to the Conversation Manager:

The Conversation Manager stores this as a MEDIA_RECORDING activity in the conversation timeline. The CX Desktop then renders it as a "Play Recording" button.

Other sources of VOICE_RECORDING / MEDIA_RECORDING:

• Cisco Connector (cisco-connector): Sends VOICE_CALL_RECORDING with Eleveo links

• QM Connector (qm-connector): Sends MEDIA_RECORDING with voice + screen recording URLs

8.7 EFSWITCH vs ELEVEO Recording Backends

CX Voice supports two fundamentally different recording architectures. The choice is made at deployment time via the RECORDING_BACKEND environment variable.

Why two backends?

• EFSWITCH gives CX full control over recording lifecycle (event-based, hold-aware, consult-aware).

• ELEVEO is required when the customer already has a Cisco contact center with existing recording infrastructure. We integrate rather than replace.

8.8 SIPREC-Based Recording

SIPREC (SIP Recording, RFC 6341) is a standard protocol where a network element (typically an SBC — Session Border Controller) forks a copy of the RTP stream to a recording server.

When do we use SIPREC? SIPREC is used in Cisco environments when the customer wants CX Voice to receive recordings, but the actual call is handled by Cisco CUBE (Cisco Unified Border Element). The CUBE forks the RTP stream to our recording infrastructure without affecting the original call path.

Our SIPREC flow:

Drachtio's role:

• Drachtio is a Node.js SIP server that acts as the SIPREC receiver.

• It receives the SIPREC INVITE from the SBC.

• It extracts the SDP (media description) from the INVITE body.

• It stores the SDP in Redis (keyed by call identifier).

• It creates a new SIP INVITE to FreeSWITCH's internal profile on port 5065.

• FreeSWITCH answers the INVITE, receives the forked RTP stream, and records it.

Why SIPREC?

• Vendor-agnostic: Works with Cisco, Avaya, Genesys — any platform that supports SIPREC.

• No PBX changes: The existing PBX/SBC just forks a copy; it doesn't need to know about CX Voice.

• Stereo recording: Both directions of the conversation are in one file, making playback simple.

• Independent: The original call path is unaffected by recording issues.

Important note: The Drachtio server code is not in any of the current repositories. It is a separate Node.js service deployed alongside the media server. If you need to modify SIPREC behavior, you will need access to the Drachtio server repository.

8.9 Recording Filename Format

Collision avoidance: set_recording_name.lua checks if a file already exists and appends _1, _2, etc. This is rare but can happen if a channel UUID is reused quickly.

8.10 Recording Encryption

EFSWITCH recordings support optional AES encryption.

Configuration:

Algorithm: AES/CFB/NoPadding

Key: Hardcoded 64-character hex string in EfswitchRecordingService.java:

File format:

• 16-byte IV prefix

• Remaining bytes = AES/CFB ciphertext

Decryption flow:

1. Middleware reads encrypted file from /var/lib/freeswitch/recordings/

2. Extracts 16-byte IV

3. Decrypts using AES/CFB/NoPadding

4. Writes decrypted file to efs.cache.path

5. Serves decrypted file to the client

6. Cached files are reused on subsequent requests

Security note: The hardcoded key means all recordings in a deployment use the same encryption key. Rotation requires a code change and re-encryption of existing files.

8.11 Recording Configuration Reference

recording-middleware Environment Variables

recording-link-activities Environment Variables

8.12 Recording Summary Table

9. RONA & Voicemail Deep Dive

9.1 What is RONA?

RONA = Ring On No Answer

When CCM reserves an agent and the Voice Connector transfers the call to that agent's extension, FreeSWITCH rings the agent's phone. If the agent does not answer within a timeout window, the call fails with a NO_ANSWER hangup cause. FreeSWITCH then executes the RONA recovery logic.

9.2 How RONA is Triggered

1. Voice Connector receives AGENT_RESERVED.

2. VcService.handleAgentForInbound() sends ESL uuid_transfer <uuid> <agentExt> XML <domain>.

3. FreeSWITCH originates a new B-leg to the agent's SIP endpoint.

4. The agent's dialplan sets originate_timeout (typically 30 seconds — configured per tenant).

5. If the agent answers → CHANNEL_BRIDGE fires → recording starts.

6. If the agent does not answer → B-leg fails with NO_ANSWER.

7. FreeSWITCH falls through in the dialplan to the next action: lua vcApi.lua rona.

8. vcApi.lua (rona branch) runs with the original customer session.

Note on timing: The exact RONA timeout is controlled by originate_timeout in the agent extension's dialplan XML. The default FreeSWITCH value is 60 seconds, but contact-center deployments typically configure it to 30 seconds (or lower, per tenant requirements). This value is set in the dialplan XML, not in the Lua scripts or Java code.

9.3 RONA Recovery Logic (without Voicemail)

From vcApi.lua (rona branch):

1. Reads originate_failed_cause — if it's NO_ANSWER, renames it to RONA.

2. Determines call direction (INBOUND, DIRECT_TRANSFER, CONSULT) and transfer type (NAMED vs QUEUE).

3. NAMED transfer → plays error prompt, sends END_CHAT, hangs up.

4. QUEUE transfer → cancels the agent request via cancel_agent() → requeues the call via request_agent() → plays hold music again.

9.4 RONA + Voicemail Flow (New Feature)

When voicemail is enabled, the flow changes:

Why set variables during AGENT_RESERVED instead of RONA? Because by the time RONA happens, the Voice Connector has already sent the AGENT_RESERVED notification. We need to pre-position the voicemail DN on the FreeSWITCH channel so that the RONA script can act immediately without making another HTTP round-trip to the Voice Connector.

9.5 NO_AGENT_AVAILABLE + Voicemail Flow

If CCM can't find any agent (not even a RONA case):

1. CCM sends NO_AGENT_AVAILABLE.

2. OutboundController checks voicemailService.isVoicemailEnabled().

3. If enabled → voicemailService.handleVoicemail(): Publishes a stub VOICEMAIL_STARTED activity (future: real activity) ESL uuid_transfer to the voicemail DN immediately

4. The customer goes straight to voicemail without ever hearing hold music or ringing.

9.6 Voicemail Metadata

The Voice Connector extracts voicemail metadata from CCM's CimMessage body. It uses case-insensitive key matching because CCM may send keys in any casing:

Agent Identifier Priority:

1. agent_extension (Extension case)

2. DID_number (DID case)

3. Hardcoded "1002" (safety fallback)

10. Component Interaction Map

11. Key Code Locations

Voice Connector (ecx_generic_connector)

Outbound Dialer (outbound-dialer)

Unified Agent (unified-agent)

Recording Middleware (recording-middleware)

Recording Link Activities (recording-link-activities)

CCM (customer-channel-manager)