CX Voice Recording + Cisco — Complete Architecture Guide

CX Voice Recording Solution — Complete Architecture Guide

---

Table of Contents

1. Executive Summary

2. System Architecture Overview

3. Component Definitions

4. Cisco Integration Layer

5. Complete Normal Inbound Call Flow

6. Complete Normal Outbound Call Flow

7. Complete RONA Flow

8. Transfer, Consult & Conference Flows

9. JTAPI Event Processing Deep Dive

10. Recording Architecture

11. Recording Middleware & Link Activities

12. Call Failure Scenarios

13. Key Source Files Reference

14. Data Models & Entity Relationships

15. Configuration & Environment Variables

16. Event Chain Summary

17. Cisco-Side Configuration Reference

18. 17.1 CUCM Configuration Requirements

19. 17.2 FreeSWITCH Recorder Configuration

20. 17.3 CX Unified Admin — Cisco Voice Channel

21. 17.4 AgentDesk Environment Configurations

22. 17.5 Cisco Elements for CX SIP Proxy

23. 17.6 ESL Configuration for Pause/Resume Recording

24. 17.7 Recording File Encryption/Decryption

25. 17.8 High Availability (HA) Deployment

26. 17.9 Generic Connector JTAPI Commands

27. 17.10 Understanding HA vs Non-HA

28. 17.11 Pause/Resume EFCX Call Recording

29. 17.12 Screen Recording for Cisco

30. 17.13 BiB Compatible Cisco Phones

31. 17.14 Solution Prerequisites & Hardware Sizing

32. 17.15 Port Utilisation

33. 17.16 Eleveo Recording Middleware Reference

34. 17.17 Quality Management (QM) Deployment

---

1. Executive Summary

The CX Voice Recording Solution is a comprehensive contact-center voice platform that integrates with Cisco Unified Communications Manager (CUCM) via JTAPI to capture call events, correlate them with ExpertFlow's conversation data, and produce retrievable call recordings. The system supports both Cisco UCCE and Cisco CCX deployments.

Two Recording Backends

High-Level Flow

Customer Phone → CUCM → FreeSWITCH → Voice Connector → CCM → Routing Engine → Agent Desktop
                          ↓
                    SIPREC / BiB Recording
                          ↓
                    EFSwitch / Eleveo Storage
                          ↓
                    Cisco Connector (JTAPI Events)
                          ↓
                    Recording Middleware → Recording Link Activities → CCM Activities

---

2. System Architecture Overview

