feat: add vici dial controls from UI (#563)

* ViciDial Working

* feat(telephony): add FreeSWITCH provider to upstream-PBX seam

Generalize the upstream-PBX capture and control paths to dispatch by
provider. FreeSWITCH bridges in with X-PBX-* headers and is driven over
the Event Socket Library (uuid_kill / uuid_transfer) by the channel UUID,
alongside the existing VICIdial ra_call_control path.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* add vici specific configs

* feat(telephony): env-based VICIdial config + address3 post-call routing

Move VICIdial agent/non-agent API and FreeSWITCH ESL connection settings
out of hardcoded POC values into environment variables so the same image
works against a PBX on another server.

Add VICIdial update_lead forwarding: X-VICI-UPDATE-LEAD_* extracted
variables are mapped to lead columns and pushed via the non-agent API
before a transfer, with reserved API-control params dropped.

Add hardcoded address3 disposition routing (Y/N -> in-group transfer,
else hang up) and a synchronous final variable extraction so the
transfer path sees the freshest conversation state. Skip upstream_pbx
capture on non-PJSIP channels to avoid Asterisk 500s.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* chore: run formatter

* feat: make vici configurable from UI

* chore: clean up PR

* fix: incorporate review comments

* chore: incorporate review comments

* chore: generate client

* chore: incporporate review comments

* chore: incorporate review comments

---------

Co-authored-by: Dograh POC <payment@dograh.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

api/schemas/organization_preferences.py

@@ -4,3 +4,4 @@ from pydantic import BaseModel
 class OrganizationPreferences(BaseModel):
     test_phone_number: str | None = None
     timezone: str | None = None
+    external_pbx_integrations_enabled: bool = False

api/schemas/tool.py

@@ -223,12 +223,70 @@ class HttpTransferResolverConfig(BaseModel):
         return v
 
 
+class ContextDestinationRoute(BaseModel):
+    """Map one gathered-context value to an external-PBX destination."""
+
+    context_value: str = Field(min_length=1, max_length=255)
+    destination: str = Field(min_length=1, max_length=255)
+
+    @field_validator("context_value", "destination")
+    @classmethod
+    def strip_non_empty(cls, value: str) -> str:
+        stripped = value.strip()
+        if not stripped:
+            raise ValueError("mapping values cannot be blank")
+        return stripped
+
+
+class ContextDestinationMappingConfig(BaseModel):
+    """Resolve an external-PBX destination from gathered context."""
+
+    context_path: str = Field(
+        min_length=1,
+        max_length=255,
+        description=(
+            "Gathered-context path or extracted-variable name used for routing."
+        ),
+    )
+    routes: List[ContextDestinationRoute] = Field(min_length=1, max_length=100)
+    fallback_destination: Optional[str] = Field(
+        default=None,
+        max_length=255,
+        description="Optional provider-native fallback destination.",
+    )
+
+    @field_validator("context_path")
+    @classmethod
+    def strip_context_path(cls, value: str) -> str:
+        stripped = value.strip()
+        if not stripped:
+            raise ValueError("context path cannot be blank")
+        return stripped
+
+    @field_validator("fallback_destination")
+    @classmethod
+    def normalize_fallback(cls, value: Optional[str]) -> Optional[str]:
+        if value is None:
+            return None
+        return value.strip() or None
+
+    @model_validator(mode="after")
+    def validate_unique_values(self):
+        values = [route.context_value.casefold() for route in self.routes]
+        if len(values) != len(set(values)):
+            raise ValueError("context mapping values must be unique")
+        return self
+
+
 class TransferCallConfig(BaseModel):
     """Configuration for Transfer Call tools."""
 
-    destination_source: Literal["static", "dynamic"] = Field(
+    destination_source: Literal["static", "dynamic", "context_mapping"] = Field(
         default="static",
-        description="Whether transfer destination is static/template or resolved by HTTP.",
+        description=(
+            "Whether the destination is static/template, resolved by HTTP, or "
+            "mapped from gathered context to an external-PBX destination."
+        ),
     )
     destination: str = Field(
         default="",
@@ -263,6 +321,10 @@ class TransferCallConfig(BaseModel):
         default=None,
         description="Optional resolver that determines transfer routing at call time.",
     )
+    context_mapping: Optional[ContextDestinationMappingConfig] = Field(
+        default=None,
+        description="Optional gathered-context to external-PBX destination mapping.",
+    )
 
     @model_validator(mode="after")
     def validate_destination_source_config(self):
@@ -270,6 +332,14 @@ class TransferCallConfig(BaseModel):
             raise ValueError(
                 "config.resolver is required when destination_source is dynamic"
             )
+        if (
+            self.destination_source == "context_mapping"
+            and self.context_mapping is None
+        ):
+            raise ValueError(
+                "config.context_mapping is required when destination_source is "
+                "context_mapping"
+            )
         return self
 
 

api/schemas/workflow_configurations.py

@@ -1,6 +1,6 @@
 from typing import Literal
 
-from pydantic import BaseModel, ConfigDict, Field, model_validator
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
 
 DEFAULT_MAX_CALL_DURATION_SECONDS = 300
 # Hard ceiling on configurable call duration. Must stay <= the concurrency
@@ -16,6 +16,23 @@ DEFAULT_TURN_STOP_STRATEGY = "transcription"
 DEFAULT_CONTEXT_COMPACTION_ENABLED = False
 
 
+class ExternalPBXFieldMapping(BaseModel):
+    """Map one gathered-context value to a provider-native field."""
+
+    context_path: str = Field(min_length=1, max_length=255)
+    destination_field: str = Field(pattern=r"^[A-Za-z][A-Za-z0-9_]{0,63}$")
+
+    @field_validator("context_path", mode="before")
+    @classmethod
+    def strip_context_path(cls, value: object) -> object:
+        return value.strip() if isinstance(value, str) else value
+
+    @field_validator("destination_field", mode="before")
+    @classmethod
+    def strip_destination_field(cls, value: object) -> object:
+        return value.strip() if isinstance(value, str) else value
+
+
 class AmbientNoiseConfigurationDefaults(BaseModel):
     model_config = ConfigDict(extra="allow")
 
@@ -56,6 +73,10 @@ class WorkflowConfigurationDefaults(BaseModel):
     )
     dictionary: str = ""
     context_compaction_enabled: bool = DEFAULT_CONTEXT_COMPACTION_ENABLED
+    external_pbx_field_mappings: list[ExternalPBXFieldMapping] = Field(
+        default_factory=list,
+        max_length=100,
+    )
 
 
 def get_default_workflow_configurations() -> WorkflowConfigurationDefaults: