CX Voice Connector & Outbound Dialer — Architecture Guide

                              OUTBOUND DIALER
                                   |
                                   | POST /agent
                                   v
+----------------+     +----------------------+     +------------------+
|   Campaign     |     |   Voice Connector    |     |   FreeSWITCH     |
|   Manager      |     |   (ecx_generic_)     |     |   (Media Server) |
| (Upload List)  |     |                      |     |                  |
+----------------+     | InboundController    |     |  vcApi.lua       |
        |              |  /request-agent      |     |  consult_conf.lua|
        | POST /contact|  /cancel-agent       |     |  cx_hangup.lua   |
        v              |  /end-chat           |     |  customTransfer  |
+----------------+     |                      |     |  agent_amd       |
| Outbound Dialer|     | OutboundController   |     |                  |
| (Spring Boot)  |     |  /ccm-msg/receive    |     +--------+---------+
|                |     |                      |              |
| -- Contacts DB  |     +----------+-----------+              | SIP
| -- ESL originate|                |                          |
| -- Agent resv   |        CIM Msg | REST                     |
+----------------+                v                          v
                                  |                   +------+------+
                          +-------v--------+          |  Customer   |
                          |      CCM       |          |  / Agent    |
                          | (Conv. Mgr)    |          +-------------+
                          +-------+--------+
                                  |
                          +-------v--------+
                          | Routing Engine |
                          | (Task/Queue)   |
                          +----------------+

ecx_generic_connector/src/main/java/com/ef/mregc/
|-- commons/Constants.java
|-- config/GlobalProperties.java
|-- controller/
|   |-- InboundController.java      # Receives from FreeSWITCH / Dialer
|   |-- OutboundController.java     # Receives from CCM
|-- dto/
|   |-- AgentDetails.java           # {agentExtension, uuid, queueName}
|   |-- CallDetails.java            # Full call metadata
|   |-- ContactDto.java             # Dialer contact
|   |-- DeliveryNotificationDetails.java
|   |-- EndChatDetails.java
|   |-- Response.java
|-- model/ContactEntity.java
|-- services/
    |-- VcService.java              # Core logic
    |-- VcServiceInterface.java
    |-- VoicemailService.java
    |-- RestUtil.java               # HTTP client

@PostMapping("/request-agent")
public ResponseEntity<Object> sendAgentRequest(@RequestBody @Valid CallDetails requestBody) {
    return vcService.requestAgent(requestBody);
}

GenericMessage body = new GenericMessage("ASSIGN_RESOURCE_REQUESTED");
body.setAdditionalDetail("callId", id);           // SIP Call-ID (inbound) or FS UUID (outbound)
body.setAdditionalDetail("direction", direction);  // "INBOUND" or "OUTBOUND"
body.setAdditionalDetail("mode", "QUEUE");         // Always QUEUE
body.setAdditionalDetail("metadata", metaData);    // {uuid, eslHost}
body.setAdditionalDetail("resource", resource);    // {type: "NAME"/"ID", value: queueName}
body.setAdditionalDetail("priority", priority);

private CimMessage createAgentRequestCancelPayload(CallDetails callDetails) {
    GenericMessage body = new GenericMessage("CANCEL_RESOURCE_REQUESTED");
    body.setAdditionalDetail("callId", id);
    body.setAdditionalDetail("direction", direction);
    body.setAdditionalDetail("requestType", "VOICE");
    body.setAdditionalDetail("reasonCode", callDetails.getErrorCode());
    return new CimMessage(header, body);
}

private CimMessage createDeliveryNotificationPayload(DeliveryNotificationDetails dto) {
    DeliveryStatus status = reasonCode.equalsIgnoreCase("NORMAL_CLEARING")
        ? DeliveryStatus.CONNECTED : DeliveryStatus.FAILED;

@PostMapping("/ccm-msg/receive/cim-messages")
public ResponseEntity<Object> receiveCimMessage(@RequestBody @Valid CimMessage cimMessage) {
    String type = cimMessage.getBody().getType();

public ResponseEntity<Object> routeAgent(String messageId, String eslHost, String customerNumber,
                                         String serviceId, String direction, String callUuid,
                                         String mode, String agentExtension, String queueName) {

public void handleAgentForInbound(String agentExtension, String eslHost, String uuid,
                                   String queueName, String customerId, String serviceIdentifier) {
    // 1. Connect ESL to FreeSWITCH
    if (!inboundClient.canSend()) {
        inboundClient.connect(new InetSocketAddress(eslHost, eslPort), eslPass, 10);
    }

public void handleAgentForOutbound(String agentExtension, String uuid, String queueName,
                                    String customerId, String serviceIdentifier) {
    if (agentExtension.isEmpty()) {
        sendEndChat(new EndChatDetails(customerId, serviceIdentifier));
        return;
    }

if (globalProperties.isAuthEnabled()) {
    String token = getCachedToken(domain);
    if (token == null) {
        token = requestNewToken();
        cacheToken(domain, token);
    }
    params.setToken(token);
    
    int status = restUtil.sendRequest(params).statusCode();
    if (status == 401) {
        removeCachedToken(domain);
        String newToken = requestNewToken();
        cacheToken(domain, newToken);
        params.setToken(newToken);
        status = restUtil.sendRequest(params).statusCode();
    }
}

[Campaign Manager / Admin UI]
    |
    | Uploads contact list, configures campaign
    v
[Outbound Dialer (Spring Boot)]
    |
    | -- Stores contacts in PostgreSQL
    | -- Schedules dialing (cron job)
    | -- Respects maxConcurrentCalls, callsPerSecond
    v
[DialerService -- retrieveContacts()]
    |
    | For each tenant:
    |   1. Get pending contacts
    |   2. Check gateway status: sofia status gateway {gatewayId}
    |   3. Build originate command
    v
[FreeSWITCH -- originate command]
    |
    | Command format:
    | {sip_h_X-Call-Id={id}, session_in_hangup_hook=true,
    |  domain_name={tenant}, record_session=true,
    |  sip_h_X-Destination-Number={serviceIdentifier},
    |  call_direction=outbound, origination_uuid={id}}
    | sofia/gateway/{gatewayId}/{customerNumber}
    | {ivrScript} XML {tenant}
    v
[Customer answers]
    |
    v
[Voice Connector -- /request-agent]
    |
    | Sends ASSIGN_RESOURCE_REQUESTED to CCM
    | Direction = "OUTBOUND"
    v
[CCM -> Routing Engine]
    |
    | Finds available agent
    v
[AGENT_RESERVED]
    |
    | Voice Connector -> Dialer API: POST /agent
    | { agentExtension, uuid, queueName }
    v
[DialerService -- dialAgent()]
    |
    | Builds originate command to connect agent to customer
    | { ... sip_h_X-agentExtension={ext} ... }
    | sofia/gateway/{gatewayId}/{customerNumber} agent XML {tenant}
    v
[FreeSWITCH]
    |
    | Bridges agent and customer

CREATE TABLE contacts (
    id                  VARCHAR PRIMARY KEY,
    customer_number     VARCHAR NOT NULL,
    campaign_type       VARCHAR,
    ivr                 VARCHAR,
    gateway_id          VARCHAR NOT NULL,
    status              VARCHAR,
    call_result         VARCHAR,
    received_time       TIMESTAMP,
    dial_time           TIMESTAMP,
    campaign_id         VARCHAR,
    campaign_contact_id VARCHAR,
    start_time          TIMESTAMP,
    end_time            TIMESTAMP,
    priority            INT DEFAULT 0,
    dialing_mode        VARCHAR,
    routing_mode        VARCHAR,
    resource_id         VARCHAR,
    queue_name          VARCHAR,
    tenant_id           VARCHAR NOT NULL,
    scheduling_metadata JSONB
);

UPLOAD          DIAL              ANSWER            AGENT RESERVED      HANGUP
  |              |                  |                    |                |
  v              v                  v                    v                v
pending ------> dialed --------> (IVR playing) ----> agent_pending ---> ended
  |              |                  |                    |                |
  |              | (Gateway DOWN)   | (AMD = MACHINE)    | (No agent)     |
  |              v                  v                    v                |
  |           pending            ended (AMD)       ended (NO_AGENT)      |
  |              |                                                     |
  |              | (Gateway INVALID)                                    |
  |              v                                                     |
  |            failed                                                  |
  |                                                                     |
  |<--------------------------------------------------------------------|
  |         (10-min cleanup resets old dialed/agent_pending -> pending)
  |
  v
stopped  <--- Campaign stop action

ESL: sofia status gateway {gatewayId}

try {
    sendOriginateCommand(command);
    currentCalls.incrementAndGet();
    contactRepository.updateContactStatus(id, "dialed", now(), tenantId);
} catch (Exception e) {
    contactRepository.updateContactStatus(id, "failed", now(), tenantId);
    log.error("COULDN'T DIAL...", e);
}

String callResult = event.getEventHeaders().get("variable_hangup_cause");

private void amdResultHandler(EslEvent event) {
    if (event.getEventHeaders().get("Event-Subclass").equalsIgnoreCase("amd::done")) {
        String amdResult = event.getEventHeaders().get("variable_amd_result");
        if (!amdResult.equalsIgnoreCase("HUMAN")) {
            amdResult = "ANSWERING_MACHINE";
        }
        sendCallEventToWebhook(id, amdResult, tenantId);
    }
}

// if (!amdResult.equalsIgnoreCase("HUMAN")) {
//     sendEfswitchApiCommand("uuid_kill", id);
// }

String agentExt = agentDetails.agent();   // e.g. "201"
String uuid = agentDetails.uuid();        // Call UUID
String queue = agentDetails.queue();      // e.g. "SalesQueue"

public void sendOriginateCommand(String command) {
    CallConfigs callConfigs = settings.getTenantDialerConfigs().get(tenantId);
    long millisecPerCall = 1000 / callConfigs.getCallsPerSecond();
    
    if (lastOriginatedTime == -1) {
        lastOriginatedTime = System.currentTimeMillis();
    } else {
        long currentTime = System.currentTimeMillis();
        long diff = currentTime - lastOriginatedTime;
        if (diff < millisecPerCall) {
            Thread.sleep(millisecPerCall - diff);  // Throttle
        }
    }
    
    inboundClient.sendBackgroundApiCommand("originate", command);
    lastOriginatedTime = System.currentTimeMillis();
}

AtomicInteger currentCalls = getTenantCounter(tenantId);
int freeCallSlots = callConfigs.getMaxConcurrentCalls() - currentCalls.get();

@Scheduled(fixedDelay = 10, timeUnit = TimeUnit.MINUTES)
public void clearOldContactsForAllTenants() {
    // For each tenant:
    // 1. Find contacts with status='agent_pending' OR 'dialed'
    //    AND dial_time < (now - maxCallTime minutes)
    // 2. Send END_CHAT for agent-based contacts
    // 3. Reset status back to 'pending' (batch update, 100 at a time)
}

private void sendCallEventToWebhook(String id, String event, String tenantId) {
    Optional<ContactEntity> contact = contactRepository.findById(id);
    JSONObject schedulingMetadata = new JSONObject(contact.get().getSchedulingMetadata());
    String webhookUrl = schedulingMetadata.get("callEventsWebhookUrl").toString();
    
    CallProgressEvent requestBody = new CallProgressEvent(
        id,
        contact.get().getSchedulingMetadata(),
        id,           // messageId
        event,        // "HUMAN" or "ANSWERING_MACHINE"
        dialerUrlForRequests
    );
    
    restUtil.sendPostRequest(webhookUrl, requestBody, tenantId);
}

// Per-tenant configuration stored in-memory
Map<String, CallConfigs> tenantDialerConfigs = new HashMap<>();

@PostConstruct
@Scheduled(fixedDelayString = "${connectDelay}", timeUnit = TimeUnit.SECONDS)
public void connectEsl() {
    inboundClient.connect(new InetSocketAddress(eslIp, eslPort), eslPass, 10);
    inboundClient.setEventSubscriptions(
        IModEslApi.EventFormat.PLAIN, 
        "CHANNEL_DESTROY GENERAL"
    );
}

private void sendCallResults(String id, String callResult, String customerNum, String tenantId) {
    DeliveryNotificationDetails requestBody = new DeliveryNotificationDetails(
        id,                           // Call UUID
        callConfigs.getServiceIdentifier(),
        customerNum,
        callResult                    // e.g. "NORMAL_CLEARING", "NO_ANSWER"
    );
    
    // POST to Voice Connector /send-delivery-notification
    restUtil.sendPostRequest(
        voiceConnector + "/send-delivery-notification", 
        requestBody, 
        tenantId
    );
}

Contact Upload
    |
    v
+-----------------+
| Gateway Check   |--DOWN--> status=failed, call_result=GATEWAY DOWN
| (sofia status)  |          send delivery notification
+-----------------+
    |
   UP
    v
+-----------------+
| Originate       |--Exception--> status=failed, call_result=null
| (bgapi)         |               log error
+-----------------+
    |
   OK
    v
+-----------------+
| Customer Answers|
| AMD runs        |--MACHINE--> send webhook (external decides)
|                 |              status stays dialed/agent_pending
+-----------------+
    |
  HUMAN
    v
+-----------------+
| Agent Request   |--Fail (no agent)--> status=ended, call_result=NO_AGENT_AVAILABLE
| to Voice Conn.  |
+-----------------+
    |
  AGENT_RESERVED
    v
+-----------------+
| Agent Answers   |--Fail--> status=ended, call_result=hangup_cause
| Call Completes  |
+-----------------+
    |
   OK
    v
+-----------------+
| CHANNEL_DESTROY |--> status=ended, call_result=NORMAL_CLEARING
| or other cause  |    (or NO_ANSWER, USER_BUSY, etc.)
+-----------------+
    |
    v
Delivery Notification -> Voice Connector

                         +------------------+
                         |   Outbound Dialer |
                         |   (Spring Boot)   |
                         +--------+---------+
                                  |
                                  | POST /agent
                                  | {agentExtension, uuid, queue}
                                  v
+------------------+     +------------------+     +------------------+
|   FreeSWITCH     |     | Voice Connector  |     |       CCM        |
|   (Lua Scripts)  |     | (Spring Boot)    |     | (Conv. Manager)  |
+------------------+     +--------+---------+     +------------------+
         |                        |                        |
         | HTTP POST              | HTTP POST              | ActiveMQ
         | /request-agent         | /message/receive       |
         | /cancel-agent          |                        |
         v                        v                        v
    FreeSWITCH              Voice Connector            Routing Engine
    originates              creates CIM                reserves agent
    call                    messages                   
         |                        ^                        |
         | CHANNEL_DESTROY        | AGENT_RESERVED         |
         | (hangup cause)         |                        |
         +------------------------+------------------------+
                                  |
                                  | POST /ccm-msg/receive
                                  | (from Routing Engine)
                                  v
                           Voice Connector
                           routes to:
                           - Inbound: ESL uuid_transfer
                           - Outbound: POST /agent to Dialer

Customer (PSTN)
    |
    v
SIP Gateway -> FreeSWITCH (INVITE to destination_number)
    |
    v
FreeSWITCH dialplan matches -> executes vcApi.lua
    |
    v
vcApi.lua: request_agent(serviceIdentifier, "INBOUND", queue, queueType, ...)
    |
    v
HTTP POST -> Voice Connector /request-agent
    |
    v
VcService.requestAgent() -> createAgentRequestPayload()
    |
    v
HTTP POST -> CCM /message/receive
    CIM intent: ASSIGN_RESOURCE_REQUESTED
    body.callId = callSipId (SIP Call-ID)
    body.direction = "INBOUND"
    |
    v
CCM MessageProcessor -> createChannelSession -> publish ChannelSessionStarted
    -> publish FindAgentEvent to conversation topic
    |
    v
ActiveMQ -> Routing Engine (MRE)
    Task created: PENDING -> QUEUED -> RESERVED
    |
    v
MRE -> AGENT_RESERVED notification
    |
    v
ActiveMQ -> CCM OutboundController
    -> Voice Connector /ccm-msg/receive/cim-messages
    |
    v
VcService.routeAgent() -> handleAgentForInbound()
    |
    v
ESL: uuid_setvar_multi (queue headers)
    ESL: uuid_transfer {uuid} {agentExtension} XML {domain}
    |
    v
FreeSWITCH bridges call to agent's SIP endpoint
    |
    v
Agent Desk Wrapper (SIP.js) receives INVITE
    -> postMessage to Angular: dialogState="confirmed"
    |
    v
sip.service.ts handleCallActiveEvent()
    -> Creates CALL_LEG_STARTED CIM message
    -> POST to CCM /message/receive
    |
    v
CM CallLegStartedEvent -> assignAgentAction()
    -> Agent assigned to conversation
    -> Conversation state = ACTIVE

Campaign Manager
    |
    v
POST /contact -> Outbound Dialer
    Contact saved: status="pending"
    |
    v
dialAgentAmd(contact)
    |
    v
ESL: originate {vars} sofia/gateway/{gw}/{customerNumber} agent_amd XML {tenant}
    |
    v
FreeSWITCH calls customer
    |
    v
Customer answers
    -> agent_amd dialplan runs AMD
    |
    v
AMD = HUMAN
    |
    v
Dialer: sendAgentRequest(contact)
    |
    v
POST {voiceConnector}/request-agent
    {
      callingNumber: customerNumber,
      callUid: id,
      direction: "OUTBOUND",
      serviceIdentifier: serviceIdentifier,
      queue: queueName,
      queueType: "NAME"
    }
    |
    v
Voice Connector -> CCM
    CIM: ASSIGN_RESOURCE_REQUESTED
    callId = callUid (FS UUID, not SIP Call-ID)
    direction = "OUTBOUND"
    |
    v
CCM -> Routing Engine -> AGENT_RESERVED
    |
    v
Voice Connector -> POST /agent to Outbound Dialer
    { agentExtension: "201", uuid: "...", queue: "SalesQueue" }
    |
    v
Dialer: dialAgent(agentDetails)
    |
    v
ESL: originate {vars} sofia/gateway/{gw}/{customerNumber} agent XML {tenant}
    (bridges agent to existing customer call)
    |
    v
Agent answers, talks to customer
    |
    v
Hangup -> CHANNEL_DESTROY
    -> hangupCallHandler(): status="ended", call_result=NORMAL_CLEARING
    -> sendCallResults() -> Voice Connector /send-delivery-notification
    -> Voice Connector -> CCM

Outbound Dialer -> originate
    |
    v
FreeSWITCH calls customer
    |
    v
Customer does NOT answer
    |
    v
FreeSWITCH hangs up
    -> CHANNEL_DESTROY event
    -> variable_hangup_cause = "NORMAL_CLEARING"
    -> Caller-Channel-Answered-Time = "0"
    |
    v
Dialer hangupCallHandler()
    -> Detects: answered=0 + NORMAL_CLEARING
    -> Maps to: callResult = "NO_ANSWER"
    -> contactRepository.setCallResult(id, "ended", "NO_ANSWER")
    -> sendCallResults(id, "NO_ANSWER", customerNum, tenantId)
    -> decrementCallCounter()
    |
    v
Voice Connector /send-delivery-notification
    -> Creates CIM DeliveryNotification
    -> Status = FAILED (not NORMAL_CLEARING)
    -> POST to CCM /message/receive
    |
    v
CCM -> Conversation ends
    -> No agent was ever involved
    -> VoiceActivity created with single leg (if any)

Outbound Dialer -> dialAgentAmd()
    |
    v
checkGatewayStatus(id, gatewayId, customerNumber, tenantId)
    -> ESL: sofia status gateway {gatewayId}
    -> Response: "Status: DOWN"
    |
    v
contactRepository.setCallResult(id, "failed", "GATEWAY DOWN", now())
sendCallResults(id, "GATEWAY_DOWN", customerNumber, tenantId)
    |
    v
Voice Connector /send-delivery-notification
    -> CIM: DeliveryNotification FAILED
    -> Reason: GATEWAY_DOWN
    |
    v
CCM -> Conversation does NOT start
    -> No ChannelSession created
    -> No task created
    -> Contact remains in dialer DB: status="failed", call_result="GATEWAY DOWN"