┌─────────────────┐     SIP/RTP      ┌──────────────────┐     SIP/RTP      ┌─────────────────┐
│  CUSTOMER       │◄────────────────►│   FREE SWITCH    │◄────────────────►│  AGENT DESKTOP  │
│  (Phone/App)    │    (A-leg)       │  (Media Server)  │    (B-leg)       │ (Browser/Angular│
└─────────────────┘                  └──────────────────┘                  └─────────────────┘
                                              │
                                              │ ESL (Event Socket Library)
                                              ▼
                                    ┌──────────────────┐
                                    │ Voice Connector  │
                                    │ (Java/Spring)    │
                                    └────────┬─────────┘
                                             │ HTTPS REST
                                             ▼
                                    ┌──────────────────┐
                                    │      CCM         │
                                    │ (Conversation    │
                                    │   Manager)       │
                                    └────────┬─────────┘
                                             │ REST API
                                             ▼
                                    ┌──────────────────┐
                                    │  Routing Engine  │
                                    │ (Task/Queue/     │
                                    │  Agent Mgmt)     │
                                    └────────┬─────────┘
                                             │
                              ┌──────────────┼──────────────┐
                              │              │              │
                              ▼              ▼              ▼
                     ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
                     │Cisco Connector│ │ Recording   │ │   JMS/XMPP  │
                     │ (JTAPI Events)│ │ Middleware  │ │   Topics    │
                     └─────────────┘ └─────────────┘ └─────────────┘
                              │              │
                              ▼              ▼
                     ┌─────────────┐ ┌──────────────────────┐
                     │   CUCM/     │ │ Recording Link       │
                     │   UCCE/CCX  │ │ Activities           │
                     │   (TCD/     │ │ (Pushes links to     │
                     │    CCD DB)  │ │  CCM Activities)     │
                     └─────────────┘ └──────────────────────┘

---

3. Component Definitions

---

4. Cisco Integration Layer

4.1 JTAPI (Java Telephony API)

The Cisco Connector and JTAPI Connector use Cisco's JTAPI to listen to call events from CUCM (Cisco Unified Communications Manager).

Connection String:

```

CUCM_IP;login=CUCM_APPLICATION_USER;passwd=CUCM_APPLICATION_USER_PASSWORD

```

Key Classes:

- JtapiConnector — Singleton that establishes the JTAPI provider connection to CUCM

- JtapiListenerService / JtapiCallObserver — Implements CallObserver and CallControlCallObserver to receive call events

4.2 JTAPI Events Captured

4.3 Event Persistence

JTAPI events are immediately persisted to a local database table (jtapi_event) with the following fields:

JtapiEvent event = JtapiEvent.builder()
    .eventType(type)           // CALL_CONNECTED, CALL_HELD, etc.
    .globalCallId(globalCallId) // Cisco Global Call ID (GCID)
    .jtapiId(jtapiId)           // Cisco JTAPI Call ID
    .connectionId(connectionId) // Connection ID (xrefciId)
    .previousGlobalCallId(...)  // For consult calls
    .callingTerminal(callingTerm)
    .calledTerminal(calledTerm)
    .callingExtension(callingExt)
    .calledExtension(calledExt)
    .callDirection(INBOUND/OUTBOUND/INTERNAL)
    .build();

4.4 HA (High Availability) with Consul

When JTAPI_HA_MODE=true, the JTAPI listener uses Consul distributed locks to ensure only one instance processes events for a given call:

boolean acquireLock(Consul consul, String callId) {
    // Creates Consul session and acquires KV lock per callId
}

---

5. Complete Normal Inbound Call Flow

Phase 1: Customer Dials Service Number

Customer dials 8001
│
▼
FreeSWITCH receives SIP INVITE on A-leg
│
▼
FreeSWITCH dialplan matches destination_number 8001
│
▼
FreeSWITCH executes: lua vcApi.lua
│ (no argv[1] → inbound IVR branch)
▼
vcApi.lua:
1. Answers the call (session:answer())
2. Gets serviceIdentifier = destination_number
3. Gets queue info from config (cx_env.lua)
4. Sets sip_h_X-queue, sip_h_X-queueType
5. Sets sip_h_X-Destination-Number = serviceIdentifier
6. Sets session_in_hangup_hook = true
7. Sets api_hangup_hook = "lua cx_hangup.lua"
8. Calls request_agent() → POST to Voice Connector /request-agent

Request body sent to Voice Connector:

```json

{

"callingNumber": "+18005550199",

"queue": "Sales",

"queueType": "NAME",

"callSipId": "abc-123-call-id",

"callUid": "uuid-of-freeswitch-call",

"eslHost": "192.168.1.161",

"serviceIdentifier": "8001",

"direction": "INBOUND",

"priority": ""

}

```

Phase 2: Voice Connector Requests Agent from CCM

Voice Connector receives POST /request-agent
│
▼
InboundController.sendAgentRequest() → VcService.requestAgent()
│
▼
VcService.createAgentRequestPayload():
  • intent = "ASSIGN_RESOURCE_REQUESTED"
  • direction = "INBOUND"
  • mode = "QUEUE"
  • resource = { type: "NAME", value: "Sales" }
  • metadata = { uuid, eslHost }
│
▼
VcService.sendPostRequestCcm() → POST CCM /ccm/message/receive

CIM Message sent to CCM:

```json

{

"header": {

"intent": "ASSIGN_RESOURCE_REQUESTED",

"channelData": {

"channelCustomerIdentifier": "+18005550199",

"serviceIdentifier": "8001"

},

"sender": { "type": "CONNECTOR", "senderName": "CX-Voice-Connector" }

},

"body": {

"type": "ASSIGN_RESOURCE_REQUESTED",

"additionalDetail": {

"callId": "abc-123-call-id",

"direction": "INBOUND",

"mode": "QUEUE",

"resource": { "type": "NAME", "value": "Sales" },

"metadata": { "uuid": "call-uuid", "eslHost": "192.168.1.161" }

}

}

}

```

Phase 3: CCM + Routing Engine Queue and Reserve Agent

CCM receives ASSIGN_RESOURCE_REQUESTED
│
▼
CCM creates conversation + channel session
│
▼
CCM → Routing Engine: AssignResourceRequest
│
▼
Routing Engine:
1. TaskManager.enqueueTask()
   • Creates TaskMedia (state = QUEUED)
   • Creates Task (conversationId, media)
   • Inserts into TasksRepository
   • Publishes TaskStateChanged event
2. PrecisionQueuesPool.publishNewRequest()
   • Adds task to queue
3. AssignAgentService.assignAgent()
   • Finds best available agent
   • agent.reserveTask(task, media)
   • TaskMedia state = RESERVED
   • Agent MRD state = RESERVED
   • Publishes AGENT_RESERVED event

Phase 4: CCM Notifies Voice Connector → FreeSWITCH Calls Agent

CCM receives AGENT_RESERVED from Routing Engine
│
▼
CCM sends notification to Voice Connector
  • NotificationType = AGENT_RESERVED
  • Contains: agent extension, call UUID, queue name
│
▼
Voice Connector receives POST /ccm-msg/receive/cim-messages
│
▼
OutboundController.receiveCimMessage():
  • Extracts agentExtension from AgentReservedDto
  • Extracts call UUID from task metadata
│
▼
VcService.routeAgent(direction="INBOUND"):
  • Calls handleAgentForInbound()
│
▼
handleAgentForInbound():
1. Connects to FreeSWITCH via ESL (ESL inbound client)
2. ESL: uuid_setvar_multi <uuid> sip_h_X-queueType=NAME;sip_h_X-queue='Sales'
3. ESL: uuid_transfer <uuid> <agent_extension> XML <domain>
   • This bridges the customer call (A-leg) to agent's SIP extension
│
▼
FreeSWITCH sends SIP INVITE to Agent Desktop (B-leg)

Phase 5: Agent Desktop Receives and Displays Call

SIP INVITE arrives at Agent Desktop via WebSocket
│
▼
sip-wrapper.js onInvite handler:
1. Creates dialog from dialogStatedata template
2. Extracts headers from INVITE:
   • X-Call-Id → dialog.id
   • X-Customernumber → dialog.customerNumber
   • X-Queue → dialog.queueName
   • X-Calltype → dialog.callType ("INBOUND")
   • X-Destination-Number → dialog.serviceIdentifier
   • X-Call-Variable0..9 → dialog.callVariables
3. Sets dialog.state = "ALERTING"
4. Sets participants[0].state = "ALERTING"
5. Sets participants[0].actions.action = ["ANSWER"]
6. Sets event = "newInboundCall"
7. callback(invitedata) → Angular sip.service.ts
8. SendPostMessage(invitedata) → parent window (if iframe)
9. Stores session reference: invitedata.session = invitation
10. calls.push(invitedata)
11. addsipcallback(invitation, 'inbound', callback)
    • Attaches onCancel, onBye, stateChange listeners

Dialog object after onInvite:

```json

{

"event": "newInboundCall",

"response": {

"loginId": "1005",

"dialog": {

"id": "abc-123-call-id",

"state": "ALERTING",

"callType": "INBOUND",

"customerNumber": "+18005550199",

"serviceIdentifier": "8001",

"queueName": "Sales",

"participants": [{

"mediaAddress": "1005",

"state": "ALERTING",

"actions": { "action": ["ANSWER"] },

"startTime": null

}],

"callVariables": { "CallVariable": [...] }

}

},

"session": <SIP.js Invitation object>

}

```

Angular UI receives callback → sip.service.ts handleNewInboundCallEvent():

1. Sets callChannelType = "cx_voice"

2. Calls handleInboundAndCampaignCallEvent(event, "INBOUND")

• Creates customer object

• Identifies customer by phone number

• Shows incoming call notification

3. Sends CALL_ALERTING to CCM via ccmChannelSessionApi()

{
  "header": { "intent": "CALL_ALERTING" },
  "body": {
    "type": "VOICE",
    "callId": "abc-123-call-id",
    "leg": "abc-123:1005:+18005550199:2026-06-01T10:00:00.000Z",
    "reasonCode": "INBOUND"
  }
}

Phase 6: Agent Answers

Agent clicks ANSWER button in UI
│
▼
sip.service.ts → postMessages({action: "answerCall", parameter: {dialogId, answerCalltype: "audio"}})
│
▼
sip-wrapper.js respond_call():
1. Finds session in calls[] by dialogId
2. Sets session delegate (inviteDelegate)
3. Configures sessionDescriptionHandlerOptions (audio constraints)
4. Calls session.accept(inviteOptions)
│
▼
SIP.js sends 200 OK response to FreeSWITCH
│
▼
Media established (RTP audio stream)
│
▼
addsipcallback stateChange listener fires:
  • newState === SIP.SessionState.Established
  • Sets participants[0].state = "ACTIVE"
  • Sets dialog.state = "ACTIVE"
  • Sets isCallEnded = 0
  • Sets startTime = new Date().toISOString()
  • Sets actions = ["TRANSFER_SST", "HOLD", "SEND_DTMF", "DROP"]
  • callback(sessionall) → Angular
│
▼
Angular UI receives ACTIVE state

sip.service.ts handleDialogActiveEvent():

1. Checks if dialogCache exists (was ALERTING)

2. Sets dialogCache to "active"

3. Sets isCallActive = true

4. Starts local/remote media streams

5. Creates CALL_LEG_STARTED CIM message

6. Sends to CCM via ccmChannelSessionApi()

{
  "header": { "intent": "CALL_LEG_STARTED" },
  "body": {
    "type": "VOICE",
    "callId": "abc-123-call-id",
    "leg": "abc-123:1005:+18005550199:2026-06-01T10:00:00.000Z",
    "reasonCode": "INBOUND"
  }
}

At this point:

- Customer and Agent are talking (RTP audio flowing)

- UI shows "On Call" with timer, Hold, Transfer, Hangup buttons

- CCM has received: CALL_ALERTING, CALL_LEG_STARTED

- Routing Engine knows agent is BUSY

Phase 7: Call Ends (Normal Hangup)

Agent clicks Hangup OR Customer hangs up
│
▼
If Agent clicks Hangup:
  sip.service.ts → postMessages({action: "releaseCall", parameter: {dialogId}})
  sip-wrapper.js terminate_call(dialogId):
    • Finds session in calls[]
    • Calls session.bye()
    • SIP BYE sent to FreeSWITCH

If Customer hangs up first:

FreeSWITCH sends SIP BYE to Agent Desktop

│

▼

sip-wrapper.js onBye handler:

• Extracts X-Call-Dropped-Custom-Reason header

• Or extracts text="NORMAL_CLEARING" from BYE body

• Sets callEndReason = "NORMAL_CLEARING"

│

▼

addsipcallback stateChange → Terminated:

• state = DROPPED

• participants[0].state = DROPPED

• If callEndReason is null → "AGENT-HANDLED"

• callback(sessionall) → Angular

• calls.splice(index, 1) → removes from array

│

▼

Angular UI receives DROPPED state

```

sip.service.ts handleDialogDroppedEvent():

1. Removes notification

2. Determines callType = "DIALOG_ENDED"

3. handleWhenEndReasonIsNotCustomerConferenceLeft()

→ handleReasonOtherThanNoAnswerOrOriginatorCancel()

→ handleCallDroppedEvent()

4. Creates CALL_LEG_ENDED CIM message

5. Sends to CCM via ccmChannelSessionApi()

6. Clears local dialog cache

{
  "header": { "intent": "CALL_LEG_ENDED" },
  "body": {
    "type": "VOICE",
    "callId": "abc-123-call-id",
    "leg": "abc-123:1005:+18005550199:2026-06-01T10:00:00.000Z",
    "reasonCode": "NORMAL_CLEARING"
  }
}

Phase 8: CCM Closes Conversation

CCM receives CALL_LEG_ENDED
│
▼
CallLegEndedEvent.handle():
  • Returns RoomEventResponse.POST_CONTROLLER_INTENT
│
▼
CCM ActivityService:
  • Updates channel session state
  • If all channel sessions ended:
    • Closes conversation
    • Publishes CHANNEL_SESSION_ENDED
│
▼
Routing Engine:
  • TaskManager.changeStateOnMediaClose()
  • Agent MRD state: BUSY → READY (if no other tasks)
  • Publishes AGENT_STATE_CHANGED

---

6. Complete Normal Outbound Call Flow

Phase 1: Agent Initiates Outbound Call

Agent opens dialpad in Agent Desktop UI
│
▼
Agent enters customer phone number (e.g., +18005550199)
│
▼
Agent clicks Call button
│
▼
Angular component → sip.service.ts makeCallOnSip(customer, number)
│
▼
sip.service.ts:
1. Sets isOBCallRequested = true
2. Calls makeCXVoiceMrdNotReady(customer)
   • Emits changeAgentState → MRD = NOT_READY
3. Waits 700ms (setTimeout)
4. Checks if CX Voice MRD is now NOT_READY
   • If yes: sends command to sip-wrapper.js
   • If no: shows error, resets state

Phase 2: sip-wrapper.js Initiates SIP Call

sip.service.ts sends postMessages({action: "makeOBCall", parameter: {...}})
│
▼
sip-wrapper.js receives makeOBCall command
│
▼
sip-wrapper.js initiate_call(calledNumber, DN, mediaType, callback, "MANUAL_OUT", serviceIdentifier):
1. Validates parameters
2. Creates SIP URI: sip:+18005550199@expertflow
3. Creates new SIP.Inviter(userAgent, sip_uri)
4. Sets SIP headers on INVITE request:
   • X-Destination-Number: <serviceIdentifier> (e.g., 8001)
   • X-Calltype: OUT
5. Configures inviteOptions with requestDelegate
6. Calls sessionall.invite(inviteOptions)
│
▼
SIP.js sends SIP INVITE to FreeSWITCH

SIP INVITE sent by Agent Desktop:

```

INVITE sip:+18005550199@expertflow SIP/2.0

Via: SIP/2.0/WSS agent-desktop

From: <sip:1005@expertflow>

To: <sip:+18005550199@expertflow>

X-Destination-Number: 8001

X-Calltype: OUT

```

Phase 3: FreeSWITCH Receives and Processes Outbound INVITE

FreeSWITCH receives SIP INVITE from Agent Desktop
│
▼
FreeSWITCH dialplan processes the INVITE
│
▼
FreeSWITCH originates call to customer's phone number
│ (via SIP trunk / PSTN gateway)
▼
Customer's phone starts ringing

Phase 4: Call State Progression in sip-wrapper.js

Phase 5: Agent Desktop Handles Call States

Event "outboundDialing" with state = "INITIATING":

- sip.service.ts handleOutboundDialingEvent()

- Calls identifyCustomer()

- Shows "Calling..." UI

Event "outboundDialing" with state = "INITIATED":

- Shows "Ringing..." UI

Event "dialogState" with state = "ACTIVE":

- sip.service.ts handleCallActiveEvent()

- For OUTBOUND calls, calls getDefaultOutBoundChannel()

- Fetches default outbound channel from backend API

- Gets serviceIdentifier for outbound channel

- Creates CALL_LEG_STARTED CIM message

- Sends to CCM via ccmChannelSessionApi()

- Sets isCallActive = true

- Shows "On Call" UI with timer

{
  "header": { "intent": "CALL_LEG_STARTED" },
  "body": {
    "type": "VOICE",
    "callId": "outbound-call-id",
    "leg": "outbound-id:1005:+18005550199:2026-06-01T10:00:00.000Z",
    "reasonCode": "OUTBOUND"
  }
}

Phase 6: Call Active

Agent and Customer are talking (RTP audio)

- UI shows: Call timer counting, Buttons: Hold, Transfer, Hangup, Customer info (if identified)

Phase 7: Call Ends

Same as inbound — agent or customer hangs up → CALL_LEG_ENDED sent to CCM with reasonCode "OUTBOUND"

Phase 8: CCM + Routing Engine Cleanup

CCM receives CALL_LEG_ENDED → closes conversation → Routing Engine updates MRD: BUSY → READY

---

7. Complete RONA Flow

The Two Parallel Paths

When RONA occurs, two independent things happen simultaneously:

Path A: Agent Desktop (SIP Path)
Path B: FreeSWITCH Backend (HTTP Path)

These paths do NOT depend on each other. They are triggered by the same FreeSWITCH originate failure.

Path A: Agent Desktop

FreeSWITCH originate fails with cause = "NO_ANSWER"
│
▼
FreeSWITCH sends SIP CANCEL to Agent Desktop
│
▼
sip-wrapper.js onCancel:
  • Extracts text="NO_ANSWER" from Reason header
  • Sets callEndReason = "NO_ANSWER"
│
▼
addsipcallback stateChange → Terminated
  • state = DROPPED
│
▼
sip.service.ts handleDialogDroppedEvent()
  → handleWhenEndReasonIsNotCustomerConferenceLeft()
  → handleNoAnswerOROriginatorCancelEndReason()
  → checkActiveTasks(agentId, dialog, "NO_ANSWER", ...)
  → handleNoAnswerEvent()
  → endingReason == "NO_ANSWER"
  → clearCacheAndCloseControlsDialog(cacheId)
    • Clears localStorage dialog cache
    • Closes call popup

Path B: FreeSWITCH Backend

FreeSWITCH originate fails with cause = "NO_ANSWER"
│
▼
FreeSWITCH executes: lua vcApi.lua rona
│
▼
vcApi.lua (rona branch):
1. Gets originate_failed_cause = "NO_ANSWER"
2. Converts to: hup_cause = "RONA"
3. Checks voicemail_enabled flag
   • If true: transfers to voicemail DN, cancels agent, returns
4. Checks transferType:
   • If NAMED (not CONSULT): plays error, ends call, returns
5. Calls cancel_agent() → POST to Voice Connector /cancel-agent
   with errorCode = "RONA"
6. Calls request_agent() → requeues the call

vcApi.lua rona branch:

```lua

-- CONVERT NO_ANSWER CAUSE TO RONA AS THE CX NEEDS IT

if (hup_cause == "NO_ANSWER") then

hup_cause = "RONA"

end

-- CANCEL AGENT REQUEST VIA THE VOICE CONNECTOR

cancel_agent(serviceIdentifier, direction, cx_env, customerNumber, hup_cause)

-- REQUEUEING CALL (for queue-based transfers)

request_agent(serviceIdentifier, direction, queue, queueType, priority, cx_env, customerNumber)

```

Voice Connector → CCM

Voice Connector receives POST /cancel-agent
│
▼
VcService.cancelAgent():
  • Creates CIM: intent = CANCEL_RESOURCE_REQUESTED
  • body.additionalDetail.reasonCode = "RONA"
  • body.additionalDetail.requestType = "VOICE"
  • POSTs to CCM /ccm/message/receive

CCM → Routing Engine

CCM receives CANCEL_RESOURCE_REQUESTED
│
▼
CancelResourceRequestedEvent.handle():
  • Extracts direction = "INBOUND"
  • Extracts reasonCode = "RONA"
  • Checks requestType == "VOICE"
  • Calls: restRequest.revokeVoiceRequestByDirection(convId, INBOUND, "RONA")
│
▼
Routing Engine TasksController:
  • DELETE /tasks/conversation/{convId}/direction/{dir}/voice/{reasonCode}
│
▼
TasksService.revokeVoiceResourceByDirection(convId, INBOUND, "RONA")

Routing Engine Revokes Task

public void revokeVoiceResourceByDirection(String conversationId, TaskTypeDirection direction, String reasonCode) {
    List<Task> tasks = find voice tasks by conversationId with direction
    tasks.forEach(t -> {
        TaskMedia media = t.findInProcessCxVoiceMedia(CX_VOICE_MRD_ID);
        boolean agentStateToBeUpdatedToNotReady = false;
        if (media != null) {
            // ONLY for RONA on RESERVED media → set agent to NOT_READY
            if (media.getState().equals(TaskMediaState.RESERVED)
                    && reasonCode.equalsIgnoreCase("RONA")) {
                agentStateToBeUpdatedToNotReady = true;
            }
            // Revoke the task
            this.taskManager.revokeInProcessVoiceTask(t, false, media);
            // After revoke, set agent state to NOT_READY (RONA only)
            if (agentStateToBeUpdatedToNotReady) {
                AgentStateChangeRequest request = new AgentStateChangeRequest(
                    t.getAssignedTo().getId(),
                    new AgentState(Enums.AgentStateName.NOT_READY, null)
                );
                agentStateService.agentState(request);
            }
        }
    });
}

FreeSWITCH Requeues the Customer

freeswitch.consoleLog("INFO", "REQUEUEING CALL")
session:sleep(3000);
session:setVariable("session_in_hangup_hook", "true")
session:setVariable("api_hangup_hook", "lua cx_hangup.lua")
local statusCode = tostring(request_agent(serviceIdentifier, direction, queue, queueType, priority, cx_env, customerNumber))
if (statusCode ~= "200") then
    session:streamFile(cx_env.ivr_prompts_folder .. "error_try_later.wav")
    session:hangup("SERVICE_UNAVAILABLE")
    return
end
hold_music(cx_env) -- Customer hears hold music while waiting

---

8. Transfer, Consult & Conference Flows

8.1 Direct Transfer

Agent A (1005) is on call with Customer
│
▼
Agent A initiates transfer to Agent B (1006)
│
▼
Agent A clicks Transfer button → sip.service.ts
│
▼
Transfer flow in Angular:
  • If blind transfer: sends TRANSFER_SST CIM to CCM
  • If consult transfer: first creates consult call, then completes transfer
│
▼
CCM processes transfer → sends new AGENT_RESERVED to Voice Connector
│
▼
Voice Connector transfers customer call to Agent B via ESL

8.2 Consult Transfer

Agent A is on call with Customer
│
▼
Agent A clicks Consult → dials Agent B
│
▼
sip-wrapper.js initiates new INVITE to Agent B (CONSULT call)
│
▼
Agent B answers → Agent A and Agent B are talking (customer on hold)
│
▼
Agent A clicks Transfer → completes consult transfer
│
▼
Customer is now connected to Agent B
│
▼
JTAPI events captured:
  • CiscoConsultCallActiveEv — consult call started
  • CiscoTransferStartEv — transfer initiated
  • ConnDisconnectedEv on original leg
  • ConnConnectedEv on new leg

8.3 Conference

Agent A is on call with Customer
│
▼
Agent A clicks Conference → dials Agent B
│
▼
Agent B answers
│
▼
Agent A clicks Merge → Conference starts
│
▼
JTAPI events:
  • CiscoConferenceStartEv
  • CiscoConferenceEndEv (when conference ends)
│
▼
Cisco Connector processes conference events:
  • Links all conference legs under same callId
  • Creates CALL_CONF_STARTED / CALL_CONF_ENDED events

---

9. JTAPI Event Processing Deep Dive

9.1 Correlation Service

The CorrelationService (in Cisco Connector) runs a scheduled background job that:

1. Fetches unprocessed JTAPI events from the database

2. Deduplicates events (skips duplicate CALL_CONNECTED, CALL_DISCONNECTED)

3. Groups events by globalCallId

4. Validates event groups (ensures equal CONNECTED and DISCONNECTED counts)

5. Detects fake legs (first event = CALL_TRANSFERRED followed by CALL_CONNECTED)

6. Collects events of one call (links consult legs to parent legs)

7. Detects call type: SIMPLE, DIRECT_TRANSFER, CONSULT, CONSULT_TRANSFER, CONFERENCE

8. Builds CallLeg objects with start/end times, reasons, and durations

9. Saves legs and histories to database

9.2 Call Type Detection

CallType detectCallType(List<JtapiEvent> events) {
    // Conference
    if (hasConfStart && hasConfEnd && hasConsult) return CallType.CONFERENCE;

// Consult Transfer

if (hasConsult && consultStartAt != null) {

for (JtapiEvent e : events) {

if (e.getEventType() == CALL_TRANSFERRED && e.getCreatedAt().isAfter(consultStartAt))

return CallType.CONSULT_TRANSFER;

}

}

// Plain Consult

if (hasConsult) return CallType.CONSULT;

// Direct Transfer vs Simple

if (connectedConnIds.size() >= 2) return CallType.DIRECT_TRANSFER;

return CallType.SIMPLE;

}

```

9.3 Building Call Legs

CallLeg buildLeg(String callId, JtapiEvent start, JtapiEvent end,
                 LegStartReason startReason, LegEndReason endReason) {
    String agentExtension;
    if (startReason == INBOUND || startReason == CONSULT || 
        startReason == CONSULT_TRANSFER || startReason == CONSULT_CONFERENCE) {
        agentExtension = start.getCalledExtension();
    } else {
        agentExtension = start.getCallingExtension();
    }

CallLeg leg = new CallLeg();

leg.setCallId(callId);

leg.setGlobalCallId(start.getGlobalCallId());

leg.setConnectionId(start.getConnectionId());

leg.setJtapiId(start.getJtapiId());

leg.setAgentExtension(agentExtension);

leg.setStartTime(start.getCreatedAt());

leg.setEndTime(end.getCreatedAt());

leg.setDuration(Duration.between(start.getCreatedAt(), end.getCreatedAt()).toMillis());

leg.setStartReason(startReason);

leg.setEndReason(endReason);

return leg;

}

```

9.4 Cisco Record Correlation

The ConversationService runs a scheduled job that:

1. Fetches unsynced CallLegs

2. Groups legs by callId

3. Fetches Cisco TCD (Termination Call Detail) or CCD (Contact Call Detail) records from Cisco database

4. Matches Cisco records to CallLegs by closest end-time

5. Enriches CallLegs with:

6. serviceIdentifier

7. customerIdentifier

8. agentName

9. agentId

10. wrapUps

11. Builds CIM messages: CALL_LEG_STARTED, CALL_LEG_ENDED, WRAPUP

12. Sends to CCM via /conversation-manager/activities/voice

CCE Query (Termination_Call_Detail):

```sql

SELECT

tcd.ANI,

tcd.DigitsDialed,

tcd.WrapupData AS WrapUps,

tcd.AgentSkillTargetID AS AgentID,

tcd.PeripheralCallKey AS JtapiId,

tcd.CallTerminatedDateTimeUTC AS endDateTime,

a.EnterpriseName AS AgentName,

tcd.InstrumentPortNumber AS extension,

dd.LastName as callId,

dd.CallResult as callResult,

CASE WHEN tcd.PeripheralCallType IN (7,17,18,27,28,29,30,31,32,33,34,35,36,37,41)

THEN 'OUTBOUND' ELSE 'INBOUND' END AS conversationType

FROM Termination_Call_Detail AS tcd

LEFT JOIN Agent AS a ON tcd.AgentSkillTargetID = a.SkillTargetID

LEFT JOIN Dialer_Detail AS dd ON tcd.PeripheralCallKey = dd.PeripheralCallKey

WHERE tcd.PeripheralCallKey IN (...)

```

CCX Query (ContactCallDetail):

```sql

SELECT

ccd.contactid AS JtapiId,

ccd.originatordn AS ANI,

ccd.callednumber AS DigitsDialed,

acd.callwrapupdata AS WrapUps,

COALESCE(ccd.enddatetime, cl.enddatetime, acd.enddatetime) as enddatetime,

r.resourceid AS AgentId,

r.resourcename AS AgentName,

r.extension,

dl.lastname as CallId

FROM ContactCallDetail ccd

LEFT JOIN AgentConnectionDetail acd ON acd.contactid = ccd.contactid

LEFT JOIN ConsultLegDetail cl ON cl.contactid = ccd.contactid

LEFT JOIN resource r ON r.resourceid = COALESCE(acd.resourceid, cl.destinationresourceid, ccd.originatorid)

LEFT JOIN dialingList dl ON dl.dialinglistid = acd.dialinglistid

WHERE ccd.contactid IN (...)

```

---

10. Recording Architecture

10.1 EFSwitch Recording (FreeSWITCH-based)

Recording Flow:

```

FreeSWITCH bridges A-leg (customer) and B-leg (agent)

│

▼

FreeSWITCH starts recording via:

• dialplan configuration or

• Lua script: set_recording_name.lua

│

▼

Recording is saved as WAV file:

/app/files/wav/<date>/<uuid>:<agent>:<ani>:<startTime>.wav

│

▼

Filename format:

<dialogId>:<agentExtension>:<customerNumber>:<epochSeconds>.wav

│

▼

Files are optionally encrypted with AES/CFB/NoPadding

```

set_recording_name.lua:

```lua

local callType = session:getVariable("sip_h_X-CallType")

local record_path = session:getVariable("record_path")

local uuid = session:getVariable("uuid")

local ext = session:getVariable("record_ext")

-- For consult calls

if (callType == "CONSULT") then

session:execute("stop_record_session","all")

local filename = uuid .. "." .. ext

session:setVariable("recording_filename", filename)

session:setVariable("recording_command",

"nolocal:execute_on_answer=record_session " .. record_path .. "/" .. filename)

return

-- For outbound calls

elseif (callType == "OUT") then

customer_leg_uuid = session:getVariable("customer_leg_uuid")

session:setVariable("recording_command",

"nolocal:execute_on_answer=record_session " .. record_path .. "/" .. customer_leg_uuid .. "." .. ext)

session:setVariable("recording_filename", customer_leg_uuid .. "." .. ext)

return

end

-- For inbound calls

local filename = uuid

local count = 0

while (fileExists(filename .. '.' .. ext)) do

count = count + 1

filename = uuid .. '_' .. count

end

filename = uuid .. suffix .. "." .. ext

session:setVariable("recording_filename", filename)

session:setVariable("recording_command",

"nolocal:execute_on_answer=record_session " .. record_path .. "/" .. filename)

```

10.2 Eleveo Recording (Cisco BiB)

For Eleveo deployments, recording is handled by Cisco Built-in-Bridge (BiB) on Cisco phones:

Cisco Phone (Agent)
│
▼ Built-in-Bridge forks audio
├─→ A-leg: Customer conversation
└─→ B-leg: Recording stream → Eleveo recorder
│
▼
Eleveo stores recording with metadata (JTAPI_CISCO_ID, COUPLE_START_REASON, etc.)
│
▼
Recording Middleware queries Eleveo API to retrieve files

10.3 Call Forking & Recording Architectures

Call forking is the process of duplicating a single call into multiple parallel RTP streams, allowing the same audio to be routed to different destinations simultaneously. In CX Voice Recording, this is the foundational mechanism by which recordings are captured.

Three Forking Sources for CX Media Server:

Forking Flow:

Incoming Call
    │
    ▼
System duplicates the call (forks)
    │
    ├─► A-leg: Original call → Agent
    │
    ├─► B-leg: Recording stream → FreeSWITCH / Eleveo
    │
    └─► C-leg (optional): Screen capture → Screen recorder
    │
    ▼
Parallel Processing:
    • Agent continues normal conversation
    • Recorder writes audio to disk
    • NLU engine (optional) receives stream for transcription

SIPREC-based Recording (Drachtio + FreeSWITCH)

An alternative architecture uses Drachtio (open-source SIP server framework) to receive SIPREC streams from a Cisco CUBE or SBC, then bridges them to FreeSWITCH for recording.

Drachtio Server Setup:

# Install dependencies
sudo apt install libcurl4-openssl-dev

Build drachtio-server

Configure admin port

Run as service

FreeSWITCH Dialplan for SIPREC Hairpin & Record:

<!-- /etc/freeswitch/dialplan/public.xml -->
<extension name="hairpin_and_record">
  <condition field="${sip_h_X-Return-Token}" expression="^(.+)$">
    <action application="export" data="sip_h_X-Return-Token=${sip_h_X-Return-Token}" />
    <action application="export" data="_nolocal_jitterbuffer_msec=100"/>
    <action application="set" data="RECORD_STEREO=true"/>
    <action application="set" data="call_id=${strftime(%Y%m%d_%H%M%S)}_${sip_from_tag}"/>
    <action application="set" data="outfile=$${base_dir}/recordings/${call_id}.wav"/>
    <action application="record_session" data="${outfile}"/>
    <action application="set" data="hangup_after_bridge=true"/>
    <action application="bridge" data="sofia/external/${destination_number}@${network_addr}"/>
  </condition>
</extension>

Important: Internal FreeSWITCH SIP profile must listen on 5065 (not 5060) because Drachtio uses 5060 for incoming SIPREC.

SIPREC Test Results Matrix:

10.4 Recording Use Cases Enabled by Call Forking

---

11. Recording Middleware & Link Activities

11.1 Recording Middleware

The Recording Middleware is a Spring Boot application that serves recording files via REST API.

Endpoints:

```

GET /{legId}/recording-file

→ Returns audio/wav file (EFSwitch) or merged bytes (Eleveo)

```

Backend Selection (Spring @ConditionalOnProperty):

```java

// EFSwitch backend (default)

@ConditionalOnProperty(name = "recording.backend", havingValue = "EFSWITCH", matchIfMissing = true)

public class EfswitchRecordingService implements RecordingServiceInterface { ... }

// Eleveo backend

@ConditionalOnProperty(name = "recording.backend", havingValue = "ELEVEO")

public class EleveoRecordingService implements RecordingServiceInterface { ... }

```

EFSwitchRecordingService

public Resource getRecordingFile(String legId) {
    // legId format: dialogId:agent:ani:epochTime
    String[] legIdParts = splitOnLastThreeColons(legId);
    String dialogId = legIdParts[0];
    String agent = legIdParts[1];
    String ani = legIdParts[2];
    Long cxLegStartTime = Long.parseLong(legIdParts[3].substring(0, legIdParts[3].length() - 3));

// Query FusionPBX database for file path

List<EfswitchCallLeg> efswitchCallLegs = getEfswitchCallLegs(dialogId, agent, ani, cxLegStartTime);

// Find closest match by start time

EfswitchCallLeg matchedLeg = findClosestMatch(efswitchCallLegs, cxLegStartTime);

// Return decrypted or plain file

return encryptionEnabled ? getDecryptedResource(matchedLeg) : getPlainResource(matchedLeg);

}

```

Decryption (AES/CFB/NoPadding):

```java

byte[] keyBytes = hexStringToByteArray(hexKey);

Key secretKey = new SecretKeySpec(keyBytes, "AES");

Cipher cipher = Cipher.getInstance("AES/CFB/NoPadding");

byte[] iv = new byte[16];

inputStream.read(iv);

IvParameterSpec ivSpec = new IvParameterSpec(iv);

cipher.init(cipherMode, secretKey, ivSpec);

```

EleveoRecordingService

public Resource getRecordingFile(String legId) {
    String[] legIdParts = legId.split(":");
    String dialogId = legIdParts[0];
    String agentExt = legIdParts[1];
    String customerNum = legIdParts[2];
    long cxLegStartTime = parseLegStartTime(legIdParts[3]);

// Fetch conversations from Eleveo API

List<EleveoCallLeg> eleveoCallLegs = getEleveoCallLegs(dialogId, customerNum);

// Merge legs broken by hold/retrieve/conference

mergeHoldEndedLegs(eleveoCallLegs, agentExt);

mergeRetrievedLegs(eleveoCallLegs, agentExt);

mergeConferenceLegs(eleveoCallLegs, agentExt);

// Find matching leg

EleveoCallLeg matchedLeg = findMatchedLeg(eleveoCallLegs, dialogId, agentExt, cxLegStartTime);

// Authenticate with Eleveo and download

String jsessionId = getEleveoJsessionId();

return buildRecordingFile(matchedLeg, jsessionId);

}

```

Eleveo Authentication Flow:

1. Get JSESSIONID via /login?loginname=admin&password=xxx

2. Get download token via /api/download?type=1&action=download&sid=<legId>

3. Download file via /api/download?token=<token>

11.2 Recording Link Activities

The Recording Link Activities service pushes recording URLs to CCM as third-party activities.

Flow:

```

Scheduled Job (every N minutes)

│

▼

1. Calculate time interval (from last pushed time to now)

│

▼

2. Fetch CX Voice call legs from CCM Voice Activities API

GET /conversation-manager/activities/voice?startTime=...&endTime=...

│

▼

3. Fetch corresponding recording legs from backend:

• EFSwitch: query FusionPBX DB + filesystem

• Eleveo: query Eleveo Conversations API

│

▼

4. Map CX legs to recording legs

│

▼

5. Push recording link to CCM Third Party Activities API

POST /conversation-manager/activities/third-party

CIM Message:

{

"header": {

"intent": "VOICE_RECORDING",

"sender": { "type": "CONNECTOR", "senderName": "CX-Recording-Link-Activities" },

"channelSessionId": "<channelSessionId>"

},

"body": {

"legId": "<legId>",

"voiceRecordingUrl": "https://middleware/{legId}/recording-file"

}

}

│

▼

6. Update cache with last pushed time

```

Helper.createRecordingLinkPayload():

```java

public CimMessage createRecordingLinkPayload(String channelSessionId, String legId) {

MessageHeader header = new MessageHeader();

header.setSender(this.sender);

header.setChannelSessionId(channelSessionId);

header.setIntent("VOICE_RECORDING");

ObjectNode node = mapper.createObjectNode();

node.put("legId", legId);

node.put("voiceRecordingUrl", globalProperties.getMiddlewareApi() + "/" + legId + "/recording-file");

UrlMessage body = new UrlMessage();

body.setAdditionalDetails(node);

return new CimMessage(UUID.randomUUID().toString(), header, body);

}

```

---

12. Call Failure Scenarios

12.1 No Agent Available

FreeSWITCH calls request_agent() → Voice Connector → CCM → Routing Engine
│
▼
No agents available
│
▼
CCM sends NO_AGENT_AVAILABLE to Voice Connector
│
▼
Voice Connector plays "no_agent_available.wav" to customer
│
▼
FreeSWITCH schedules hangup after 6 seconds

12.2 Transfer Failure

Voice Connector sends uuid_transfer command to FreeSWITCH
│
▼
ESL response contains "-ERR"
│
▼
Voice Connector logs "TRANSFER FAILED"
│
▼
Voice Connector sends END_CHAT to CCM
│
▼
Call is terminated

12.3 Dialer Connection Failure (Outbound)

Voice Connector attempts to send agent details to Dialer
│
▼
Dialer returns 503 (Service Unavailable)
│
▼
Voice Connector sends END_CHAT to CCM
│
▼
Throws DialerConnectionException

---

13. Key Source Files Reference

13.1 Cisco Connector

13.2 JTAPI Connector (Legacy)

13.3 Voice Connector (ecx_generic_connector)

13.4 FreeSWITCH Scripts

13.5 Recording Middleware

13.6 Recording Link Activities

---

14. Data Models & Entity Relationships

14.1 Cisco Connector Entities

JtapiEvent
├── id (UUID)
├── eventType (CALL_CONNECTED, CALL_HELD, CALL_RESUMED, CALL_TRANSFERRED, CALL_CONSULT_STARTED, CALL_CONF_STARTED, CALL_CONF_ENDED, CALL_DISCONNECTED)
├── globalCallId (String)
├── jtapiId (String)
├── connectionId (String)
├── previousGlobalCallId (String, for consult calls)
├── callingTerminal (String)
├── calledTerminal (String)
├── callingExtension (String)
├── calledExtension (String)
├── callDirection (INBOUND, OUTBOUND, INTERNAL)
└── createdAt (Timestamp)

CallLeg

├── id (UUID)

├── callId (String, generated UUID for the call)

├── globalCallId (String, Cisco GCID)

├── connectionId (String, xrefciId)

├── jtapiId (String, Cisco JTAPI ID)

├── agentExtension (String)

├── startTime (Instant)

├── endTime (Instant)

├── duration (Long, milliseconds)

├── startReason (INBOUND, OUTBOUND, CONSULT, CONSULT_TRANSFER, CONSULT_CONFERENCE)

├── endReason (DIALOG_ENDED, DIRECT_TRANSFER, CONSULT_TRANSFER, CONSULT_ENDED, CONFERENCE_ENDED, HOLD, etc.)

├── conversationType (INBOUND, OUTBOUND)

├── callType (SIMPLE, DIRECT_TRANSFER, CONSULT, CONSULT_TRANSFER, CONFERENCE)

├── serviceIdentifier (String, populated from Cisco TCD/CCD)

├── customerIdentifier (String, populated from Cisco TCD/CCD)

├── agentName (String, populated from Cisco TCD/CCD)

├── agentId (String, populated from Cisco TCD/CCD)

├── wrapUps (String, populated from Cisco TCD/CCD)

└── syncWithCisco (Boolean)

CallLegHistory

├── id (UUID)

├── callLeg (CallLeg)

├── eventType (CALL_HELD, CALL_RESUMED)

└── timestamp (Instant)

```

14.2 JTAPI Connector Entities (Legacy)

CallInformation
├── id (UUID)
├── gcid (String, Global Call ID)
├── jtapiId (String)
├── xrefciId (String, Connection ID)
├── uuid (String, FreeSWITCH call UUID)
├── callType (String: SimpleCall, ConsultCall, ConfCall)
├── eventType (CiscoEventType)
├── callEndTime (Date)
├── callingExtension (String)
├── calledExtension (String)
└── ... (various correlation fields for consult/conference)

---

15. Configuration & Environment Variables

15.1 Cisco Connector

15.2 JTAPI Connector (Legacy)

15.3 Recording Middleware

15.4 Recording Link Activities

---

16. Event Chain Summary

16.1 Inbound Call Event Chain

[Customer] SIP INVITE → [FreeSWITCH]
[FreeSWITCH] HTTP POST /request-agent → [Voice Connector]
[Voice Connector] CIM ASSIGN_RESOURCE_REQUESTED → [CCM]
[CCM] → [Routing Engine] Task QUEUED → RESERVED
[Routing Engine] AGENT_RESERVED → [CCM]
[CCM] CIM AGENT_RESERVED → [Voice Connector]
[Voice Connector] ESL uuid_transfer → [FreeSWITCH]
[FreeSWITCH] SIP INVITE → [Agent Desktop]
[Agent Desktop] SIP 200 OK → [FreeSWITCH]
[Agent Desktop] CIM CALL_ALERTING → [CCM]
[Agent Desktop] CIM CALL_LEG_STARTED → [CCM]
[JTAPI] ConnConnectedEv → [Cisco Connector] → DB jtapi_event
[Customer/Agent] Hangup
[FreeSWITCH] SIP BYE → [Agent Desktop]
[Agent Desktop] CIM CALL_LEG_ENDED → [CCM]
[JTAPI] ConnDisconnectedEv → [Cisco Connector] → DB jtapi_event
[CCM] Conversation closed → [Routing Engine] MRD READY
[Cisco Connector] Correlates JTAPI events → CallLegs
[Cisco Connector] Fetches Cisco TCD/CCD → Enriches CallLegs
[Cisco Connector] CIM CALL_LEG_STARTED + CALL_LEG_ENDED + WRAPUP → [CCM]
[Recording Link Activities] Query recordings → Push VOICE_RECORDING links → [CCM]

16.2 CIM Intents Used

---

17. Cisco-Side Configuration Reference

This section consolidates all Cisco-side configuration requirements extracted from ExpertFlow Confluence documentation (spaces: VRS, CX). It covers CUCM configuration, FreeSWITCH recorder setup, CX Unified Admin configuration, AgentDesk environment variables, SIP Proxy integration, and recording security settings.

---

17.1 CUCM Configuration Requirements (Voice Recording)

The following configurations are required on Cisco Unified Communications Manager (CUCM) to capture voice streams for audio recording.

17.1.1 Recording Profile

1. Create a Recording Profile in CUCM:

2. Navigate to Device → Device Settings → Recording Profile

3. Create a new profile and associate it with your Recording Destination Address (the DN or Route Point where recordings are sent)

4. Create a SIP Profile:

5. Enable the PING Option (helps in troubleshooting trunk health)

6. Configure appropriate codec preferences

7. Create a SIP Security Profile:

8. Set Incoming Transport to TCP + UDP

9. Set Outgoing Transport to TCP

10. Enable Built-in-Bridge (BiB) on all agent phones that will be recorded:

11. Navigate to Device → Phone → [Select Phone] → Device Configuration

12. Set Built-in-Bridge to On

13. Link Recording Profile to Phones:

14. On each phone configuration, set the Recording Profile field to the profile created above

17.1.2 SIP Trunk Configuration

Create a SIP Trunk pointing to the ExpertFlow Recording Server (FreeSWITCH/VRS):

17.1.3 Network & Firewall Requirements

• Disable firewall OR allow the following ports:

• 5060 TCP (SIP signaling, inbound + outbound)

• All UDP ports for RTP media streams

17.1.4 Troubleshooting Checklist

---

17.2 FreeSWITCH Recorder Configuration (VRS)

17.2.1 Recording Script Setup

1. Place the record.lua script in the FreeSWITCH scripts directory:

2. Source package: /usr/local/freeswitch/scripts/

3. Package install: /usr/share/freeswitch/scripts/

4. Update the IP addresses in record.lua to point to your server:

-- Update these URLs in record.lua
url = "http://<IP-ADDRESS>:9900/mixer/sip-data"
url = "http://<IP-ADDRESS>:8080/vrs/recording-rules/evaluate"
url = "http://<IP-ADDRESS>:9900/mixapi"

1. Create the recording directories:

mkdir -p /var/vrs/recordings/cucmRecording/streams
mkdir -p /var/vrs/recordings/cucmRecording/sessions
chmod 777 -R /var/vrs/

1. Update directory paths in record.lua:

recording_dir = "/var/vrs/recordings/cucmRecording/streams/"
recording_path = "/var/vrs/recordings/cucmRecording/streams/"
mixedRecordingDir = "/var/vrs/recordings/cucmRecording/sessions/"

17.2.2 Dialplan Configuration

Edit /usr/local/freeswitch/conf/dialplan/public.xml and add:

<!-- Mark outside calls -->
<extension name="outside_call" continue="true">
  <condition>
    <action application="set" data="outside_call=true"/>
    <action application="export" data="RFC2822_DATE=${strftime(%a, %d %b %Y %T %z)}"/>
  </condition>
</extension>

<!-- CUCM Recording Profile trigger -->

<extension name="CUCM Recording Profile">

<action application="log" data="INFO Entering Call from CUCM"/>

<condition field="${sip_from_host}" expression="<CUCM_IP_ADDRESS>">

<action application="lua" data="record.lua"/>

</condition>

</extension>

```

For multiple CUCM servers, use pipe-delimited IPs:

<condition field="${sip_from_host}" expression="192.168.1.26|192.168.1.27|192.168.1.28">
  <action application="lua" data="record.lua"/>
</condition>
</extension>

17.2.3 SIP Profile Settings

Edit both internal.xml and external.xml in /usr/local/freeswitch/conf/sip_profiles/:

1. Enable 3PCC (Third Party Call Control):

<param name="enable-3pcc" value="true"/>

1. Parse all INVITE headers (add to internal.xml):

<param name="parse-all-invite-headers" value="true"/>

1. Set IP addresses in external.xml:

<param name="rtp-ip" value="<recorder-ip>"/>
<param name="sip-ip" value="<recorder-ip>"/>
<param name="ext-rtp-ip" value="<recorder-ip>"/>
<param name="ext-sip-ip" value="<recorder-ip>"/>

17.2.4 Access Control List (ACL)

Edit /usr/local/freeswitch/conf/autoload_configs/acl.conf.xml and add CUCM IPs:

<configuration name="acl.conf" description="Network Lists">
  <network-lists>
    <!-- existing entries -->
    <node type="allow" domain="$${domain}"/>
    
    <!-- Add CUCM IP(s) -->
    <node type="allow" cidr="<CUCM_IP>/32"/>
    <!-- Repeat for each CUCM -->
  </network-lists>
</configuration>

17.2.5 Disable STUN

Edit /usr/local/freeswitch/conf/vars.xml and comment out STUN lines:

<!-- Comment these out -->
<!-- <X-PRE-PROCESS cmd="stun-set" data="external_rtp_ip=stun:stun.freeswitch.org"/> -->
<!-- <X-PRE-PROCESS cmd="stun-set" data="external_sip_ip=stun:stun.freeswitch.org"/> -->

Restart FreeSWITCH:

sudo systemctl restart freeswitch

17.2.6 Required Utilities

Install Lua dependencies:

sudo apt install -y lua-socket
sudo apt install -y lua-dkjson

---

17.3 CX Unified Admin — Cisco Voice Channel Configuration

17.3.1 Pre-Requisites & Recommendations

• Finesse and CIM Server time must be synced (NTP)

• Customer Activity Timeout in CX must be greater than the call timeout configured on Cisco (Finesse) for the voice channel

• For CX4.2+ use CISCO_CC channel type; for earlier versions use VOICE

17.3.2 Channel Provider Configuration (Unified Admin)

1. Navigate to Unified Admin → Channel Management → Channel Providers

2. Add a provider for CISCO_CC (CX4.2+) or VOICE (earlier) channel type:

3. The provider webhook is not required for Cisco integration

4. Add a Channel Connector for the configured provider

17.3.3 Channel Configuration

Add a channel with the following settings:

17.3.4 MRD (Media Routing Domain) Configuration

For the default CISCO_CC (or VOICE) MRD:

For each user/agent, set max task request to 1 for the Cisco CC MRD.

---

17.4 AgentDesk Environment Configurations for Cisco

Update the ef-unified-agent-configmap.yaml at:

cim-solution/kubernetes/cim/ConfigMaps/ef-unified-agent-configmap.yaml

17.4.1 Required CTI Config Variables

# To enable Cisco contact center integration
isCiscoEnabled: "true"

Cisco Finesse domain name

Secondary Finesse domain (leave blank if no HA)

Cisco Finesse BOSH URL

Secondary Finesse BOSH URL (leave blank if no HA)

SSO backend URL (if Finesse is SSO-enabled)

Cisco UCCE flavor: UCCE | UCCX

RONA timeout as configured on Finesse

Enable if Finesse runs in HA

Finesse FQDN or IP address

Secondary Finesse URL (HA only)

Static identifier used as channel identifier in CX

17.4.2 Encrypted Credentials

Share cf-admin credentials with ExpertFlow support. They will encrypt and update:

ctiParam: "<Encrypted cf admin username>"
ctiParam2: "<Encrypted cf admin password>"

17.4.3 Apply ConfigMap

cd cim-solution/kubernetes
kubectl delete -f cim/ConfigMaps/ef-unified-agent-configmap.yaml
kubectl apply -f cim/ConfigMaps/ef-unified-agent-configmap.yaml

kubectl delete -f cim/Deployments/ef-unified-agent-deployment.yaml

kubectl apply -f cim/Deployments/ef-unified-agent-deployment.yaml

```

---

17.5 Cisco Elements Configurations for CX SIP Proxy

17.5.1 Inbound Call Configuration

CUBE (Cisco Unified Border Element) Settings:

1. Incoming Dial-Peer Configuration:

2. Set the destination IP address of the SIP Proxy in the session target ipv4 field

3. Trusted List:

4. Add the CX SIP Proxy server IP(s) to the trusted list for security

CVP (Cisco Voice Portal) Settings:

1. SIP Proxy Group Assignment:

2. Create a group containing CVP IP addresses

3. Map this group to a Dial Number (DN) on the SIP Proxy from CUBE

4. CVP OAMP Configuration:

5. Configure SIP Proxy IP for specific labels: 45199, 9191, 9292

6. These correspond to EF SIP Proxy configurations

7. VVB (Cisco Voice Browser) Integration:

8. On SIP Proxy, assign a group containing VVB IP addresses to the labels above

9. CUCM Integration:

10. In CVP OAMP, set SIP Proxy IP against CUCM Extension Numbers

11. On SIP Proxy, assign a group containing CUCM IP addresses for call routing

17.5.2 Outbound Call Configuration

Manual Outbound Calls:

1. CUCM SIP Trunk:

2. Create a SIP Trunk on CUCM connecting to the SIP Proxy

3. SIP Proxy Group & Pattern:

4. Create a group containing CUBE IP addresses

5. Map to specific dialing prefixes (e.g., 96***********)

Dialer Connected Calls:

1. Cisco Dialer Registry:

2. Set SIPServerAddress to the SIP Proxy Server IP

3. SIP Proxy Group & Pattern:

4. Same as manual outbound — group CUBE IPs and map to dialing patterns

---

17.6 ESL Configuration for Pause and Resume Recording

The Event Socket Library (ESL) allows external control of FreeSWITCH for pause/resume recording functionality.

17.6.1 ESL Configuration

Edit /etc/freeswitch/autoload_configs/event_socket.conf.xml (or /usr/local/freeswitch/conf/autoload_configs/):

<settings>
  <param name="listen-ip" value="192.168.1.106"/>  <!-- Server IP -->
  <param name="listen-port" value="8021"/>          <!-- Default ESL port -->
  <param name="password" value="<strong-password>"/><!-- NOT default ClueCon -->
  <param name="apply-inbound-acl" value="esl"/>
</settings>

Edit acl.conf.xml in the same directory:

<configuration name="acl.conf" description="Network Lists">
  <network-lists>
    <!-- existing lists -->
    <list name="esl" default="allow">
      <node type="allow" cidr="0.0.0.0/0"/>
    </list>
  </network-lists>
</configuration>

Note: Restrict cidr to specific IPs in production (do not use 0.0.0.0/0).

17.6.2 Apply Changes

fs_cli
> reloadxml
> reloadacl

sudo systemctl restart freeswitch

Test ESL connection

---

17.7 Recording File Encryption/Decryption Configuration

17.7.1 FreeSWITCH Event Hook

Edit /etc/freeswitch/autoload_configs/lua.conf.xml and add under <!-- Subscribe to events -->:

<hook event="RECORD_STOP" subclass="" script="encrypt.lua"/>

Restart FreeSWITCH:

systemctl restart freeswitch

17.7.2 Lua Encryption Script

Create /usr/share/freeswitch/scripts/encrypt.lua:

package.cpath = "/usr/lib/x86_64-linux-gnu/lua/5.2/?.so;" .. package.cpath
package.path = "/usr/share/lua/5.2/?.lua;" .. package.path
local json = require("cjson")

local eventClass = event:getHeader("Event-Subclass")

local uuid = event:getHeader("variable_uuid")

local call_uuid = event:getHeader("variable_call_uuid")

local call_id = event:getHeader("variable_sip_h_X-Call-ID")

local time = event:getHeader("Event-Date-GMT")

local filename = event:getHeader("recording_filename")

freeswitch.consoleLog("INFO", "UUID: " .. tostring(uuid) .. "\n")

freeswitch.consoleLog("INFO", "Filename: " .. tostring(filename) .. "\n")

local input_file_path = event:getHeader("Record-File-Path")

local command = string.format("python3 /usr/share/freeswitch/pythonScript/encrypt.py '%s'", input_file_path)

os.execute(command)

```

Install Lua if needed:

sudo apt update
sudo apt install lua5.3 -y

17.7.3 Python Encryption Script

Create /usr/share/freeswitch/pythonScript/encrypt.py:

from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
from cryptography.hazmat.backends import default_backend
from cryptography.hazmat.primitives import padding
import sys
import logging
import os

log_file = "/var/log/encrypt.log"

logging.basicConfig(filename=log_file, level=logging.INFO,

format="%(asctime)s - %(levelname)s - %(message)s")

def encrypt_file(mixedRecordingPathName, key):

try:

iv = b'1234567890123456'

backend = default_backend()

cipher = Cipher(algorithms.AES(key), modes.CFB(iv), backend=backend)

encryptor = cipher.encryptor()

with open(mixedRecordingPathName, 'rb') as f:

data = f.read()

padder = padding.PKCS7(algorithms.AES.block_size).padder()

padded_data = padder.update(data) + padder.finalize()

encrypted_data = encryptor.update(padded_data) + encryptor.finalize()

with open(mixedRecordingPathName, 'wb') as f:

f.write(iv + encrypted_data)

logging.info(f"Successfully encrypted: {mixedRecordingPathName}")

return mixedRecordingPathName

except Exception as e:

logging.error(f"Error encrypting {mixedRecordingPathName}: {str(e)}")

return None

if __name__ == "__main__":

key = bytes.fromhex('42066107bda481f0266fd709627faf98b422e29a29b01495daa3ef3640ee6fe6')

mixedRecordingPathName = sys.argv[1]

encrypted_file = encrypt_file(mixedRecordingPathName, key)

```

Install dependencies:

sudo apt install python3 -y
sudo apt install python3-cryptography -y

17.7.4 Dialplan Recording Filename Export

In FusionPBX (or FreeSWITCH dialplan), add to the user_record dialplan (last group):

17.7.5 Log File Setup

sudo touch /var/log/encrypt.log
sudo chmod 777 /var/log/encrypt.log

---

17.8 High Availability (HA) / Duplex Deployment

17.8.1 Prerequisites

• A shared file system based on NAS or SAN (note: this is a single point of failure)

• Two VMs with identical specifications (4+ cores, 4+ GB RAM, 300+ GB disk)

17.8.2 Recorder Failover

Deploy core recorder service on two servers with identical configurations. Configure two SIP trunks in CUCM.

17.8.3 Other Services HA

Mixer, REST Server, Archival Process — High availability is achieved via Docker Swarm:

• Docker Swarm manages container orchestration across multiple Docker hosts

• If a worker node becomes unavailable, Docker schedules tasks on other nodes

• If a Docker engine goes down, the Linux OS typically restarts it automatically

17.8.4 SIP Trunk Failover in CUCM

CUCM keeps track of recorder servers and sends SIP invites to one active recorder. The active recorder saves recordings on the shared network file system.

---

17.9 Cisco Generic Connector JTAPI Commands Reference

The Generic Connector exposes JTAPI-based commands for agent state and call control. These are relevant for understanding the Cisco-side event vocabulary that the CX system consumes.

17.9.1 Agent Commands

17.9.2 GC Output Events (relevant to CX)

17.9.3 Agent States

UNKNOWN, READY, NOT_READY, LOGOUT, TALKING, RESERVED,
RESERVED_OUTBOUND, RESERVED_OUTBOUND_PREVIEW, WORK, WORK_READY, HOLD

17.9.4 Dialog States

INITIATED, INITIATING, ALERTING, ACTIVE, HELD, FAILED, DROPPED, ACCEPTED

---

17.10 Understanding HA vs Non-HA in CX Voice

---

17.10.1 The Core Idea (Analogy)

Imagine a bridge with one lane vs. a bridge with two lanes:

In software terms, the "lane" is a running service instance (JVM, Docker container, or VM). HA ensures there is always a backup ready to take over.

---

17.10.2 Where HA Matters in This Architecture

The CX Voice + Cisco system has four distinct HA domains. Each operates independently — you can configure HA for some and not others.

A. JTAPI Connector HA (Cisco-Connector / JTAPI-Connector)

What it does: Listens to Cisco CUCM call events via JTAPI and persists them to the database.

How the Consul lock works:

Node-A (Active)          Node-B (Standby)          Consul Server
    │                          │                          │
    ├─ acquireLock(callId) ──►│                          │
    │◄──── lock granted ───────┤                          │
    │                          │                          │
    ├─ process JTAPI event ──► │                          │
    │                          │                          │
 [Node-A CRASHES]            │                          │
    │                          ├─ acquireLock(callId) ──►│
    │                          │◄──── lock granted ──────┤
    │                          │                          │
    │                          ├─ process JTAPI event ──► │

The lock is per call ID, so even in HA mode, events for the same call are never processed by both nodes simultaneously (preventing duplicates).

---

B. Finesse HA (Agent Desktop CTI)

What it does: The AgentDesk (unified-agent) connects to Cisco Finesse for agent state management, call control, and screen-pop.

Important: Finesse HA is a Cisco-side feature (two Finesse servers configured as a pair in Cisco UCCE/UCCX). CX simply connects to whichever is active.

---

C. Recorder HA (Voice Recording Server / FreeSWITCH)

What it does: Receives SIPREC/BiB streams from CUCM and writes recording files.

How CUCM decides which recorder to use:

CUCM sends periodic SIP OPTIONS pings to both trunks. The recorder that responds is marked active. If the active recorder stops responding, CUCM switches to the other trunk.

CUCM ──SIP INVITE──► Recorder-A (ACTIVE) ──RTP──► writes to NAS
   │
   └──SIP OPTIONS──► Recorder-A  ◄──200 OK── healthy
   │
   └──SIP OPTIONS──► Recorder-B  ◄──200 OK── healthy (standby)

[Recorder-A stops responding]

CUCM ──SIP INVITE──► Recorder-B (now ACTIVE) ──RTP──► writes to same NAS

```

---

D. Docker Swarm HA (Mixer, REST API, Archival)

What it does: Services like the recording mixer, REST server, and archival process run as Docker containers.

Docker Swarm behavior:

┌─────────────────┐         ┌─────────────────┐
│   Swarm Node 1  │         │   Swarm Node 2  │
│  (Manager)      │◄───────►│  (Worker)       │
│                 │  Mesh   │                 │
│ • Mixer svc     │ Network │ • Mixer svc     │
│ • REST API svc  │         │ • Archival svc  │
└─────────────────┘         └─────────────────┘

[Node 1 crashes]

Swarm Manager (on Node 2 or Node 3) detects failure

│

▼

Reschedules Mixer + REST API containers to Node 2

```

---

17.10.3 Configuration Comparison: HA vs Non-HA

---

17.10.4 Trade-offs: When to Use HA

Rule of thumb:

- Non-HA = Development, testing, proof-of-concept, or small contact centers (< 20 agents) where occasional downtime is acceptable.

- HA = Production deployments, regulated industries (finance, healthcare), or any environment where every call and recording must be captured.

---

17.10.5 Summary Diagram: Full HA Deployment

┌─────────────────────────────────────────────────────────────────────────────┐
│                           PRODUCTION HA DEPLOYMENT                          │
├─────────────────────────────────────────────────────────────────────────────┤
│  CUCM                          │  FreeSWITCH Recorders (HA Pair)            │
│  ┌─────────┐                   │  ┌─────────────────┐  ┌─────────────────┐  │
│  │ SIP Trk │───────────────────┼─►│ Recorder-A      │  │ Recorder-B      │  │
│  │  (Pri)  │                   │  │ (Active)        │  │ (Standby)       │  │
│  └─────────┘                   │  │                 │  │                 │  │
│  ┌─────────┐                   │  │ writes to ──────┼──┼─► Shared NAS    │  │
│  │ SIP Trk │───────────────────┼─►│                 │  │                 │  │
│  │  (Sec)  │                   │  └─────────────────┘  └─────────────────┘  │
│  └─────────┘                   │                                             │
├────────────────────────────────┼─────────────────────────────────────────────┤
│  Finesse Servers (HA Pair)     │  CX Components                              │
│  ┌─────────┐  ┌─────────┐     │  ┌─────────────────┐  ┌─────────────────┐   │
│  │Primary  │◄►│Secondary│     │  │ cisco-connector │  │ cisco-connector │   │
│  │Finesse  │  │Finesse  │     │  │   (Node-A)      │  │   (Node-B)      │   │
│  └─────────┘  └─────────┘     │  │                 │  │                 │   │
│                                │  │ JTAPI listener  │  │ JTAPI listener  │   │
│                                │  │ Consul lock=✓   │  │ Consul lock=✗   │   │
│                                │  └─────────────────┘  └─────────────────┘   │
│                                │           │            │                     │
│                                │           └─────┬──────┘                     │
│                                │                 ▼                            │
│                                │         ┌─────────────┐                       │
│                                │         │   Consul    │                       │
│                                │         │   Server    │                       │
│                                │         └─────────────┘                       │
├────────────────────────────────┼─────────────────────────────────────────────┤
│  Docker Swarm Cluster          │                                             │
│  ┌─────────┐  ┌─────────┐     │                                             │
│  │ Manager │◄►│ Worker  │     │                                             │
│  │• Mixer  │  │• Mixer  │     │                                             │
│  │• REST   │  │• Archival│     │                                             │
│  └─────────┘  └─────────┘     │                                             │
└────────────────────────────────┴─────────────────────────────────────────────┘

---

17.11 Pause/Resume EFCX Call Recording

EFCX supports selective recording — the ability to pause and resume recording during a call based on business rules (e.g., PCI-DSS compliance for credit card collection, or agent-initiated privacy holds).

17.11.1 How Pause/Resume Works

The pause/resume mechanism operates at the FreeSWITCH ESL layer, not at the phone level. This means it works uniformly across all call types (inbound, outbound, consult, transfer) regardless of the endpoint device.

Agent triggers pause/resume
    │
    ▼ (via AgentDesk or API)
CX Unified Admin / CCM
    │
    ▼ (CIM message or API call)
Voice Connector (ecx_generic_connector)
    │
    ▼ (ESL command)
FreeSWITCH
    │
    ├─► Pause:  uuid_record <uuid> stop
    │     OR    uuid_broadcast <uuid> pause_recording
    │
    └─► Resume: uuid_record <uuid> start <file>
          OR    uuid_broadcast <uuid> resume_recording
    │
    ▼
Recording file contains audio ONLY for non-paused segments

Key ESL Commands:

17.11.2 FreeSWITCH Dialplan Configuration for Pause/Resume

Add bind_meta_app actions to the recording dialplan to enable DTMF-triggered pause/resume:

<!-- In the hairpin_and_record extension -->
<extension name="hairpin_and_record">
  <condition field="${sip_h_X-Return-Token}" expression="^(.+)$">
    <action application="export" data="sip_h_X-Return-Token=${sip_h_X-Return-Token}" />
    <action application="export" data="_nolocal_jitterbuffer_msec=100"/>
    <action application="set" data="RECORD_STEREO=true"/>
    <action application="record_session" data="/tmp/mytestingfile.wav"/>
    <!-- DTMF-triggered pause/resume -->
    <action application="bind_meta_app" data="2 ab s lua::prtask_pause.lua"/>
    <action application="bind_meta_app" data="3 ab s lua::prtask_resume.lua"/>
    <action application="bridge" data="sofia/external/${destination_number}@${network_addr}"/>
  </condition>
</extension>

Lua Pause Script (/usr/share/freeswitch/scripts/prtask_pause.lua):

local filename = "/tmp/mytestingfile.wav";
freeswitch.consoleLog("INFO", "==============================================Pausing recording")
session:execute("record_session_pause", filename)

Lua Resume Script (/usr/share/freeswitch/scripts/prtask_resume.lua):

local filename = "/tmp/mytestingfile.wav";
freeswitch.consoleLog("INFO", "==============================================Resuming recording")
session:execute("record_session_resume", filename)

Usage:

- Press *2 from any endpoint to pause recording

- Press *3 from any endpoint to resume recording

- Run reloadxml in fs_cli after dialplan changes

17.11.3 Programmatic Pause/Resume via ESL

The Voice Connector (ecx_generic_connector) can programmatically control recording via the mod_event_socket interface:

// Pseudo-code from VcService flow
String uuid = session.getVariable("uuid");

// Pause recording

eslConnection.sendCommand("uuid_record " + uuid + " stop");

// Resume recording (same file)

eslConnection.sendCommand("uuid_record " + uuid + " start /app/files/wav/" + filename);

```

CCM Integration:

A PAUSE_RECORDING or RESUME_RECORDING intent can be sent from CCM to the Voice Connector via the standard CIM message bus. The connector translates this to the appropriate ESL command.

17.11.4 Compliance Considerations

Audit Trail: When pause/resume is triggered, the system should log:

- Timestamp of pause and resume events

- Agent/extension who triggered it

- Reason code (if provided)

- Resulting recording file(s) and their durations

---

17.12 Screen Recording for Cisco Configuration and Deployment Guide

Screen recording complements voice recording by capturing the agent's desktop activity during a call. This is essential for quality management, compliance verification, and agent coaching.

17.12.1 Architecture Overview

Agent Workstation
    │
    ├─► Cisco Phone (BiB) ──► Voice Recording Stream ──► FreeSWITCH / Eleveo
    │
    └─► Desktop
          │
          ├─► Finesse Agent Desktop (browser)
          │     └── Screen Recording Gadget (JavaScript)
          │
          └─► Screen Recording Controller (Controller.exe)
                │
                ▼
          Local Screen Capture
                │
                ▼
          SFTP Upload ──► Recording Server (/app/files/screen/)
                │
                ▼
          CX Recording Middleware
                │
                ▼
          CCM Third Party Activity (SCREEN_RECORDING)

17.12.2 Finesse Screen Recording Gadget

The Finesse gadget is a JavaScript widget embedded in the Cisco Finesse agent desktop. It:

1. Detects when the agent is on an active call (via Finesse event API)

2. Signals the local Controller.exe to start/stop screen capture

3. Displays recording status to the agent

4. Submits metadata (call ID, agent ID, timestamp) alongside the recording

Gadget Configuration:

<!-- Finesse desktop layout XML snippet -->
<gadgets>
  <gadget>
    <url>https://<recording-server>/screen-recording-gadget/gadget.xml</url>
    <height>100</height>
    <title>Screen Recording</title>
  </gadget>
</gadgets>

17.12.3 Screen Recording Controller (Controller.exe)

The Controller is a Windows-native application installed on each agent workstation.

Responsibilities:

PowerShell Configuration Script (deployed per workstation):

# screen-recording-config.ps1
$Config = @{
    ServerAddress = "192.168.1.100"
    SFTPPort = 22
    SFTPUsername = "screenuser"
    SFTPKeyPath = "C:\\ScreenRec\\keys\\id_rsa"
    UploadPath = "/app/files/screen/"
    CaptureFPS = 5
    VideoCodec = "H.264"
    Resolution = "1920x1080"
    StartOnCallAnswer = $true
    StopOnCallEnd = $true
    LocalBufferPath = "C:\\ScreenRec\\buffer\\"
}
Export-ModuleMember -Variable Config

17.12.4 SFTP Server Setup

The recording server hosts an SFTP endpoint for receiving screen recordings:

# On Debian/Ubuntu recording server
sudo apt install openssh-server
sudo groupadd sftpusers
sudo useradd -m -G sftpusers screenuser
sudo mkdir -p /app/files/screen
sudo chown root:root /app
sudo chown screenuser:sftpusers /app/files/screen
sudo chmod 755 /app/files/screen

Configure sshd for chroot SFTP

17.12.5 File Naming & Storage

Screen recordings follow a naming convention linking them to voice recordings:

/screen/
  └── <date>/
        └── <dialogId>_<agentExtension>_<timestamp>.mp4

Example: 550e8400-e29b-41d4-a716-446655440000_5001_1718000000.mp4

17.12.6 Screen Recording Link Activity

Similar to voice recording links, screen recordings are pushed to CCM:

// CIM Message for screen recording
{
  "header": {
    "intent": "SCREEN_RECORDING",
    "sender": { "type": "CONNECTOR", "senderName": "CX-Screen-Recording-Link" },
    "channelSessionId": "<channelSessionId>"
  },
  "body": {
    "legId": "<legId>",
    "screenRecordingUrl": "https://middleware/{legId}/screen-recording-file",
    "durationSeconds": 245,
    "resolution": "1920x1080"
  }
}

17.12.7 Bandwidth & Storage Considerations

Example: 100 agents, 8 hours/day, 5 days/week:

- Upload bandwidth: 100 × 1 Mbps = 100 Mbps upstream

- Weekly storage: 100 × 8 × 5 × 750 MB = ~3 TB/week

- Recommendation: Dedicated SFTP server with 1 Gbps NIC and 50+ TB NAS

---

17.13 BiB Compatible Cisco Phones

Built-in-Bridge (BiB) is a Cisco phone feature that creates a forked RTP stream of the call audio for recording purposes. BiB is the foundation of Cisco-native recording (used by Eleveo and other Cisco-compatible recorders).

17.13.1 How BiB Works

Customer ──► CUCM ──► Agent Phone
                          │
                          ├─► Normal audio path (agent headset/speaker)
                          │
                          └─► BiB fork ──► Recording stream ──► Eleveo Recorder
                                (separate RTP stream)

When BiB is enabled on a phone:

1. The phone creates a second RTP session (the BiB leg)

2. This leg carries a copy of the mixed audio (agent + customer)

3. CUCM routes the BiB leg to the configured recording server (SIP trunk)

4. The recording server receives and stores the audio

17.13.2 BiB-Compatible Phone Models

The following Cisco IP Phone models support Built-in-Bridge for recording. Phones running SCCP or SIP firmware are both supported, but SIP is preferred for newer deployments.

17.13.3 Enabling BiB on CUCM

Per-phone configuration in CUCM Administration:

1. Navigate to Device → Phone

2. Find the agent's phone

3. Set Built In Bridge = On

4. Set Recording Option = Automatic or Selective

5. Set Recording Profile to the recording server SIP trunk

6. Save and apply configuration

Phone Configuration XML (bulk provisioning):

<device>
  <phoneConfig>
    <builtInBridgeEnable>1</builtInBridgeEnable>
    <recordingOption>Automatic</recordingOption>
    <recordingProfile>
      <recordingCss>
        <partition>PT-Recording</partition>
      </recordingCss>
      <destination>recording-server.example.com</destination>
    </recordingProfile>
  </phoneConfig>
</device>

17.13.4 BiB vs. SPAN vs. SIPREC

Recommendation: Use BiB for Cisco UCCE/UCCX environments with compatible endpoints. Use SIPREC if the customer has a CUBE or third-party SBC. Use CX SIP Proxy Fork for pure CX-native deployments.

---

17.14 Solution Prerequisites & Hardware Sizing

Before deploying the CX Voice Recording Solution with Cisco, verify all hardware, software, and network prerequisites.

17.14.1 Recording Server Hardware Sizing

Formula for Storage Planning:

Total Daily Storage (GB) = Concurrent Calls × Hours/Day × Recording Bitrate (Mbps) × 3600 × 0.125

Where:

• Concurrent Calls = Expected peak simultaneous recorded calls

• Recording Bitrate = ~64 kbps (mono, 8 kHz, G.711) to ~128 kbps (stereo WAV)

• 0.125 = Conversion factor (Mbps → MB/s → GB/hour)

```

Storage Calculation Example:

Retention Planning:

17.14.2 Recording Server Specifications

17.14.3 SQL Server Requirements (UCCE / Historical DB)

17.14.4 Docker & Container Prerequisites

For deployments using Docker Swarm or Kubernetes (CX 4.8+):

17.14.5 FusionPBX Prerequisites (EFSwitch Backend)

17.14.6 Time Synchronization (NTP)

Accurate time synchronization is critical for recording correlation. All components must sync to the same NTP source:

# On all Linux servers (Debian/Ubuntu)
sudo apt install chrony
sudo systemctl enable chrony

/etc/chrony/chrony.conf

sudo systemctl restart chrony

```

Components requiring NTP sync:

- CUCM (internal NTP or external source)

- UCCE/UCCX Admin Workstation

- FreeSWITCH / FusionPBX

- cisco-connector VMs

- Recording server

- Agent workstations (for screen recording timestamp alignment)

Maximum allowed drift: < 1 second across all systems. Drift > 5 seconds will cause recording correlation failures.

---

17.15 Port Utilisation

The following network ports must be open for the CX Voice Recording Solution to function. This table covers CUCM, FreeSWITCH, recording servers, databases, and agent endpoints.

17.15.1 Core Recording Ports

17.15.2 Cisco Infrastructure Ports

17.15.3 CX & Middleware Ports

17.15.4 Firewall Rules Summary

# Example iptables rules for a recording server
sudo iptables -A INPUT -p tcp --dport 5060 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 5065 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 8021 -s 127.0.0.1 -j ACCEPT
sudo iptables -A INPUT -p udp --dport 16384:32768 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 22 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 443 -j ACCEPT
sudo iptables-save

---

17.16 Eleveo Recording Middleware Reference

The Eleveo Recording Middleware bridges CX with an existing Eleveo (Zoom Call Recording / Cisco-compatible) recording infrastructure. It is used when the customer already has an Eleveo deployment and wants CX to consume those recordings.

17.16.1 Typical Eleveo Deployment

17.16.2 Integration Flow

CX Unified Admin
    │ (configured with ELEVEO backend)
    ▼
Recording Middleware (ELEVEO profile)
    │
    ├─► Authenticates to Eleveo (JSESSIONID)
    ├─► Searches conversations by JTAPI_CISCO_ID metadata
    ├─► Downloads individual call legs
    ├─► Merges split legs (hold/retrieve/conference)
    │
    ▼
Returns merged audio file to requesting client

17.16.3 Middleware Configuration

# application.yml (recording-middleware)
recording:
  backend: ELEVEO
  eleveo:
    base-url: https://192.168.1.236
    username: admin
    password: zoomcallrec12345
    download-timeout: 30000

17.16.4 Known Limitations

---

17.17 Quality Management (QM) Deployment Guide

Quality Management (QM) is a CX add-on module that provides conversation evaluation, scoring, and agent coaching. It integrates with the recording infrastructure to allow supervisors to review voice (and optionally screen) recordings and score agent performance.

17.17.1 QM Architecture

┌──────────────┐     ┌─────────────┐     ┌──────────────┐
│   CX Core    │────►│  QM-Backend │────►│  QM-Frontend │
│  (CCM, MRE)  │     │  (PostgreSQL)│     │ (Angular UI) │
└──────────────┘     └─────────────┘     └──────────────┘
       │
       ▼
┌─────────────────────────────────────────────┐
│         Recording Middleware                  │
│    (EFSwitch or Eleveo backend)              │
└─────────────────────────────────────────────┘
       │
       ▼
┌─────────────────────────────────────────────┐
│  Cisco UCCE (awdb) ──► QM-Connector          │
│  (reads TCD, ACD for wrap-up codes)          │
└─────────────────────────────────────────────┘

17.17.2 Prerequisites

1. EF CX deployed with Cisco voice channel configured

2. Recording backend configured (EFSwitch or Eleveo)

3. CISCO_CC channels created in Unified Admin for both Inbound and Outbound

4. Outbound service identifier set as UCCE_OB_SERVICE_IDENTIFIER in values.yaml

5. Routing Mode = External

6. Channel Model = HYBRID

7. Keycloak user vrs created with all realm-management roles

17.17.3 QM-Connector Environment Variables

17.17.4 Deployment Commands

# Add Expertflow Helm repo
helm repo add expertflow https://expertflow.github.io/charts
helm repo update expertflow

Create QM database in Postgres

kubectl -n ef-external exec -it ef-postgresql-client -- bash

psql --host ef-postgresql -U sa postgres -p 5432

CREATE DATABASE qm_db;

\c qm_db;

CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

\q

Fetch and customize values

Deploy QM

17.17.5 Keycloak QM Roles

Two new roles are introduced by QM:

Import sequence:

1. Partial import quality-management-realm.json to create roles

2. Import quality-management-authz.json into the cim client Authorization tab

17.17.6 QM Limitations (as of CX 4.8)

---

Appendix: Repository Locations

All referenced source code is available in the following repositories:

---

This section documents every behavioral detail of the CX Voice + Cisco system, organized by component. It covers state machines, transition rules, edge cases, and recovery behaviors for both Cisco-side and EFCX-side components.

---

18.1 Agent State Machine & MRD Behavior

18.1.1 Cisco Finesse Agent States

Cisco Finesse maintains an independent agent state machine. The CX AgentDesk subscribes to Finesse events via BOSH (Bidirectional-streams Over Synchronous HTTP) and maps them to CX MRD (Media Routing Domain) states.

Finesse State Machine:

LOGOUT → LOGIN → NOT_READY → READY → RESERVED → TALKING → WORK → READY
                                    ↓                    ↓
                              RESERVED_OUTBOUND      WORK_READY
                                    ↓
                              TALKING (outbound)

Finesse States and Meanings:

18.1.2 CX MRD State Machine

The CX Routing Engine maintains its own MRD state per agent, synchronized with Finesse states.

NOT_READY ←──────┬──────→ READY
      ↑            │         ↓
      └────────────┘      RESERVED
                               ↓
                              BUSY
                               ↓
                         NOT_READY (after wrap-up)

State Transitions:

18.1.3 Hardcoded MRD and Channel Type

Critical Implementation Detail: The AgentDesk hardcodes the voice MRD name as "VOICE" (for pre-CX4.2) or "CISCO_CC" (for CX4.2+). This mapping is configured in the AgentDesk ConfigMap:

# ef-unified-agent-configmap.yaml
isCiscoEnabled: "true"
# The MRD name must match what's configured in Unified Admin
# For CX < 4.2: "VOICE"
# For CX >= 4.2: "CISCO_CC"

Behavioral Impact:

- If the MRD name in Unified Admin does not match the hardcoded value in AgentDesk, the agent state updates will fail silently

- The AgentDesk identifies active voice channel sessions by the "VOICE" channel type name

- On leaving a conversation with an active voice channel session, the client must send the hangup command to the correct voice platform

18.1.4 Agent State Change Flow

Agent clicks "Make Ready" in UI
│
▼
Angular emits changeAgentState event
│
▼
cti.service.ts sends state change to Finesse via BOSH
  PUT /finesse/api/User/{agentId}
  { state: "READY" }
│
▼
Finesse updates agent state in CUCM
│
▼
Finesse publishes state change via XMPP BOSH
  <Update>
    <user>
      <state>READY</state>
      <stateChangeTime>2026-06-08T10:00:00.000Z</stateChangeTime>
    </user>
  </Update>
│
▼
AgentDesk cti.service.ts receives XMPP update
│
▼
Maps Finesse state to CX MRD state
│
▼
Emits agentStateChanged event to Angular
│
▼
Angular updates UI (Ready button green, timer starts)
│
▼
Sends AGENT_STATE_CHANGED to CCM via REST API
  POST /conversation-manager/channel-session/agent-state
  { agentId, mrdId, state: "READY" }
│
▼
CCM updates agent MRD state
│
▼
Routing Engine receives AGENT_STATE_CHANGED event
  → Agent is now eligible for task assignment

---

18.2 Complete Call Control Behaviors

18.2.1 Hold Call

Trigger: Agent clicks "Hold" button in Agent Desktop UI.

Cisco-side Behavior:

```

Agent clicks HOLD

│

▼

sip.service.ts → postMessages({action: "holdCall", parameter: {dialogId}})

│

▼

sip-wrapper.js hold_call(dialogId):

1. Finds session in calls[] by dialogId

2. Calls session.invite({

requestDelegate: {

onAccept: () => { / hold accepted / }

}

})

3. SIP re-INVITE sent to FreeSWITCH with SDP indicating hold

(sendonly/inactive direction in SDP)

│

▼

FreeSWITCH receives re-INVITE

→ Bridges customer to hold music (MOH)

→ Agent leg is parked

│

▼

JTAPI event: CallCtlTermConnHeldEv

→ Cisco Connector receives event

→ Persists to jtapi_event table

→ CorrelationService processes → creates CALL_HOLD CIM

│

▼

Cisco Connector sends CALL_HOLD to CCM

│

▼

CCM updates channel session state

│

▼

Angular UI shows "On Hold" with resume timer

```

EFCX-side Recording Behavior:

- FreeSWITCH uuid_record continues writing to file

- Hold music (MOH) audio is mixed into the recording

- For Eleveo: BiB continues streaming; hold music is recorded

- For EFSwitch: The recording file contains the hold music segment

Post-Hold State:

| Component | State After Hold |

|---|---|

| Finesse | TALKING (unchanged) |

| CX MRD | BUSY (unchanged) |

| SIP.js session | Established (re-INVITE with hold SDP) |

| FreeSWITCH bridge | Customer → MOH, Agent leg parked |

| Recording | Continues (includes MOH) |

18.2.2 Retrieve Call (Resume from Hold)

Trigger: Agent clicks "Resume" button.

Agent clicks RESUME
│
▼
sip.service.ts → postMessages({action: "retrieveCall", parameter: {dialogId}})
│
▼
sip-wrapper.js retrieve_call(dialogId):
  1. Finds session in calls[]
  2. Sends re-INVITE with normal SDP (sendrecv)
│
▼
FreeSWITCH receives re-INVITE
  → Unparks agent leg
  → Re-bridges customer and agent
  → Stops MOH
│
▼
JTAPI event: CallCtlTermConnTalkingEv
  → Cisco Connector → CALL_RESUME CIM → CCM
│
▼
Angular UI shows "On Call" (hold timer stops)

Recording Implications:

- EFSwitch: Recording continues seamlessly in same file

- Eleveo: Recording may split on hold/retrieve (middleware merges legs)

18.2.3 Blind Transfer (Single Step Transfer - SST)

Trigger: Agent selects transfer target and clicks "Transfer" without consulting.

Agent A (1005) is on call with Customer
│
▼
Agent A clicks Transfer → selects Agent B (1006)
│
▼
sip.service.ts → postMessages({action: "transferCall", parameter: {dialogId, to: "1006"}})
│
▼
sip-wrapper.js transfer_call(dialogId, target):
  1. Finds session in calls[]
  2. SIP REFER sent to FreeSWITCH
     Refer-To: <sip:1006@expertflow>
     Referred-By: <sip:1005@expertflow>
│
▼
FreeSWITCH processes REFER:
  1. Receives REFER from Agent A
  2. Sends 202 Accepted to Agent A
  3. Initiates new INVITE to Agent B on behalf of Customer
  4. When Agent B answers, bridges Customer to Agent B
  5. Hangs up Agent A leg
│
▼
Agent A receives NOTIFY: sipfrag;status=200
  → sip-wrapper.js: dialog.state = DROPPED
  → callback to Angular
│
▼
Angular: handleDialogDroppedEvent()
  → CALL_LEG_ENDED sent to CCM
│
▼
CCM: Conversation remains active (new leg started)
│
▼
JTAPI events:
  - ConnDisconnectedEv on Agent A leg
  - ConnConnectedEv on Agent B leg
  - CiscoTransferStartEv
│
▼
Cisco Connector correlates events
  → CallType = DIRECT_TRANSFER
  → Creates CALL_LEG_ENDED for Agent A
  → Creates CALL_LEG_STARTED for Agent B

Key Behavioral Details:

- The customer experiences a brief silence/blind transfer (no consult)

- Agent A is immediately dropped from the call

- If Agent B does not answer, the call may go to voicemail or RONA

- Recording: For EFSwitch, the recording continues with the same file (same UUID)

- For Eleveo, a new recording leg is created for Agent B

18.2.4 Consult Transfer (Two-Step Transfer)

Trigger: Agent clicks "Consult" → dials target → talks → clicks "Complete Transfer".

Phase 1: Consult Call Initiation

```

Agent A on call with Customer

│

▼

Agent A clicks Consult → enters Agent B extension

│

▼

sip.service.ts → postMessages({action: "consultCall", parameter: {dialogId, consultTo: "1006"}})

│

▼

sip-wrapper.js consult_call(dialogId, target):

1. Creates new SIP.Inviter for consult call

2. Sets SIP headers:

- X-Calltype: CONSULT

- X-Consult-Parent-Dialog: <originalDialogId>

3. Sends INVITE to FreeSWITCH

│

▼

FreeSWITCH processes consult INVITE

→ Creates new B-leg for consult call

→ Customer is put on hold (or remains bridged to Agent A)

│

▼

Agent B receives consult call INVITE

→ Dialog shows "Consult from 1005"

│

▼

JTAPI events:

- CiscoConsultCallActiveEv (new consult call)

- CallCtlTermConnHeldEv on original call (if customer put on hold)

```

Phase 2: Consult Call Active

```

Agent B answers consult call

│

▼

Agent A and Agent B are talking

Customer is on hold (hearing MOH)

│

▼

JTAPI: ConnConnectedEv on consult leg

```

Phase 3: Complete Transfer

```

Agent A clicks "Complete Transfer"

│

▼

sip.service.ts → postMessages({action: "completeTransfer", parameter: {dialogId, consultDialogId}})

│

▼

sip-wrapper.js:

1. Sends BYE to consult leg (Agent A ↔ Agent B)

2. SIP REFER on original leg to transfer customer to Agent B

│

▼

FreeSWITCH:

1. Bridges Customer to Agent B

2. Hangs up Agent A

│

▼

Customer is now connected to Agent B

Agent A is dropped

│

▼

JTAPI events:

- CiscoTransferStartEv

- ConnDisconnectedEv on Agent A leg

- ConnConnectedEv on Agent B leg (now primary)

│

▼

Cisco Connector:

→ CallType = CONSULT_TRANSFER

→ Original leg ended (Agent A)

→ New leg started (Agent B)

→ Consult leg is closed

```

Key Behavioral Details:

- The consult call is a separate SIP dialog with its own UUID

- FreeSWITCH may or may not put the customer on hold during consult

- If Agent B rejects the consult, Agent A can click "Cancel Consult" and return to the customer

- Recording: For EFSwitch, consult calls may have separate recording files

- For Eleveo, consult audio is typically NOT recorded (BiB only records primary call)

18.2.5 Conference

Trigger: Agent clicks "Conference" → dials participant → clicks "Merge".

Phase 1: Conference Initiation

```

Agent A on call with Customer

│

▼

Agent A clicks Conference → dials Agent B

│

▼

Same as consult call initiation

→ New consult leg created

→ Customer on hold

```

Phase 2: Merge (Conference Active)

```

Agent A clicks "Merge"

│

▼

FreeSWITCH creates three-way bridge:

Customer ↔ Agent A ↔ Agent B

│

▼

All three parties can hear each other

│

▼

JTAPI events:

- CiscoConferenceStartEv

- All legs linked under same conference callId

│

▼

Cisco Connector:

→ CallType = CONFERENCE

→ All conference participants linked to same conversation

```

Phase 3: Conference End

```

Any participant hangs up

│

▼

If Customer hangs up:

→ Conference ends for all

→ All agents dropped

│

▼

If Agent A hangs up:

→ Agent B and Customer remain connected

→ Conference becomes regular two-party call

│

▼

JTAPI: CiscoConferenceEndEv

```

Recording Behavior:

- EFSwitch: Records the entire conference as a single file (mixed audio)

- Eleveo: Each agent's BiB records separately; middleware must merge

---

18.3 CCM Conversation Lifecycle

18.3.1 Conversation State Machine

The CCM (Conversation Manager) maintains a conversation object that represents the entire customer interaction across all channels.

CREATED → ACTIVE → CLOSED
   ↓        ↓        ↓
(queued) (talking) (ended)

State Definitions:

18.3.2 Channel Session Lifecycle

Each voice call creates a channel session within the conversation:

INITIATED → ALERTING → ACTIVE → ENDED
    ↓           ↓         ↓        ↓
(call     (ringing   (talking  (hangup
 created)  on agent)  started)  complete)

Channel Session State Transitions:

18.3.3 Conversation Creation Flow

Voice Connector sends ASSIGN_RESOURCE_REQUESTED
│
▼
CCM receives CIM message
│
▼
CCM.ActivityService.createConversation():
  1. Creates Conversation object
  2. Generates conversationId (UUID)
  3. Sets channelType = "VOICE" / "CISCO_CC"
  4. Sets customerIdentifier = callingNumber
  5. Sets serviceIdentifier = DN
  6. Creates ChannelSession:
     - channelSessionId = UUID
     - channelType = VOICE
     - state = INITIATED
     - direction = INBOUND/OUTBOUND
  7. Persists to database
│
▼
CCM sends AssignResourceRequest to Routing Engine
│
▼
Routing Engine creates Task and enqueues

18.3.4 Conversation Closure Flow

CCM receives CALL_LEG_ENDED
│
▼
CCM.ActivityService.processLegEnded():
  1. Finds channel session by callId
  2. Updates channelSession.state = ENDED
  3. Checks if ALL channel sessions are ended
│
▼
If all sessions ended:
  1. Updates Conversation.state = CLOSED
  2. Calculates total duration
  3. Publishes CONVERSATION_ENDED event
  4. Triggers wrap-up flow if configured
│
▼
Routing Engine receives CONVERSATION_ENDED
  → TaskManager.changeStateOnMediaClose()
  → Updates agent MRD state

Wrap-up Behavior:

- If autoWrapUp = true in MRD config: Agent goes to WORK state for configured duration

- If autoWrapUp = false: Agent immediately becomes READY (if no other tasks)

- Wrap-up timer is enforced by Routing Engine

- During wrap-up, agent cannot receive new tasks

---

18.4 Routing Engine Task State Machine

18.4.1 Task Lifecycle

The Routing Engine manages tasks that represent work items to be assigned to agents.

QUEUED → RESERVED → ACTIVE → COMPLETED
  ↓         ↓         ↓          ↓
(waiting (agent    (agent    (work
 in queue) selected) talking)  done)

Task State Definitions: