feat: Enhance IVR and Call Recording Features[latest]

Author: shenjinti

src/app.rs

@@ -292,6 +292,17 @@ impl AppStateBuilder {
             .filter(|policy| policy.uploads_recording())
             .cloned();
 
+        // Create RWI gateway early so it can be shared with call record hooks
+        // (e.g. RecordingUploadHook emits RecordingMetadataAvailable after upload).
+        let rwi_gateway: Option<crate::rwi::RwiGatewayRef> =
+            if config.rwi.is_some() || config.rwi_webhook.is_some() {
+                Some(std::sync::Arc::new(parking_lot::RwLock::new(
+                    crate::rwi::RwiGateway::new(),
+                )))
+            } else {
+                None
+            };
+
         let callrecord_formatter = if let Some(formatter) = self.callrecord_formatter {
             formatter
         } else {
@@ -342,7 +353,11 @@ impl AppStateBuilder {
             }
 
             if let Some(policy) = recording_upload_policy.as_ref() {
-                builder = builder.with_hook(Box::new(RecordingUploadHook::new(policy.clone())));
+                let mut hook = RecordingUploadHook::new(policy.clone());
+                if let Some(ref gw) = rwi_gateway {
+                    hook = hook.with_rwi_gateway(gw.clone());
+                }
+                builder = builder.with_hook(Box::new(hook));
             }
 
             builder = builder.with_hook(Box::new(DatabaseHook {
@@ -383,13 +398,7 @@ impl AppStateBuilder {
             callrecord_stats: callrecord_stats.clone(),
             storage: storage.clone(),
             rwi_auth: crate::rwi::create_rwi_auth(&config),
-            rwi_gateway: if config.rwi.is_some() || config.rwi_webhook.is_some() {
-                Some(std::sync::Arc::new(parking_lot::RwLock::new(
-                    crate::rwi::RwiGateway::new(),
-                )))
-            } else {
-                None
-            },
+            rwi_gateway: rwi_gateway.clone(),
             rwi_call_registry: None,
         });
 

src/call/app/app_context.rs

@@ -26,6 +26,9 @@ pub struct CallInfo {
     /// headers like Via, Max-Forwards, Call-ID, CSeq, Content-Length).
     #[serde(skip_serializing_if = "HashMap::is_empty")]
     pub sip_headers: HashMap<String, String>,
+    /// Name of the matched routing rule that dispatched this call.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub route_name: Option<String>,
 }
 
 pub struct AppSharedState {
@@ -218,6 +221,7 @@ mod tests {
             direction: "inbound".to_string(),
             started_at: Utc::now(),
             sip_headers: HashMap::new(),
+            route_name: None,
         }
     }
 

src/call/app/ivr/executor.rs

@@ -22,6 +22,20 @@ pub struct StepIvrApp {
     step_index: u32,
     ivr_name: Option<String>,
     rwi_gateway: Option<crate::rwi::RwiGatewayRef>,
+    /// Name of the route that dispatched this call into the IVR.
+    route_name: Option<String>,
+    /// Route-level configured headers.
+    route_headers: Option<HashMap<String, String>>,
+    /// Passthrough data set by the external provider (echoed back each step).
+    custom_data: Option<serde_json::Value>,
+    /// Previous step start time (RFC3339) for timing reporting.
+    step_prev_start_time: Option<String>,
+    /// Previous step wall-clock duration in ms.
+    step_prev_duration_ms: u64,
+    /// How this session entered IVR: `None` (fresh inbound), `"agent"`, `"queue"`.
+    transferred_from: Option<String>,
+    /// Last transfer target string (for EndReason classification).
+    last_transfer_target: Option<String>,
 }
 
 #[derive(Clone)]
@@ -48,6 +62,13 @@ impl StepIvrApp {
             step_index: 0,
             ivr_name: None,
             rwi_gateway: None,
+            route_name: None,
+            route_headers: None,
+            custom_data: None,
+            step_prev_start_time: None,
+            step_prev_duration_ms: 0,
+            transferred_from: None,
+            last_transfer_target: None,
         }
     }
 
@@ -64,6 +85,13 @@ impl StepIvrApp {
             step_index: 0,
             ivr_name: None,
             rwi_gateway: None,
+            route_name: None,
+            route_headers: None,
+            custom_data: None,
+            step_prev_start_time: None,
+            step_prev_duration_ms: 0,
+            transferred_from: None,
+            last_transfer_target: None,
         }
     }
 
@@ -98,6 +126,24 @@ impl StepIvrApp {
         self
     }
 
+    /// Set the route name that dispatched this call into the IVR.
+    pub fn with_route_name(mut self, name: Option<String>) -> Self {
+        self.route_name = name;
+        self
+    }
+
+    /// Set the route-level configured headers.
+    pub fn with_route_headers(mut self, headers: Option<HashMap<String, String>>) -> Self {
+        self.route_headers = headers;
+        self
+    }
+
+    /// Mark this session as re-entered from agent or queue.
+    pub fn with_transferred_from(mut self, from: Option<String>) -> Self {
+        self.transferred_from = from;
+        self
+    }
+
     fn record_trace(&self, entry: IvrTraceEntry) {
         if let Some(t) = self.effective_trace() {
             let ent = entry.clone();
@@ -258,9 +304,10 @@ impl StepIvrApp {
                             error: None,
                         });
                         match terminal {
-                            TerminalAction::Transfer(target) => {
-                                (AppAction::Transfer(target), "terminal")
-                            }
+                    TerminalAction::Transfer(target) => {
+                            self.last_transfer_target = Some(target.clone());
+                            (AppAction::Transfer(target), "terminal")
+                        }
                             TerminalAction::Hangup { reason, code } => {
                                 (AppAction::Hangup { reason, code }, "terminal")
                             }
@@ -319,7 +366,9 @@ impl StepIvrApp {
         }
     }
 
-    async fn request_next(&self, event: Option<ProviderEvent>) -> anyhow::Result<ActionNode> {
+    async fn request_next(&mut self, event: Option<ProviderEvent>) -> anyhow::Result<ActionNode> {
+        let now_rfc3339 = chrono::Utc::now().to_rfc3339();
+        let prev_step_duration_ms = self.step_prev_duration_ms;
         let ctx = ProviderContext {
             session_id: self
                 .sess
@@ -350,12 +399,25 @@ impl StepIvrApp {
             variables: self.sess.variables.clone(),
             sip_headers: self.get_sip_headers(),
             event,
+            route_name: self.route_name.clone(),
+            route_headers: self.route_headers.clone(),
+            custom_data: self.custom_data.clone(),
+            step_start_time: Some(self.step_prev_start_time.clone().unwrap_or_else(|| now_rfc3339.clone())),
+            step_end_time: Some(now_rfc3339.clone()),
+            step_duration_ms: if prev_step_duration_ms > 0 { Some(prev_step_duration_ms) } else { None },
+            step_index: Some(self.step_index),
+            transferred_from: self.transferred_from.clone(),
         };
 
         let start = std::time::Instant::now();
         let result = self.provider.next_action(ctx.clone()).await;
         let elapsed_ms = start.elapsed().as_millis() as u64;
 
+        // Save step timing for the next ProviderContext.
+        self.step_prev_start_time = Some(now_rfc3339);
+        self.step_prev_duration_ms = elapsed_ms;
+        self.step_index += 1;
+
         // Trace the provider call
         let trace_action_type = match &result {
             Ok(node) => match &node.action {
@@ -680,9 +742,15 @@ impl CallApp for StepIvrApp {
             tenant_id: None,
             ivr_id: None,
             sip_headers: Some(headers),
+            route_name: self.route_name.clone(),
+            route_headers: self.route_headers.clone(),
+            custom_data: self.custom_data.clone(),
+            transferred_from: self.transferred_from.clone(),
         };
         self.provider.on_session_start(&sess_ctx).await.ok();
 
+        self.step_prev_start_time = Some(chrono::Utc::now().to_rfc3339());
+
         self.record_session_start(
             &context.call_info.session_id,
             &context.call_info.caller,
@@ -811,17 +879,30 @@ impl CallApp for StepIvrApp {
     async fn on_exit(&mut self, reason: crate::call::app::ExitReason) -> anyhow::Result<()> {
         let end_reason = match reason {
             crate::call::app::ExitReason::Normal => EndReason::Normal,
-            crate::call::app::ExitReason::Hangup
-            | crate::call::app::ExitReason::RemoteHangup(_) => EndReason::Hangup,
-            crate::call::app::ExitReason::Transferred => EndReason::Transfer(String::new()),
+            crate::call::app::ExitReason::Hangup => EndReason::Hangup,
+            crate::call::app::ExitReason::RemoteHangup(_) => EndReason::UserHangup,
+            crate::call::app::ExitReason::Transferred => {
+                // Determine transfer target type from the last action.
+                let target = self.last_transfer_target.clone().unwrap_or_default();
+                if target.starts_with("queue:") {
+                    EndReason::TransferToQueue(target)
+                } else if target.starts_with("toivr:") || target.starts_with("ivr:") {
+                    EndReason::TransferToIvr(target)
+                } else {
+                    EndReason::Transfer(target)
+                }
+            }
             crate::call::app::ExitReason::Error(e) => EndReason::Error(e),
             _ => EndReason::Normal,
         };
         self.provider.on_session_end(&end_reason).await.ok();
         let status = match &end_reason {
             EndReason::Normal => "completed",
             EndReason::Transfer(_) => "completed",
+            EndReason::TransferToQueue(_) => "completed",
+            EndReason::TransferToIvr(_) => "completed",
             EndReason::Hangup => "completed",
+            EndReason::UserHangup => "completed",
             EndReason::Error(_) => "error",
         };
         self.record_session_end(status).await;
@@ -1486,6 +1567,10 @@ mod tests {
             tenant_id: None,
             ivr_id: None,
             sip_headers: None,
+            route_name: None,
+            route_headers: None,
+            custom_data: None,
+            transferred_from: None,
         };
         step_provider
             .on_session_start(&session)
@@ -1502,6 +1587,14 @@ mod tests {
             variables: HashMap::new(),
             sip_headers: None,
             event: Some(ProviderEvent::SessionStart),
+            route_name: None,
+            route_headers: None,
+            custom_data: None,
+            step_start_time: None,
+            step_end_time: None,
+            step_duration_ms: None,
+            step_index: None,
+            transferred_from: None,
         };
         let prompt = step_provider.next_action(ctx).await.unwrap();
         assert!(
@@ -1523,6 +1616,14 @@ mod tests {
                 variables: HashMap::new(),
                 sip_headers: None,
                 event: None,
+                route_name: None,
+                route_headers: None,
+                custom_data: None,
+                step_start_time: None,
+                step_end_time: None,
+                step_duration_ms: None,
+                step_index: None,
+                transferred_from: None,
             }
         };
         let transfer = step_provider.next_action(ctx).await.unwrap();

src/call/app/ivr/provider.rs

@@ -46,6 +46,19 @@ pub struct SessionContext {
     /// All SIP headers from the original INVITE request.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub sip_headers: Option<HashMap<String, String>>,
+    /// Name of the matched route that sent this call into the IVR.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub route_name: Option<String>,
+    /// Extra headers configured on the route (from routing rule `option.headers`).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub route_headers: Option<HashMap<String, String>>,
+    /// Arbitrary passthrough data set by the caller / external system.
+    /// The provider receives this and can use it for correlation.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub custom_data: Option<serde_json::Value>,
+    /// Whether this session was re-entered from agent/queue (transfer-back).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub transferred_from: Option<String>,
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
@@ -61,6 +74,32 @@ pub struct ProviderContext {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub sip_headers: Option<HashMap<String, String>>,
     pub event: Option<ProviderEvent>,
+    /// Name of the matched route that sent this call into the IVR.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub route_name: Option<String>,
+    /// Extra headers configured on the route.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub route_headers: Option<HashMap<String, String>>,
+    /// Passthrough data — the provider can set `custom_data` in its response
+    /// and it will be echoed back in every subsequent ProviderContext.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub custom_data: Option<serde_json::Value>,
+    /// Step timing: ISO-8601 timestamp when this step started.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub step_start_time: Option<String>,
+    /// Step timing: ISO-8601 timestamp when this step ended (set before sending).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub step_end_time: Option<String>,
+    /// Step timing: wall-clock duration of the previous step in milliseconds.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub step_duration_ms: Option<u64>,
+    /// Monotonic step index (0 for SessionStart, incremented thereafter).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub step_index: Option<u32>,
+    /// Whether this session was re-entered from agent/queue.
+    /// Values: `"agent"`, `"queue"`, or `None`.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub transferred_from: Option<String>,
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
@@ -100,9 +139,19 @@ pub enum ProviderEvent {
 
 #[derive(Debug, Clone)]
 pub enum EndReason {
+    /// IVR completed normally (played all nodes, no transfer).
     Normal,
+    /// IVR exited because the call was transferred to an agent or extension.
     Transfer(String),
+    /// IVR exited because the call was sent to a queue.
+    TransferToQueue(String),
+    /// IVR exited because the call jumped to another IVR.
+    TransferToIvr(String),
+    /// System (PBX) initiated the hangup.
     Hangup,
+    /// User / remote party hung up.
+    UserHangup,
+    /// Error during IVR execution.
     Error(String),
 }