From 5e5dc21f2fd6d86fc5ba49538a488db09d9d3a1e Mon Sep 17 00:00:00 2001
From: tds-1 <tds-1@users.noreply.github.com>
Date: Tue, 21 Apr 2026 04:47:53 +0000
Subject: [PATCH] feat(whatsapp-call): add server-side WebRTC media server for
 call persistence

Implements a Pion Go B2BUA media server sidecar that sits between Meta's
WhatsApp Cloud API and the agent's browser, enabling call persistence
across page reloads, server-side recording, multi-participant support,
audio injection, and AI integration readiness.

Go Media Server (enterprise/media-server/):
- Pion WebRTC v4 B2BUA with Peer A (Meta) and Peer B (Agent) connections
- Real-time OGG/Opus recording with crash recovery
- Audio bridge with multi-peer fan-out and AudioConsumer plugin interface
- Audio injection from OGG files with loop support for hold music
- Session manager with graceful shutdown and orphaned recording recovery
- HTTP API with Bearer token auth, health checks, and metrics

Rails Integration:
- Whatsapp::MediaServerClient HTTP client for Go sidecar communication
- Dual-mode CallService: legacy browser-direct and server-relay paths
- Media server callback controller for agent disconnect/recording/terminate
- CallRecordingFetchJob: downloads OGG from Go server to ActiveStorage/S3
- CallCleanupJob: sweeps stale ringing and in-progress calls
- New endpoints: active, agent_answer, reconnect, join, play_audio
- DB migration: media_session_id column with indexes

Frontend:
- Dual-mode composable auto-detecting legacy vs server-relay
- handleAgentOffer() for receiving SDP from media server
- useCallReconnection composable for page reload recovery
- Removed terminateCallOnUnload in server-relay mode
- Simplified outbound call flow in ConversationHeader
- New ActionCable event: whatsapp_call.agent_offer

Documentation:
- Server-side WebRTC architecture spec (1505 lines)
- Implementation plan with 119 trackable checklist items
- Feature spec, PR breakdown, and relay architecture docs
---
 .env.example                                  |    7 +
 app/javascript/dashboard/api/whatsappCalls.js |   47 +-
 .../message/bubbles/VoiceCall.vue             |   15 +-
 .../components/widgets/WhatsappCallWidget.vue |   44 +-
 .../conversation/ConversationHeader.vue       |  121 +-
 .../composables/useCallReconnection.js        |   63 +
 .../composables/useWhatsappCallSession.js     |  255 ++-
 .../dashboard/helper/actionCable.js           |   62 +-
 .../i18n/locale/en/whatsappCall.json          |    4 +-
 .../dashboard/stores/whatsappCalls.js         |   31 +-
 config/routes.rb                              |   17 +-
 ...042235_add_media_server_fields_to_calls.rb |    7 +
 db/schema.rb                                  |    6 +-
 docker-compose.production.yaml                |   27 +
 docker-compose.yaml                           |   27 +
 docs/SERVER_SIDE_WEBRTC_ARCHITECTURE.md       | 1504 +++++++++++++++++
 .../SERVER_SIDE_WEBRTC_IMPLEMENTATION_PLAN.md | 1314 ++++++++++++++
 docs/WHATSAPP_CALL_FEATURE_SPEC.md            |  272 +++
 docs/WHATSAPP_CALL_PR_BREAKDOWN.md            |  347 ++++
 ...WHATSAPP_CALL_SERVER_RELAY_ARCHITECTURE.md |  694 ++++++++
 .../media_server/callbacks_controller.rb      |   67 +
 .../v1/accounts/whatsapp_calls_controller.rb  |  136 +-
 .../app/jobs/whatsapp/call_cleanup_job.rb     |   33 +
 .../jobs/whatsapp/call_recording_fetch_job.rb |   26 +
 enterprise/app/models/call.rb                 |    5 +
 .../app/services/whatsapp/call_service.rb     |   90 +-
 .../whatsapp/incoming_call_service.rb         |   39 +-
 .../services/whatsapp/media_server_client.rb  |  109 ++
 enterprise/media-server/Dockerfile            |   31 +
 enterprise/media-server/README.md             |  155 ++
 enterprise/media-server/cmd/server/main.go    |  133 ++
 enterprise/media-server/go.mod                |   30 +
 .../media-server/internal/auth/middleware.go  |   65 +
 .../internal/callback/rails_client.go         |  138 ++
 .../media-server/internal/config/config.go    |  197 +++
 .../media-server/internal/media/bridge.go     |  323 ++++
 .../media-server/internal/media/injector.go   |  189 +++
 .../media-server/internal/media/recorder.go   |  208 +++
 .../media-server/internal/peer/agent_peer.go  |  236 +++
 .../media-server/internal/peer/meta_peer.go   |  257 +++
 .../media-server/internal/server/handlers.go  |  662 ++++++++
 .../media-server/internal/server/router.go    |  116 ++
 .../media-server/internal/session/manager.go  |  292 ++++
 .../media-server/internal/session/session.go  |  563 ++++++
 44 files changed, 8827 insertions(+), 137 deletions(-)
 create mode 100644 app/javascript/dashboard/composables/useCallReconnection.js
 create mode 100644 db/migrate/20260421042235_add_media_server_fields_to_calls.rb
 create mode 100644 docs/SERVER_SIDE_WEBRTC_ARCHITECTURE.md
 create mode 100644 docs/SERVER_SIDE_WEBRTC_IMPLEMENTATION_PLAN.md
 create mode 100644 docs/WHATSAPP_CALL_FEATURE_SPEC.md
 create mode 100644 docs/WHATSAPP_CALL_PR_BREAKDOWN.md
 create mode 100644 docs/WHATSAPP_CALL_SERVER_RELAY_ARCHITECTURE.md
 create mode 100644 enterprise/app/controllers/api/v1/accounts/media_server/callbacks_controller.rb
 create mode 100644 enterprise/app/jobs/whatsapp/call_cleanup_job.rb
 create mode 100644 enterprise/app/jobs/whatsapp/call_recording_fetch_job.rb
 create mode 100644 enterprise/app/services/whatsapp/media_server_client.rb
 create mode 100644 enterprise/media-server/Dockerfile
 create mode 100644 enterprise/media-server/README.md
 create mode 100644 enterprise/media-server/cmd/server/main.go
 create mode 100644 enterprise/media-server/go.mod
 create mode 100644 enterprise/media-server/internal/auth/middleware.go
 create mode 100644 enterprise/media-server/internal/callback/rails_client.go
 create mode 100644 enterprise/media-server/internal/config/config.go
 create mode 100644 enterprise/media-server/internal/media/bridge.go
 create mode 100644 enterprise/media-server/internal/media/injector.go
 create mode 100644 enterprise/media-server/internal/media/recorder.go
 create mode 100644 enterprise/media-server/internal/peer/agent_peer.go
 create mode 100644 enterprise/media-server/internal/peer/meta_peer.go
 create mode 100644 enterprise/media-server/internal/server/handlers.go
 create mode 100644 enterprise/media-server/internal/server/router.go
 create mode 100644 enterprise/media-server/internal/session/manager.go
 create mode 100644 enterprise/media-server/internal/session/session.go

diff --git a/.env.example b/.env.example
index bc7380a29..62ba1a24f 100644
--- a/.env.example
+++ b/.env.example
@@ -277,3 +277,10 @@ AZURE_APP_SECRET=
 
 # REDIS_ALFRED_SIZE=10
 # REDIS_VELMA_SIZE=10
+
+# Media Server (WhatsApp Calling - Server-Side WebRTC)
+# Enable server-side WebRTC relay for call persistence across page reloads
+# and server-side recording. Requires the chatwoot-media-server sidecar.
+# MEDIA_SERVER_URL=http://localhost:4000
+# MEDIA_SERVER_AUTH_TOKEN=
+# MEDIA_SERVER_PUBLIC_IP=
diff --git a/app/javascript/dashboard/api/whatsappCalls.js b/app/javascript/dashboard/api/whatsappCalls.js
index 3b35588b1..e8c3de378 100644
--- a/app/javascript/dashboard/api/whatsappCalls.js
+++ b/app/javascript/dashboard/api/whatsappCalls.js
@@ -10,10 +10,11 @@ class WhatsappCallsAPI extends ApiClient {
     return axios.get(`${this.url}/${callId}`);
   }
 
+  // Accept a ringing call. sdpAnswer is optional — omitted in server-relay mode
+  // where the media server handles WebRTC negotiation.
   accept(callId, sdpAnswer) {
-    return axios.post(`${this.url}/${callId}/accept`, {
-      sdp_answer: sdpAnswer,
-    });
+    const body = sdpAnswer ? { sdp_answer: sdpAnswer } : {};
+    return axios.post(`${this.url}/${callId}/accept`, body);
   }
 
   reject(callId) {
@@ -24,13 +25,47 @@ class WhatsappCallsAPI extends ApiClient {
     return axios.post(`${this.url}/${callId}/terminate`);
   }
 
+  // Initiate an outbound call. sdpOffer is optional — omitted in server-relay
+  // mode where the media server generates the SDP offer for Meta.
   initiate(conversationId, sdpOffer) {
-    return axios.post(`${this.url}/initiate`, {
-      conversation_id: conversationId,
-      sdp_offer: sdpOffer,
+    const body = { conversation_id: conversationId };
+    if (sdpOffer) body.sdp_offer = sdpOffer;
+    return axios.post(`${this.url}/initiate`, body);
+  }
+
+  // Send the agent's SDP answer for the Peer B connection (server-relay mode).
+  agentAnswer(callId, sdpAnswer) {
+    return axios.post(`${this.url}/${callId}/agent_answer`, {
+      sdp_answer: sdpAnswer,
     });
   }
 
+  // Get the current agent's active call (if any). Used for reconnection on page load.
+  active() {
+    return axios.get(`${this.url}/active`);
+  }
+
+  // Reconnect to an active call after page reload. Server creates a new Peer B
+  // and returns a fresh SDP offer via ActionCable.
+  reconnect(callId) {
+    return axios.post(`${this.url}/${callId}/reconnect`);
+  }
+
+  // Join an existing call as a supervisor (listen-only by default).
+  join(callId, role = 'listen_only') {
+    return axios.post(`${this.url}/${callId}/join`, { role });
+  }
+
+  // Play an audio file to the caller via the media server.
+  playAudio(callId, { filePath, mode = 'replace', loop = false }) {
+    return axios.post(`${this.url}/${callId}/play_audio`, {
+      file_path: filePath,
+      mode,
+      loop,
+    });
+  }
+
+  // Legacy: upload browser-side recording. Deprecated when media server is enabled.
   uploadRecording(callId, blob) {
     const formData = new FormData();
     formData.append('recording', blob, `call-${callId}.webm`);
diff --git a/app/javascript/dashboard/components-next/message/bubbles/VoiceCall.vue b/app/javascript/dashboard/components-next/message/bubbles/VoiceCall.vue
index 053bcaeb8..a24fb1fe6 100644
--- a/app/javascript/dashboard/components-next/message/bubbles/VoiceCall.vue
+++ b/app/javascript/dashboard/components-next/message/bubbles/VoiceCall.vue
@@ -47,7 +47,7 @@ const isFailed = computed(() =>
 
 // Call source and metadata — all camelCase due to deep transform
 const isWhatsappCall = computed(() => data.value?.callSource === 'whatsapp');
-const waCallId = computed(() => data.value?.callId);
+const callId = computed(() => data.value?.callId);
 const acceptedBy = computed(() => data.value?.acceptedBy);
 const durationSeconds = computed(() => data.value?.durationSeconds);
 const recordingUrl = computed(() => data.value?.recordingUrl);
@@ -64,10 +64,19 @@ const formattedDuration = computed(() => {
 });
 
 // Show join/accept button logic
-// WhatsApp: only ringing (peer-to-peer WebRTC — cannot rejoin after accept)
+// WhatsApp with media server: ringing + in_progress (server-relay supports rejoin)
+// WhatsApp without media server: only ringing (peer-to-peer WebRTC — cannot rejoin after accept)
 // Twilio: ringing + in-progress (conference model supports rejoin)
 const showJoinButton = computed(() => {
   if (isWhatsappCall.value) {
+    // Server-relay mode enables rejoining in-progress calls
+    const isMediaServerMode = data.value?.mediaServerEnabled;
+    if (isMediaServerMode) {
+      return [
+        VOICE_CALL_STATUS.RINGING,
+        VOICE_CALL_STATUS.IN_PROGRESS,
+      ].includes(status.value);
+    }
     return status.value === VOICE_CALL_STATUS.RINGING;
   }
   return [VOICE_CALL_STATUS.RINGING, VOICE_CALL_STATUS.IN_PROGRESS].includes(
@@ -133,7 +142,7 @@ const handleJoinCall = async () => {
 
   try {
     if (isWhatsappCall.value) {
-      const result = await acceptWhatsappCallById(waCallId.value);
+      const result = await acceptWhatsappCallById(callId.value);
       if (result?.success && result.call) {
         router.push({
           name: 'inbox_conversation',
diff --git a/app/javascript/dashboard/components/widgets/WhatsappCallWidget.vue b/app/javascript/dashboard/components/widgets/WhatsappCallWidget.vue
index d96bd7f79..690605371 100644
--- a/app/javascript/dashboard/components/widgets/WhatsappCallWidget.vue
+++ b/app/javascript/dashboard/components/widgets/WhatsappCallWidget.vue
@@ -1,9 +1,11 @@
 <script setup>
-import { watch, onUnmounted } from 'vue';
+import { watch, onUnmounted, onMounted } from 'vue';
 import { useRouter } from 'vue-router';
 import { useWhatsappCallSession } from 'dashboard/composables/useWhatsappCallSession';
 import Avatar from 'dashboard/components-next/avatar/Avatar.vue';
 import { useI18n } from 'vue-i18n';
+import { emitter } from 'shared/helpers/mitt';
+import { BUS_EVENTS } from 'shared/constants/busEvents';
 
 const { t } = useI18n();
 const router = useRouter();
@@ -16,6 +18,7 @@ const {
   isAccepting,
   isMuted,
   isOutboundRinging,
+  isReconnecting,
   callError,
   formattedCallDuration,
   acceptCall,
@@ -23,8 +26,27 @@ const {
   endActiveCall,
   toggleMute,
   dismissIncomingCall,
+  startDurationTimer,
 } = useWhatsappCallSession();
 
+// In server-relay mode, the timer starts when the Peer B WebRTC handshake
+// completes (not when the agent clicks accept). Listen for this event.
+const onAgentWebRTCConnected = () => {
+  startDurationTimer();
+};
+
+const onPermissionGranted = ({ contactName }) => {
+  emitter.emit(BUS_EVENTS.SHOW_ALERT, {
+    message: t('WHATSAPP_CALL.PERMISSION_GRANTED', { contactName }),
+    type: 'success',
+  });
+};
+
+onMounted(() => {
+  emitter.on('whatsapp_call:agent_webrtc_connected', onAgentWebRTCConnected);
+  emitter.on('whatsapp_call:permission_granted', onPermissionGranted);
+});
+
 // Auto-dismiss ringing calls after 30 seconds
 const autoRejectTimers = new Map();
 
@@ -77,6 +99,8 @@ watch(
 onUnmounted(() => {
   autoRejectTimers.forEach(timer => clearTimeout(timer));
   autoRejectTimers.clear();
+  emitter.off('whatsapp_call:agent_webrtc_connected', onAgentWebRTCConnected);
+  emitter.off('whatsapp_call:permission_granted', onPermissionGranted);
 });
 </script>
 
@@ -173,14 +197,20 @@ onUnmounted(() => {
         <p
           class="text-sm"
           :class="
-            isOutboundRinging ? 'text-n-slate-11' : 'font-mono text-n-teal-9'
+            isOutboundRinging || isReconnecting
+              ? 'text-n-slate-11'
+              : 'font-mono text-n-teal-9'
           "
         >
-          {{
-            isOutboundRinging
-              ? t('WHATSAPP_CALL.RINGING')
-              : formattedCallDuration
-          }}
+          <template v-if="isReconnecting">
+            {{ t('WHATSAPP_CALL.RECONNECTING') }}
+          </template>
+          <template v-else-if="isOutboundRinging">
+            {{ t('WHATSAPP_CALL.RINGING') }}
+          </template>
+          <template v-else>
+            {{ formattedCallDuration }}
+          </template>
         </p>
       </div>
       <div class="flex shrink-0 gap-2">
diff --git a/app/javascript/dashboard/components/widgets/conversation/ConversationHeader.vue b/app/javascript/dashboard/components/widgets/conversation/ConversationHeader.vue
index 98131a824..6185ee9ba 100644
--- a/app/javascript/dashboard/components/widgets/conversation/ConversationHeader.vue
+++ b/app/javascript/dashboard/components/widgets/conversation/ConversationHeader.vue
@@ -104,32 +104,118 @@ const hasSlaPolicyId = computed(() => props.chat?.sla_policy_id);
 const canInitiateWhatsappCall = computed(() => {
   if (!isAWhatsAppCloudChannel.value) return false;
   if (!inbox.value?.calling_enabled) return false;
-  // Block if there's already an active or ringing WhatsApp call
   if (whatsappCallsStore.hasWhatsappCall) return false;
   return true;
 });
 
+// Detect if the media server is enabled for this inbox.
+// When enabled, the browser should NOT create its own WebRTC offer.
+const isMediaServerEnabled = computed(
+  () => !!inbox.value?.media_server_enabled
+);
+
 const waitForOutboundIceGathering = pc =>
-  new Promise(resolve => {
+  new Promise((resolve, reject) => {
     if (pc.iceGatheringState === 'complete') {
       resolve();
       return;
     }
-    const timeout = setTimeout(() => resolve(), 10000);
+
+    let timeout = null;
+
+    const cleanup = () => {
+      clearTimeout(timeout);
+      pc.onicegatheringstatechange = null;
+      pc.oniceconnectionstatechange = null;
+    };
+
+    timeout = setTimeout(() => {
+      cleanup();
+      resolve();
+    }, 10000);
+
     pc.onicegatheringstatechange = () => {
       if (pc.iceGatheringState === 'complete') {
-        clearTimeout(timeout);
+        cleanup();
         resolve();
       }
     };
+    pc.oniceconnectionstatechange = () => {
+      if (pc.iceConnectionState === 'failed') {
+        cleanup();
+        reject(new Error('ICE connection failed'));
+      }
+    };
   });
 
-const initiateWhatsappCall = async () => {
+/**
+ * Server-relay mode: POST /initiate without SDP. The media server creates
+ * Peer A (Meta-side) and later sends the agent Peer B offer via ActionCable
+ * (whatsapp_call.outbound_connected with sdp_offer).
+ */
+const initiateServerRelayCall = async () => {
+  if (isInitiatingCall.value || !currentChat.value?.id) return;
+  isInitiatingCall.value = true;
+
+  try {
+    const response = await WhatsappCallsAPI.initiate(currentChat.value.id);
+
+    const callStatus = response.data?.status;
+    if (
+      callStatus === 'permission_requested' ||
+      callStatus === 'permission_pending'
+    ) {
+      const message =
+        callStatus === 'permission_requested'
+          ? t('WHATSAPP_CALL.PERMISSION_REQUESTED')
+          : t('WHATSAPP_CALL.PERMISSION_PENDING');
+      emitter.emit(BUS_EVENTS.SHOW_ALERT, { message, type: 'info' });
+      return;
+    }
+
+    emitter.emit(BUS_EVENTS.SHOW_ALERT, {
+      message: t('WHATSAPP_CALL.CALLING'),
+      type: 'success',
+    });
+
+    const outboundCallId = response.data?.call_id;
+
+    // Set active call — WebRTC setup happens when ActionCable delivers agent_offer
+    whatsappCallsStore.setActiveCall({
+      id: response.data?.id,
+      callId: outboundCallId,
+      direction: 'outbound',
+      status: 'ringing',
+      serverRelay: true,
+      conversationId: currentChat.value.id,
+      caller: {
+        name: currentContact.value?.name,
+        phone: currentContact.value?.phone_number,
+        avatar: currentContact.value?.thumbnail,
+      },
+    });
+  } catch (err) {
+    const errorMessage =
+      err.response?.data?.error || t('WHATSAPP_CALL.CALL_FAILED');
+    emitter.emit(BUS_EVENTS.SHOW_ALERT, {
+      message: errorMessage,
+      type: 'error',
+    });
+  } finally {
+    isInitiatingCall.value = false;
+  }
+};
+
+/**
+ * Legacy mode: Browser creates RTCPeerConnection, generates SDP offer,
+ * sends it to backend which forwards to Meta.
+ */
+const initiateLegacyCall = async () => {
   if (isInitiatingCall.value || !currentChat.value?.id) return;
   isInitiatingCall.value = true;
   let pc = null;
   let localStream = null;
-  let waCallId = null;
+  let recordCallId = null;
   try {
     localStream = await navigator.mediaDevices.getUserMedia({ audio: true });
     pc = new RTCPeerConnection({
@@ -137,7 +223,6 @@ const initiateWhatsappCall = async () => {
     });
     localStream.getTracks().forEach(track => pc.addTrack(track, localStream));
 
-    // Handle remote audio from Meta — ontrack fires when the callee picks up
     pc.ontrack = event => {
       const [stream] = event.streams;
       if (!stream) return;
@@ -146,21 +231,13 @@ const initiateWhatsappCall = async () => {
       audio.autoplay = true;
       document.body.appendChild(audio);
       setOutboundCallProperty('audio', audio);
-      // Remote audio arrived — callee picked up, transition from ringing to connected
       whatsappCallsStore.markActiveCallConnected();
-      // Start recording both local + remote audio
-      if (waCallId) startCallRecording(pc, localStream, waCallId);
-    };
-
-    pc.oniceconnectionstatechange = () => {
-      // eslint-disable-next-line no-console
-      console.log('[WhatsApp Call] Outbound ICE state:', pc.iceConnectionState);
+      if (recordCallId) startCallRecording(pc, localStream, recordCallId);
     };
 
     const offer = await pc.createOffer();
     await pc.setLocalDescription(offer);
 
-    // Wait for ICE gathering to complete before sending offer
     await waitForOutboundIceGathering(pc);
     const completeSdp = pc.localDescription.sdp;
 
@@ -190,18 +267,17 @@ const initiateWhatsappCall = async () => {
     });
 
     const outboundCallId = response.data?.call_id;
-    waCallId = response.data?.id;
+    recordCallId = response.data?.id;
     setOutboundCallProperty('pc', pc);
     setOutboundCallProperty('stream', localStream);
     setOutboundCallProperty('callId', outboundCallId);
 
-    // Set active call in store so the WhatsappCallWidget renders
-    // Status starts as 'ringing' — updated to 'connected' when SDP answer arrives
     whatsappCallsStore.setActiveCall({
       id: response.data?.id,
       callId: outboundCallId,
       direction: 'outbound',
       status: 'ringing',
+      serverRelay: false,
       conversationId: currentChat.value.id,
       caller: {
         name: currentContact.value?.name,
@@ -222,6 +298,13 @@ const initiateWhatsappCall = async () => {
     isInitiatingCall.value = false;
   }
 };
+
+const initiateWhatsappCall = () => {
+  if (isMediaServerEnabled.value) {
+    return initiateServerRelayCall();
+  }
+  return initiateLegacyCall();
+};
 </script>
 
 <template>
diff --git a/app/javascript/dashboard/composables/useCallReconnection.js b/app/javascript/dashboard/composables/useCallReconnection.js
new file mode 100644
index 000000000..40236ac16
--- /dev/null
+++ b/app/javascript/dashboard/composables/useCallReconnection.js
@@ -0,0 +1,63 @@
+import { onMounted, computed } from 'vue';
+import { useWhatsappCallsStore } from 'dashboard/stores/whatsappCalls';
+import WhatsappCallsAPI from 'dashboard/api/whatsappCalls';
+
+/**
+ * Checks for an active WhatsApp call on page load and reconnects if found.
+ * This handles the server-relay scenario where the call persists on the media
+ * server even after the agent's browser reloads.
+ *
+ * NOTE: This composable intentionally does NOT call useWhatsappCallSession()
+ * to avoid creating duplicate side effects (beforeunload handlers, cleanup
+ * callbacks, timers). The WhatsappCallWidget owns the useWhatsappCallSession
+ * instance. This composable only sets store state and triggers the reconnect
+ * API call — the actual WebRTC setup happens when the ActionCable agent_offer
+ * event arrives and is handled by handleAgentOffer.
+ *
+ * Usage: call `useCallReconnection()` in the app-level layout component that
+ * mounts once on page load.
+ */
+export function useCallReconnection() {
+  const callsStore = useWhatsappCallsStore();
+
+  const isReconnecting = computed(() => callsStore.isReconnecting);
+
+  onMounted(async () => {
+    // Skip if there's already an active or incoming call in the store
+    if (callsStore.hasActiveCall || callsStore.hasIncomingCall) return;
+
+    try {
+      const { data } = await WhatsappCallsAPI.active();
+      if (!data?.call) return;
+
+      const activeCallData = data.call;
+
+      callsStore.setReconnecting(true);
+      callsStore.setActiveCall({
+        id: activeCallData.id,
+        callId: activeCallData.call_id,
+        direction: activeCallData.direction,
+        conversationId: activeCallData.conversation_id,
+        status: 'reconnecting',
+        serverRelay: true,
+        caller: activeCallData.caller,
+      });
+
+      // Set timer offset so the timer resumes from the correct elapsed time
+      if (activeCallData.elapsed_seconds) {
+        callsStore.setTimerOffset(activeCallData.elapsed_seconds);
+      }
+
+      // Tell the server to create a new Peer B and send us a fresh SDP offer.
+      // The server will broadcast whatsapp_call.agent_offer via ActionCable,
+      // which is handled by handleAgentOffer in actionCable.js.
+      await WhatsappCallsAPI.reconnect(activeCallData.id);
+    } catch {
+      // No active call or API/reconnect error — clear state and silent fail.
+      // clearActiveCall() also resets isReconnecting and callTimerOffset.
+      callsStore.clearActiveCall();
+    }
+  });
+
+  return { isReconnecting };
+}
diff --git a/app/javascript/dashboard/composables/useWhatsappCallSession.js b/app/javascript/dashboard/composables/useWhatsappCallSession.js
index 4fcc1e6f8..5ab0f60de 100644
--- a/app/javascript/dashboard/composables/useWhatsappCallSession.js
+++ b/app/javascript/dashboard/composables/useWhatsappCallSession.js
@@ -3,18 +3,18 @@ import { useI18n } from 'vue-i18n';
 import {
   useWhatsappCallsStore,
   getOutboundCallState,
+  cleanupOutboundCall,
 } from 'dashboard/stores/whatsappCalls';
 import WhatsappCallsAPI from 'dashboard/api/whatsappCalls';
 import Auth from 'dashboard/api/auth';
 import Timer from 'dashboard/helper/Timer';
 
-// ── Module-level WebRTC state for inbound calls accepted from anywhere ──
-// Kept at module scope so both the composable and acceptWhatsappCallById share it.
+// ── Module-level WebRTC state (shared across legacy inbound + server-relay) ──
 let inboundPc = null;
 let inboundStream = null;
 let inboundAudio = null;
 
-// ── Module-level recording state ──
+// ── Module-level recording state (legacy mode only) ──
 let mediaRecorder = null;
 let recordedChunks = [];
 let recordingCallId = null;
@@ -40,19 +40,18 @@ function cleanupInboundWebRTC() {
 /**
  * Start recording both local and remote audio tracks via MediaRecorder.
  * Mixes them into a single stream using AudioContext.
+ * Used ONLY in legacy (browser-direct) mode.
  */
 export function startCallRecording(pc, localStream, callId) {
   try {
     const ctx = new AudioContext();
     const dest = ctx.createMediaStreamDestination();
 
-    // Add local mic track
     if (localStream) {
       const localSource = ctx.createMediaStreamSource(localStream);
       localSource.connect(dest);
     }
 
-    // Add remote tracks from peer connection
     pc.getReceivers().forEach(receiver => {
       if (receiver.track && receiver.track.kind === 'audio') {
         const remoteStream = new MediaStream([receiver.track]);
@@ -81,6 +80,7 @@ export function startCallRecording(pc, localStream, callId) {
 
 /**
  * Stop recording and upload the audio blob to the backend.
+ * Used ONLY in legacy (browser-direct) mode.
  */
 function stopAndUploadRecording(callId) {
   if (!mediaRecorder || mediaRecorder.state === 'inactive') return;
@@ -110,7 +110,17 @@ function waitForIceGatheringComplete(pc) {
       resolve();
       return;
     }
-    const timeout = setTimeout(() => {
+
+    let timeout = null;
+
+    const cleanup = () => {
+      clearTimeout(timeout);
+      pc.onicegatheringstatechange = null;
+      pc.oniceconnectionstatechange = null;
+    };
+
+    timeout = setTimeout(() => {
+      cleanup();
       // eslint-disable-next-line no-console
       console.warn(
         '[WhatsApp Call] ICE gathering timed out, sending partial SDP'
@@ -120,85 +130,155 @@ function waitForIceGatheringComplete(pc) {
 
     pc.onicegatheringstatechange = () => {
       if (pc.iceGatheringState === 'complete') {
-        clearTimeout(timeout);
+        cleanup();
         resolve();
       }
     };
     pc.oniceconnectionstatechange = () => {
       if (pc.iceConnectionState === 'failed') {
-        clearTimeout(timeout);
+        cleanup();
         reject(new Error('ICE connection failed'));
       }
     };
   });
 }
 
+// ── Server-relay mode: detect by absence of sdpOffer in incoming call data ──
+function isServerRelayCall(call) {
+  return !call.sdpOffer;
+}
+
 /**
- * Core accept logic: creates WebRTC session and posts SDP to backend.
- * Can be called from anywhere — composable, widget, or bubble.
- * Returns { success: true } or { success: false, error }.
+ * Handle an SDP offer from the media server (Peer B). Used in server-relay mode
+ * for both inbound accept and outbound connect flows.
+ *
+ * Flow: getUserMedia -> RTCPeerConnection(iceServers) -> setRemoteDescription(offer)
+ *       -> createAnswer -> waitForICE -> POST /agent_answer
  */
-async function doAcceptCall(call) {
+async function handleAgentOffer(callId, sdpOffer, iceServers) {
   cleanupInboundWebRTC();
 
-  const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
-  inboundStream = stream;
+  try {
+    const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+    inboundStream = stream;
 
-  const iceServers = call.iceServers?.length
-    ? call.iceServers
-    : [{ urls: 'stun:stun.l.google.com:19302' }];
+    const servers = iceServers?.length
+      ? iceServers
+      : [{ urls: 'stun:stun.l.google.com:19302' }];
 
-  const pc = new RTCPeerConnection({ iceServers });
-  inboundPc = pc;
+    const pc = new RTCPeerConnection({ iceServers: servers });
+    inboundPc = pc;
 
-  stream.getTracks().forEach(track => pc.addTrack(track, stream));
+    stream.getTracks().forEach(track => pc.addTrack(track, stream));
 
-  pc.ontrack = event => {
-    const [remoteStream] = event.streams;
-    if (!remoteStream) return;
-    if (!inboundAudio) {
-      const audio = document.createElement('audio');
-      audio.autoplay = true;
-      document.body.appendChild(audio);
-      inboundAudio = audio;
-    }
-    inboundAudio.srcObject = remoteStream;
-    inboundAudio.play().catch(() => {});
+    pc.ontrack = event => {
+      const [remoteStream] = event.streams;
+      if (!remoteStream) return;
+      if (!inboundAudio) {
+        const audio = document.createElement('audio');
+        audio.autoplay = true;
+        document.body.appendChild(audio);
+        inboundAudio = audio;
+      }
+      inboundAudio.srcObject = remoteStream;
+      inboundAudio.play().catch(() => {});
 
-    // Start recording once remote audio is available
-    startCallRecording(pc, stream, call.id);
-  };
+      // No client-side recording in server-relay mode — the media server records
+    };
 
-  await pc.setRemoteDescription({ type: 'offer', sdp: call.sdpOffer });
-  const answer = await pc.createAnswer();
-  await pc.setLocalDescription(answer);
-  await waitForIceGatheringComplete(pc);
+    await pc.setRemoteDescription({ type: 'offer', sdp: sdpOffer });
+    const answer = await pc.createAnswer();
+    await pc.setLocalDescription(answer);
+    await waitForIceGatheringComplete(pc);
 
-  const completeSdp = pc.localDescription.sdp;
-  await WhatsappCallsAPI.accept(call.id, completeSdp);
+    const completeSdp = pc.localDescription.sdp;
+    await WhatsappCallsAPI.agentAnswer(callId, completeSdp);
 
-  return { success: true };
+    return { success: true };
+  } catch (err) {
+    cleanupInboundWebRTC();
+    throw err;
+  }
+}
+
+// Expose handleAgentOffer so ActionCable handler can invoke it
+export { handleAgentOffer };
+
+/**
+ * Legacy mode: creates WebRTC session and posts SDP to backend (browser ↔ Meta).
+ * Can be called from anywhere — composable, widget, or bubble.
+ */
+async function doAcceptCall(call) {
+  // Server-relay mode: just POST /accept without SDP. Wait for agent_offer event.
+  if (isServerRelayCall(call)) {
+    await WhatsappCallsAPI.accept(call.id);
+    return { success: true, awaitingAgentOffer: true };
+  }
+
+  // Legacy mode: full browser-side WebRTC handshake
+  cleanupInboundWebRTC();
+
+  try {
+    const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+    inboundStream = stream;
+
+    const iceServers = call.iceServers?.length
+      ? call.iceServers
+      : [{ urls: 'stun:stun.l.google.com:19302' }];
+
+    const pc = new RTCPeerConnection({ iceServers });
+    inboundPc = pc;
+
+    stream.getTracks().forEach(track => pc.addTrack(track, stream));
+
+    pc.ontrack = event => {
+      const [remoteStream] = event.streams;
+      if (!remoteStream) return;
+      if (!inboundAudio) {
+        const audio = document.createElement('audio');
+        audio.autoplay = true;
+        document.body.appendChild(audio);
+        inboundAudio = audio;
+      }
+      inboundAudio.srcObject = remoteStream;
+      inboundAudio.play().catch(() => {});
+
+      // Start recording once remote audio is available (legacy mode only)
+      startCallRecording(pc, stream, call.id);
+    };
+
+    await pc.setRemoteDescription({ type: 'offer', sdp: call.sdpOffer });
+    const answer = await pc.createAnswer();
+    await pc.setLocalDescription(answer);
+    await waitForIceGatheringComplete(pc);
+
+    const completeSdp = pc.localDescription.sdp;
+    await WhatsappCallsAPI.accept(call.id, completeSdp);
+
+    return { success: true };
+  } catch (err) {
+    cleanupInboundWebRTC();
+    throw err;
+  }
 }
 
 /**
  * Standalone function callable from VoiceCall bubble.
  * Fetches call data if needed, runs WebRTC accept, updates store.
  */
-export async function acceptWhatsappCallById(waCallId) {
+export async function acceptWhatsappCallById(callId) {
   const callsStore = useWhatsappCallsStore();
 
   if (callsStore.hasActiveCall) {
     return { success: false, error: 'active_call_exists' };
   }
 
-  // 1. Check if the call is already in the incoming store
   let call = callsStore.incomingCalls.find(
-    c => c.id === waCallId || c.callId === String(waCallId)
+    c => c.id === callId || c.callId === String(callId)
   );
 
-  // 2. Not in store (page was refreshed) → fetch from API
   if (!call) {
-    const { data } = await WhatsappCallsAPI.show(waCallId);
+    const { data } = await WhatsappCallsAPI.show(callId);
     if (data.status !== 'ringing') {
       return { success: false, error: 'not_ringing' };
     }
@@ -215,19 +295,30 @@ export async function acceptWhatsappCallById(waCallId) {
     callsStore.addIncomingCall(call);
   }
 
-  // 3. Run the WebRTC accept
-  await doAcceptCall(call);
+  try {
+    const result = await doAcceptCall(call);
 
-  // 4. Move from incoming to active
-  callsStore.removeIncomingCall(call.callId);
-  callsStore.setActiveCall({ ...call });
+    callsStore.removeIncomingCall(call.callId);
 
-  return { success: true, call };
+    // In server-relay mode the call becomes active but awaits the agent_offer
+    // ActionCable event to complete WebRTC setup. Mark it with serverRelay flag.
+    const activeCallData = {
+      ...call,
+      serverRelay: isServerRelayCall(call),
+    };
+    callsStore.setActiveCall(activeCallData);
+
+    return { success: true, call: activeCallData, ...result };
+  } catch (err) {
+    callsStore.removeIncomingCall(call.callId);
+    throw err;
+  }
 }
 
 /**
  * Fire-and-forget terminate request using fetch + keepalive.
  * Works reliably inside beforeunload / pagehide where axios won't complete.
+ * Used ONLY in legacy mode. Server-relay mode does NOT terminate on unload.
  */
 function terminateCallOnUnload(callId) {
   const authData = Auth.hasAuthCookie() ? Auth.getAuthData() : {};
@@ -260,9 +351,10 @@ export function useWhatsappCallSession() {
   const isMuted = ref(false);
   const callError = ref(null);
   const callDuration = ref(0);
+  const isReconnecting = computed(() => callsStore.isReconnecting);
 
   const durationTimer = new Timer(elapsed => {
-    callDuration.value = elapsed;
+    callDuration.value = callsStore.callTimerOffset + elapsed;
   });
 
   const activeCall = computed(() => callsStore.activeCall);
@@ -285,16 +377,27 @@ export function useWhatsappCallSession() {
 
   // Register cleanup so external call-end events can teardown WebRTC
   callsStore.registerCleanupCallback(() => {
-    stopAndUploadRecording();
+    // Only do recording cleanup in legacy mode
+    if (!callsStore.isMediaServerEnabled) {
+      stopAndUploadRecording();
+    }
     cleanupInboundWebRTC();
     durationTimer.stop();
     callDuration.value = 0;
   });
 
-  // Terminate active call on page close / reload
+  // On page close / reload:
+  // - Legacy mode: terminate call (current behavior)
+  // - Server-relay mode: just clean up local WebRTC resources, call persists
   const handleBeforeUnload = () => {
     const call = callsStore.activeCall;
-    if (call?.id) {
+    if (!call?.id) return;
+
+    if (call.serverRelay) {
+      // Server-relay: only clean up local resources, do NOT terminate
+      cleanupInboundWebRTC();
+    } else {
+      // Legacy: terminate and clean up
       terminateCallOnUnload(call.id);
       cleanupInboundWebRTC();
     }
@@ -314,7 +417,6 @@ export function useWhatsappCallSession() {
 
   /**
    * Accept an incoming call — used by the floating widget buttons.
-   * Uses the same doAcceptCall core + starts the timer.
    */
   const acceptCall = async call => {
     if (isAccepting.value) return;
@@ -322,10 +424,21 @@ export function useWhatsappCallSession() {
     callError.value = null;
 
     try {
-      await doAcceptCall(call);
+      const result = await doAcceptCall(call);
       callsStore.removeIncomingCall(call.callId);
-      callsStore.setActiveCall({ ...call });
-      durationTimer.start();
+
+      const activeCallData = {
+        ...call,
+        serverRelay: isServerRelayCall(call),
+      };
+      callsStore.setActiveCall(activeCallData);
+
+      // In legacy mode, WebRTC is already established so start timer now.
+      // In server-relay mode, timer starts when handleAgentOffer completes
+      // (triggered by the whatsapp_call.agent_offer ActionCable event).
+      if (!result.awaitingAgentOffer) {
+        durationTimer.start();
+      }
     } catch (err) {
       callError.value =
         err.name === 'NotAllowedError'
@@ -333,7 +446,7 @@ export function useWhatsappCallSession() {
           : t('WHATSAPP_CALL.CALL_FAILED');
       // eslint-disable-next-line no-console
       console.error('[WhatsApp Call] acceptCall error:', err);
-      cleanupInboundWebRTC();
+      // Note: doAcceptCall already cleans up WebRTC resources on error
     } finally {
       isAccepting.value = false;
     }
@@ -353,7 +466,10 @@ export function useWhatsappCallSession() {
     const call = activeCall.value;
     if (!call) return;
 
-    stopAndUploadRecording(call.id);
+    // Only upload recording in legacy mode
+    if (!call.serverRelay) {
+      stopAndUploadRecording(call.id);
+    }
 
     try {
       await WhatsappCallsAPI.terminate(call.id);
@@ -361,7 +477,10 @@ export function useWhatsappCallSession() {
       // Best effort
     } finally {
       cleanupInboundWebRTC();
-      callsStore.handleCallEnded(call.callId);
+      cleanupOutboundCall();
+      // Clear state directly — do NOT use handleCallEnded here since that is
+      // meant for external events (ActionCable) and would invoke cleanupCallback
+      // which would duplicate the cleanup we just performed.
       callsStore.clearActiveCall();
       durationTimer.stop();
       callDuration.value = 0;
@@ -381,6 +500,14 @@ export function useWhatsappCallSession() {
     callsStore.removeIncomingCall(call.callId);
   };
 
+  /**
+   * Start the duration timer. Called externally after server-relay WebRTC
+   * setup completes (handleAgentOffer).
+   */
+  const startDurationTimer = () => {
+    durationTimer.start();
+  };
+
   onUnmounted(() => {
     window.removeEventListener('beforeunload', handleBeforeUnload);
     durationTimer.stop();
@@ -395,6 +522,7 @@ export function useWhatsappCallSession() {
     isAccepting,
     isMuted,
     isOutboundRinging,
+    isReconnecting,
     callError,
     formattedCallDuration,
     acceptCall,
@@ -402,5 +530,6 @@ export function useWhatsappCallSession() {
     endActiveCall,
     toggleMute,
     dismissIncomingCall,
+    startDurationTimer,
   };
 }
diff --git a/app/javascript/dashboard/helper/actionCable.js b/app/javascript/dashboard/helper/actionCable.js
index f3cdbaef9..b34c1cc5f 100644
--- a/app/javascript/dashboard/helper/actionCable.js
+++ b/app/javascript/dashboard/helper/actionCable.js
@@ -8,6 +8,7 @@ import {
   useWhatsappCallsStore,
   getOutboundCallState,
 } from 'dashboard/stores/whatsappCalls';
+import { handleAgentOffer } from 'dashboard/composables/useWhatsappCallSession';
 
 const { isImpersonating } = useImpersonation();
 
@@ -43,6 +44,7 @@ class ActionCableConnector extends BaseActionCableConnector {
       'whatsapp_call.ended': this.onWhatsappCallEnded,
       'whatsapp_call.outbound_connected': this.onWhatsappCallOutboundConnected,
       'whatsapp_call.permission_granted': this.onWhatsappCallPermissionGranted,
+      'whatsapp_call.agent_offer': this.onWhatsappCallAgentOffer,
     };
   }
 
@@ -213,6 +215,8 @@ class ActionCableConnector extends BaseActionCableConnector {
   // eslint-disable-next-line class-methods-use-this
   onWhatsappCallIncoming = data => {
     const whatsappCallsStore = useWhatsappCallsStore();
+    // In server-relay mode, sdp_offer and ice_servers are absent — the media
+    // server handles WebRTC with Meta, and the browser only needs call metadata.
     whatsappCallsStore.addIncomingCall({
       id: data.id,
       callId: data.call_id,
@@ -220,8 +224,8 @@ class ActionCableConnector extends BaseActionCableConnector {
       inboxId: data.inbox_id,
       conversationId: data.conversation_id,
       caller: data.caller,
-      sdpOffer: data.sdp_offer,
-      iceServers: data.ice_servers,
+      sdpOffer: data.sdp_offer || null,
+      iceServers: data.ice_servers || null,
     });
   };
 
@@ -242,6 +246,31 @@ class ActionCableConnector extends BaseActionCableConnector {
 
   // eslint-disable-next-line class-methods-use-this
   onWhatsappCallOutboundConnected = data => {
+    const whatsappCallsStore = useWhatsappCallsStore();
+
+    // Server-relay mode: data contains sdp_offer (media server generated offer
+    // for Peer B) instead of sdp_answer.
+    if (data.sdp_offer) {
+      const activeCall = whatsappCallsStore.activeCall;
+      if (activeCall && activeCall.callId === data.call_id) {
+        handleAgentOffer(activeCall.id, data.sdp_offer, data.ice_servers)
+          .then(() => {
+            whatsappCallsStore.markActiveCallConnected();
+            // Emit event so the composable can start the timer
+            emitter.emit('whatsapp_call:agent_webrtc_connected');
+          })
+          .catch(err => {
+            // eslint-disable-next-line no-console
+            console.error(
+              '[WhatsApp Call] Failed to handle outbound agent offer:',
+              err
+            );
+          });
+      }
+      return;
+    }
+
+    // Legacy mode: data contains sdp_answer (Meta's answer to browser's offer)
     const { pc, callId } = getOutboundCallState();
     if (pc && callId === data.call_id && data.sdp_answer) {
       pc.setRemoteDescription({ type: 'answer', sdp: data.sdp_answer }).catch(
@@ -258,11 +287,34 @@ class ActionCableConnector extends BaseActionCableConnector {
 
   // eslint-disable-next-line class-methods-use-this
   onWhatsappCallPermissionGranted = data => {
-    emitter.emit(BUS_EVENTS.SHOW_ALERT, {
-      message: `${data.contact_name} approved the call permission request. You can now call them.`,
-      type: 'success',
+    emitter.emit('whatsapp_call:permission_granted', {
+      contactName: data.contact_name,
     });
   };
+
+  // Server-relay mode: the media server created Peer B and sent an SDP offer
+  // for the agent's browser. This fires after POST /accept or POST /reconnect.
+  // eslint-disable-next-line class-methods-use-this
+  onWhatsappCallAgentOffer = data => {
+    const whatsappCallsStore = useWhatsappCallsStore();
+    const activeCall = whatsappCallsStore.activeCall;
+
+    if (!activeCall) return;
+    // Verify this offer is for the current active call
+    if (activeCall.callId !== data.call_id && activeCall.id !== data.id) return;
+
+    handleAgentOffer(activeCall.id, data.sdp_offer, data.ice_servers)
+      .then(() => {
+        whatsappCallsStore.markActiveCallConnected();
+        whatsappCallsStore.setReconnecting(false);
+        // Emit event so the composable can start the timer
+        emitter.emit('whatsapp_call:agent_webrtc_connected');
+      })
+      .catch(err => {
+        // eslint-disable-next-line no-console
+        console.error('[WhatsApp Call] Failed to handle agent offer:', err);
+      });
+  };
 }
 
 export default {
diff --git a/app/javascript/dashboard/i18n/locale/en/whatsappCall.json b/app/javascript/dashboard/i18n/locale/en/whatsappCall.json
index 1df29be07..e68e29a7e 100644
--- a/app/javascript/dashboard/i18n/locale/en/whatsappCall.json
+++ b/app/javascript/dashboard/i18n/locale/en/whatsappCall.json
@@ -15,6 +15,8 @@
     "PERMISSION_PENDING": "Waiting for the contact to approve the call permission request. Please try again shortly.",
     "UNKNOWN_CALLER": "Unknown caller",
     "MIC_DENIED": "Microphone access denied. Please allow mic access and try again.",
-    "CALL_TAKEN": "Call accepted by another agent"
+    "CALL_TAKEN": "Call accepted by another agent",
+    "RECONNECTING": "Reconnecting…",
+    "PERMISSION_GRANTED": "{contactName} approved the call permission request. You can now call them."
   }
 }
diff --git a/app/javascript/dashboard/stores/whatsappCalls.js b/app/javascript/dashboard/stores/whatsappCalls.js
index 633e54977..e9bef5dac 100644
--- a/app/javascript/dashboard/stores/whatsappCalls.js
+++ b/app/javascript/dashboard/stores/whatsappCalls.js
@@ -2,6 +2,8 @@ import { defineStore } from 'pinia';
 
 // Module-scoped (non-reactive) state for outbound call WebRTC objects.
 // These cannot be in Pinia state because RTCPeerConnection/MediaStream are not serializable.
+// Used ONLY in legacy (browser-direct) mode. In server-relay mode outbound calls
+// go through the same inbound WebRTC path via handleAgentOffer.
 const outboundCall = { pc: null, stream: null, audio: null, callId: null };
 
 export function getOutboundCallState() {
@@ -12,7 +14,7 @@ export function setOutboundCallProperty(key, value) {
   outboundCall[key] = value;
 }
 
-function cleanupOutboundCall() {
+export function cleanupOutboundCall() {
   if (outboundCall.pc) outboundCall.pc.close();
   if (outboundCall.stream) {
     outboundCall.stream.getTracks().forEach(t => t.stop());
@@ -35,6 +37,10 @@ export const useWhatsappCallsStore = defineStore('whatsappCalls', {
     activeCall: null,
     // Cleanup callback registered by the composable — called when a call ends externally
     cleanupCallback: null,
+    // True while the agent is reconnecting to an active call after page reload
+    isReconnecting: false,
+    // Seconds already elapsed when reconnecting — timer resumes from this offset
+    callTimerOffset: 0,
   }),
 
   getters: {
@@ -43,6 +49,13 @@ export const useWhatsappCallsStore = defineStore('whatsappCalls', {
     hasWhatsappCall: state =>
       state.incomingCalls.length > 0 || state.activeCall !== null,
     firstIncomingCall: state => state.incomingCalls[0] || null,
+
+    // Returns true when the active call is operating through the media server
+    // (server-relay mode). Detected by the absence of sdpOffer in the call data
+    // — in legacy mode the incoming call ActionCable event includes sdpOffer.
+    isMediaServerEnabled() {
+      return this.activeCall?.serverRelay === true;
+    },
   },
 
   actions: {
@@ -62,6 +75,8 @@ export const useWhatsappCallsStore = defineStore('whatsappCalls', {
 
     clearActiveCall() {
       this.activeCall = null;
+      this.callTimerOffset = 0;
+      this.isReconnecting = false;
     },
 
     markActiveCallConnected() {
@@ -74,6 +89,14 @@ export const useWhatsappCallsStore = defineStore('whatsappCalls', {
       this.cleanupCallback = callback;
     },
 
+    setReconnecting(value) {
+      this.isReconnecting = value;
+    },
+
+    setTimerOffset(seconds) {
+      this.callTimerOffset = seconds;
+    },
+
     handleCallAcceptedByOther(callId) {
       this.removeIncomingCall(callId);
     },
@@ -81,10 +104,14 @@ export const useWhatsappCallsStore = defineStore('whatsappCalls', {
     handleCallEnded(callId) {
       this.removeIncomingCall(callId);
       if (this.activeCall?.callId === callId) {
-        this.activeCall = null;
+        // Invoke cleanup BEFORE clearing activeCall so the callback can
+        // check isMediaServerEnabled (which depends on activeCall.serverRelay)
         if (this.cleanupCallback) {
           this.cleanupCallback();
         }
+        this.activeCall = null;
+        this.callTimerOffset = 0;
+        this.isReconnecting = false;
       }
       if (outboundCall.callId === callId) {
         cleanupOutboundCall();
diff --git a/config/routes.rb b/config/routes.rb
index be735231a..7ee28d8f4 100644
--- a/config/routes.rb
+++ b/config/routes.rb
@@ -304,15 +304,26 @@ Rails.application.routes.draw do
           end
 
           resources :whatsapp_calls, only: [:show] do
+            collection do
+              get :active
+              post :initiate
+            end
             member do
               post :accept
               post :reject
               post :terminate
+              post :agent_answer
+              post :reconnect
+              post :join
+              post :play_audio
               post :upload_recording
             end
-            collection do
-              post :initiate
-            end
+          end
+
+          namespace :media_server do
+            post 'callbacks/agent_disconnected', to: 'callbacks#agent_disconnected'
+            post 'callbacks/recording_ready', to: 'callbacks#recording_ready'
+            post 'callbacks/session_terminated', to: 'callbacks#session_terminated'
           end
 
           resources :webhooks, only: [:index, :create, :update, :destroy]
diff --git a/db/migrate/20260421042235_add_media_server_fields_to_calls.rb b/db/migrate/20260421042235_add_media_server_fields_to_calls.rb
new file mode 100644
index 000000000..bcbfe0fbe
--- /dev/null
+++ b/db/migrate/20260421042235_add_media_server_fields_to_calls.rb
@@ -0,0 +1,7 @@
+class AddMediaServerFieldsToCalls < ActiveRecord::Migration[7.0]
+  def change
+    add_column :calls, :media_session_id, :string
+    add_index :calls, :media_session_id, unique: true
+    add_index :calls, [:accepted_by_agent_id, :status]
+  end
+end
diff --git a/db/schema.rb b/db/schema.rb
index e2d3d75df..40d84a636 100644
--- a/db/schema.rb
+++ b/db/schema.rb
@@ -10,7 +10,7 @@
 #
 # It's strongly recommended that you check this file into your version control system.
 
-ActiveRecord::Schema[7.1].define(version: 2026_04_09_091202) do
+ActiveRecord::Schema[7.1].define(version: 2026_04_21_042235) do
   # These extensions should be enabled to support this database
   enable_extension "pg_stat_statements"
   enable_extension "pg_trgm"
@@ -282,9 +282,11 @@ ActiveRecord::Schema[7.1].define(version: 2026_04_09_091202) do
     t.text "transcript"
     t.datetime "created_at", null: false
     t.datetime "updated_at", null: false
+    t.string "media_session_id"
+    t.index ["accepted_by_agent_id", "status"], name: "index_calls_on_accepted_by_agent_id_and_status"
     t.index ["account_id", "conversation_id"], name: "index_calls_on_account_id_and_conversation_id"
+    t.index ["media_session_id"], name: "index_calls_on_media_session_id", unique: true
     t.index ["message_id"], name: "index_calls_on_message_id"
-    t.index ["meta"], name: "index_calls_on_meta", using: :gin
     t.index ["provider", "provider_call_id"], name: "index_calls_on_provider_and_provider_call_id", unique: true
   end
 
diff --git a/docker-compose.production.yaml b/docker-compose.production.yaml
index bf6ecbb6b..fc53a6af0 100644
--- a/docker-compose.production.yaml
+++ b/docker-compose.production.yaml
@@ -57,7 +57,34 @@ services:
     ports:
       - '127.0.0.1:6379:6379'
 
+  # Optional: WhatsApp Calling media server (server-side WebRTC relay)
+  # Uncomment to enable call persistence across page reloads and server-side recording.
+  # media-server:
+  #   image: chatwoot/media-server:latest
+  #   env_file: .env
+  #   ports:
+  #     - '4000:4000'
+  #     - '10000-10100:10000-10100/udp'
+  #   environment:
+  #     - AUTH_TOKEN=${MEDIA_SERVER_AUTH_TOKEN}
+  #     - RAILS_CALLBACK_URL=http://rails:3000
+  #     - RECORDINGS_DIR=/recordings
+  #     - LOG_LEVEL=info
+  #     - UDP_PORT_MIN=10000
+  #     - UDP_PORT_MAX=10100
+  #     - PUBLIC_IP=${MEDIA_SERVER_PUBLIC_IP}
+  #     - STUN_SERVERS=stun:stun.l.google.com:19302
+  #   volumes:
+  #     - media_recordings:/recordings
+  #   restart: always
+  #   healthcheck:
+  #     test: ['CMD', 'wget', '--spider', '-q', 'http://localhost:4000/health']
+  #     interval: 10s
+  #     timeout: 5s
+  #     retries: 3
+
 volumes:
   storage_data:
   postgres_data:
   redis_data:
+  # media_recordings:
diff --git a/docker-compose.yaml b/docker-compose.yaml
index facac830f..f08cb79e1 100644
--- a/docker-compose.yaml
+++ b/docker-compose.yaml
@@ -110,6 +110,32 @@ services:
       - 1025:1025
       - 8025:8025
 
+  media-server:
+    image: chatwoot/media-server:latest
+    build:
+      context: ./enterprise/media-server
+      dockerfile: Dockerfile
+    ports:
+      - '4000:4000'
+      - '10000-10100:10000-10100/udp'
+    environment:
+      - AUTH_TOKEN=${MEDIA_SERVER_AUTH_TOKEN:-}
+      - RAILS_CALLBACK_URL=http://rails:3000
+      - RECORDINGS_DIR=/recordings
+      - LOG_LEVEL=info
+      - UDP_PORT_MIN=10000
+      - UDP_PORT_MAX=10100
+      - PUBLIC_IP=${MEDIA_SERVER_PUBLIC_IP:-}
+      - STUN_SERVERS=stun:stun.l.google.com:19302
+    volumes:
+      - media_recordings:/recordings
+    restart: unless-stopped
+    healthcheck:
+      test: ['CMD', 'wget', '--spider', '-q', 'http://localhost:4000/health']
+      interval: 10s
+      timeout: 5s
+      retries: 3
+
 volumes:
   postgres:
   redis:
@@ -117,3 +143,4 @@ volumes:
   node_modules:
   cache:
   bundle:
+  media_recordings:
diff --git a/docs/SERVER_SIDE_WEBRTC_ARCHITECTURE.md b/docs/SERVER_SIDE_WEBRTC_ARCHITECTURE.md
new file mode 100644
index 000000000..5af83b932
--- /dev/null
+++ b/docs/SERVER_SIDE_WEBRTC_ARCHITECTURE.md
@@ -0,0 +1,1504 @@
+# Server-Side WebRTC Architecture for WhatsApp Calling
+
+## Executive Summary
+
+This document designs a migration from browser-based WebRTC to server-side WebRTC for
+Chatwoot's WhatsApp Calling feature. The new architecture places a **Pion-based Go
+sidecar** (called `chatwoot-media-server`) between Meta's media servers and the agent's
+browser. This gives us call persistence across page reloads, server-side recording,
+and centralized call lifecycle management -- all without modifying the existing Rails
+application server in a language-incompatible way.
+
+---
+
+## Table of Contents
+
+1. [Technology Recommendation](#1-technology-recommendation)
+2. [System Architecture](#2-system-architecture)
+3. [Component Interaction Flows](#3-component-interaction-flows)
+4. [Inbound Call Flow](#4-inbound-call-flow)
+5. [Outbound Call Flow](#5-outbound-call-flow)
+6. [Recording Pipeline](#6-recording-pipeline)
+7. [Frontend-to-Backend Audio Relay](#7-frontend-to-backend-audio-relay)
+8. [Call Lifecycle and Reconnection](#8-call-lifecycle-and-reconnection)
+9. [Database Schema Changes](#9-database-schema-changes)
+10. [File Structure](#10-file-structure)
+11. [Deployment Architecture](#11-deployment-architecture)
+12. [Scalability Analysis](#12-scalability-analysis)
+13. [Security Considerations](#13-security-considerations)
+14. [Pros, Cons, and Trade-offs](#14-pros-cons-and-trade-offs)
+15. [Migration Path](#15-migration-path)
+
+---
+
+## 1. Technology Recommendation
+
+### Evaluation Matrix
+
+| Criterion                    | Janus (C)  | mediasoup (Node) | Pion (Go)      | GStreamer+WebRTC (C) |
+|------------------------------|------------|-------------------|----------------|----------------------|
+| WebRTC standard compliance   | Full       | Full (SFU only)   | Full           | Full                 |
+| Can act as WebRTC endpoint   | Yes        | No (SFU, not endpoint) | Yes        | Yes                  |
+| SDP offer/answer handling    | Plugin API | JS API            | Native Go API  | GStreamer pipeline   |
+| Audio mixing/recording       | Plugins    | External           | Manual + Opus  | Native pipelines     |
+| Operational complexity       | High (C, plugins, Lua) | Medium  | Low            | High (pipelines)     |
+| Docker image size            | ~200 MB    | ~150 MB           | ~15-30 MB      | ~300 MB              |
+| Concurrent call capacity     | High       | High              | Very high      | High                 |
+| Memory per call              | ~5 MB      | ~3 MB             | ~1-2 MB        | ~8 MB                |
+| Language interop with Rails  | HTTP/WS    | HTTP/WS           | HTTP/gRPC      | CLI/HTTP             |
+| Community / maintenance      | Active     | Active            | Very active    | Active               |
+| Learning curve for team      | Steep      | Moderate          | Moderate       | Steep                |
+
+### Recommendation: Pion (Go sidecar)
+
+**Pion** is the best fit for this use case. Here is the rationale:
+
+1. **Full WebRTC endpoint capability.** Pion can hold an `RTCPeerConnection` on the
+   server side -- it is not just an SFU. It can receive Meta's SDP offer, generate an
+   SDP answer, and establish a direct SRTP audio session with Meta's media servers.
+   mediasoup cannot do this; it is an SFU that only forwards packets between peers.
+
+2. **Lightweight.** A statically-compiled Go binary produces a Docker image under 30 MB.
+   No plugin system, no Lua, no native dependency chain. This matters for Chatwoot's
+   self-hosted deployment model.
+
+3. **Audio recording is straightforward.** Pion gives access to raw RTP packets and
+   decoded Opus frames. Writing them to an OGG/Opus container (or decoding to PCM for
+   WAV) is well-documented in Pion's examples. No GStreamer pipeline needed.
+
+4. **Excellent concurrency.** Go's goroutine model handles thousands of concurrent
+   connections with minimal memory overhead. Each active call consumes approximately
+   1-2 MB of memory (RTP buffers + SRTP context).
+
+5. **Clean integration surface.** The Go sidecar exposes a simple HTTP/gRPC API that
+   Rails calls. No shared memory, no FFI, no process spawning.
+
+6. **Active ecosystem.** Pion has 13k+ GitHub stars, weekly releases, and an active
+   Discord. The `pion/webrtc`, `pion/rtp`, `pion/opus`, and `pion/interceptor`
+   packages cover all requirements.
+
+### Why not the others
+
+- **Janus**: Overkill. Requires maintaining C plugins, Lua scripting, and a complex
+  configuration. Designed for multi-party video conferencing, not 1:1 audio relay.
+- **mediasoup**: Cannot act as a WebRTC endpoint. It is an SFU that forwards media
+  between browser peers. Meta expects to negotiate with a single WebRTC peer, not a
+  forwarding unit.
+- **GStreamer**: Powerful but heavy. Pipeline-based architecture is great for complex
+  media processing, but adds significant operational complexity for what is
+  fundamentally a simple audio relay + recording task.
+
+---
+
+## 2. System Architecture
+
+### High-Level Diagram
+
+```
+                                                    CHATWOOT SERVER
+                                    ┌─────────────────────────────────────────────────────┐
+                                    │                                                     │
+ ┌──────────────┐                   │  ┌────────────────┐       ┌──────────────────────┐  │
+ │   WhatsApp   │  Webhook          │  │                │ HTTP  │                      │  │
+ │   Contact    │  (signaling)      │  │   Rails App    │◄─────►│  chatwoot-media-     │  │
+ │              │─────────────────────►│   (Puma/       │       │  server (Pion Go)    │  │
+ └──────┬───────┘                   │  │    Sidekiq)    │       │                      │  │
+        │                           │  │                │       │  Holds WebRTC peers: │  │
+        │                           │  └───────┬────────┘       │  - Meta-side peer    │  │
+        │                           │          │                │  - Agent-side peer   │  │
+        │                           │          │ ActionCable    │  - Recording engine  │  │
+        │                           │          │ (WebSocket)    │                      │  │
+        │   ┌────────────────────┐  │          │                └──────────┬───────────┘  │
+        │   │   Meta Media       │  │          │                          │               │
+        │   │   Servers          │  │          │                  SRTP    │ SRTP          │
+        │   │                    │  │          │             (Meta side)  │ (Agent side)  │
+        └──►│  Routes audio      │◄═══════════╪══════════════════════════╡               │
+            │  between endpoints │  │          │                         │               │
+            └────────────────────┘  │  ┌───────▼────────┐               │               │
+                                    │  │   Agent's      │◄══════════════╡               │
+                                    │  │   Browser      │  WebRTC audio │               │
+                                    │  │   (Vue.js)     │  (SRTP)       │               │
+                                    │  │                │               │               │
+                                    │  └────────────────┘               │               │
+                                    │                                   │               │
+                                    │                     ┌─────────────▼───────────┐   │
+                                    │                     │   Recording Pipeline     │   │
+                                    │                     │                         │   │
+                                    │                     │   OGG/Opus file         │   │
+                                    │                     │   → ActiveStorage       │   │
+                                    │                     └─────────────────────────┘   │
+                                    └─────────────────────────────────────────────────────┘
+```
+
+### Two-Peer Bridge Architecture
+
+The media server maintains **two independent WebRTC peer connections per call** and
+bridges audio between them:
+
+```
+  Meta Media Servers                chatwoot-media-server              Agent Browser
+  ════════════════                  ═══════════════════                 ══════════════
+                         SRTP                                  SRTP
+  ┌──────────────┐  ◄═══════════►  ┌──────────────┐  ◄═══════════►  ┌──────────────┐
+  │              │                  │              │                  │              │
+  │  Meta's      │    Peer A        │  Pion Go     │    Peer B        │  Browser     │
+  │  WebRTC      │    (Meta-side    │  process     │    (Agent-side   │  WebRTC      │
+  │  endpoint    │     connection)  │              │     connection)  │  RTCPeerConn │
+  │              │                  │              │                  │              │
+  └──────────────┘                  │  ┌────────┐  │                  └──────────────┘
+                                    │  │ Audio   │  │
+                                    │  │ Bridge  │  │
+                                    │  │         │  │
+                                    │  │ A→B     │  │
+                                    │  │ B→A     │  │
+                                    │  │         │  │
+                                    │  │ +Record │  │
+                                    │  └────────┘  │
+                                    └──────────────┘
+```
+
+**Why two peers instead of one:**
+
+Meta's WebRTC endpoint negotiates a standard peer connection. The agent's browser also
+needs a standard peer connection. The media server sits in the middle as a "back-to-back
+user agent" (B2BUA), forwarding RTP packets between the two peers while also tapping
+into the streams for recording.
+
+This is a well-established pattern in VoIP (analogous to a SIP B2BUA). Each peer
+connection is independent: Meta does not know about the agent, the agent does not know
+about Meta. The media server handles codec negotiation, SRTP encryption/decryption, and
+RTP forwarding for both sides.
+
+---
+
+## 3. Component Interaction Flows
+
+### Component Responsibilities
+
+```
+┌─────────────────────────────────────────────────────────────────────────────────────┐
+│                                                                                     │
+│  RAILS APP (existing, modified)                                                    │
+│  ─────────────────────────────                                                     │
+│  - Receives Meta webhooks (call connect/terminate events)                          │
+│  - Manages Call model lifecycle (DB records, status transitions)                   │
+│  - Delegates SDP handling to media server via internal HTTP API                    │
+│  - Broadcasts ActionCable events to agent browsers                                 │
+│  - Stores recordings in ActiveStorage after media server delivers them             │
+│  - Runs transcription jobs (unchanged)                                             │
+│                                                                                     │
+│  CHATWOOT-MEDIA-SERVER (new, Go/Pion)                                              │
+│  ────────────────────────────────────                                               │
+│  - Holds Meta-side WebRTC peer connection (Peer A)                                 │
+│  - Holds Agent-side WebRTC peer connection (Peer B)                                │
+│  - Bridges audio packets between Peer A and Peer B                                 │
+│  - Records both audio streams to disk (OGG/Opus)                                  │
+│  - Manages ICE/STUN/TURN for both peers                                            │
+│  - Exposes HTTP API for Rails to control call sessions                             │
+│  - Reports call events back to Rails via HTTP callbacks                            │
+│                                                                                     │
+│  AGENT BROWSER (modified)                                                          │
+│  ────────────────────────                                                          │
+│  - Establishes WebRTC peer connection to media server (NOT to Meta directly)       │
+│  - Sends/receives audio via standard WebRTC (getUserMedia + RTCPeerConnection)     │
+│  - No longer handles recording (server does it)                                    │
+│  - Can reconnect to an active call after page reload                               │
+│  - Receives SDP offer from media server via ActionCable, responds with answer      │
+│                                                                                     │
+└─────────────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Media Server Internal HTTP API
+
+The Go sidecar exposes the following HTTP endpoints, accessible only from the Rails
+process (bound to localhost or internal network):
+
+```
+POST   /sessions                    Create a new call session
+POST   /sessions/:id/meta-sdp      Set Meta's SDP offer and get server's SDP answer
+POST   /sessions/:id/agent-offer   Get SDP offer for agent-side peer
+POST   /sessions/:id/agent-answer  Set agent's SDP answer for agent-side peer
+POST   /sessions/:id/terminate     Tear down both peers and finalize recording
+GET    /sessions/:id/status        Get session status (peers connected, ICE state)
+GET    /sessions/:id/recording     Download the finalized recording file
+DELETE /sessions/:id               Force-destroy a session
+
+POST   /sessions/:id/agent-reconnect  Generate new agent-side offer for reconnection
+```
+
+Authentication between Rails and the media server uses a shared secret token passed as
+a Bearer header, configured via environment variable `MEDIA_SERVER_AUTH_TOKEN`.
+
+---
+
+## 4. Inbound Call Flow
+
+```
+  WhatsApp              Meta                 Chatwoot            Media              Agent
+  Contact              Cloud                 Backend             Server             Browser
+    │                    │                     │                    │                   │
+ 1. │── Dials ──────────►│                     │                    │                   │
+    │  business #        │                     │                    │                   │
+    │                    │                     │                    │                   │
+ 2. │                    │── Webhook ──────────►│                    │                   │
+    │                    │  event: connect      │                    │                   │
+    │                    │  {id, from,          │                    │                   │
+    │                    │   sdp_offer}         │                    │                   │
+    │                    │                     │                    │                   │
+ 3. │                    │               ┌─────┴──────┐             │                   │
+    │                    │               │ Incoming    │             │                   │
+    │                    │               │ CallService │             │                   │
+    │                    │               │             │             │                   │
+    │                    │               │ a. Contact  │             │                   │
+    │                    │               │ b. Convo    │             │                   │
+    │                    │               │ c. Call rec │             │                   │
+    │                    │               └─────┬──────┘             │                   │
+    │                    │                     │                    │                   │
+ 4. │                    │                     │── POST /sessions ─►│                   │
+    │                    │                     │   {call_id,        │                   │
+    │                    │                     │    meta_sdp_offer} │                   │
+    │                    │                     │                    │                   │
+ 5. │                    │                     │              ┌─────┴──────┐            │
+    │                    │                     │              │ Create     │            │
+    │                    │                     │              │ Peer A     │            │
+    │                    │                     │              │ (Meta-side)│            │
+    │                    │                     │              │            │            │
+    │                    │                     │              │ Set remote │            │
+    │                    │                     │              │ desc (SDP  │            │
+    │                    │                     │              │ offer)     │            │
+    │                    │                     │              │            │            │
+    │                    │                     │              │ Create     │            │
+    │                    │                     │              │ answer     │            │
+    │                    │                     │              │ + ICE      │            │
+    │                    │                     │              │ gather     │            │
+    │                    │                     │              └─────┬──────┘            │
+    │                    │                     │                    │                   │
+ 6. │                    │                     │◄── {sdp_answer,   │                   │
+    │                    │                     │     session_id}    │                   │
+    │                    │                     │                    │                   │
+ 7. │                    │                     │  Store session_id  │                   │
+    │                    │                     │  in Call.meta      │                   │
+    │                    │                     │                    │                   │
+    │                    │                     │  NOTE: Do NOT send │                   │
+    │                    │                     │  SDP answer to Meta│                   │
+    │                    │                     │  yet. Wait for     │                   │
+    │                    │                     │  agent to accept.  │                   │
+    │                    │                     │                    │                   │
+ 8. │                    │                     │── ActionCable ─────────────────────────►│
+    │                    │                     │  whatsapp_call.incoming                 │
+    │                    │                     │  {id, call_id, caller, conversation_id} │
+    │                    │                     │  (NO sdp_offer -- agent doesn't need it)│
+    │                    │                     │                    │                   │
+ 9. │                    │                     │                    │            ┌──────┴───┐
+    │                    │                     │                    │            │ Widget:  │
+    │                    │                     │                    │            │ "Incoming│
+    │                    │                     │                    │            │  call"   │
+    │                    │                     │                    │            │ [Accept] │
+    │                    │                     │                    │            │ [Reject] │
+    │                    │                     │                    │            └──────┬───┘
+    │                    │                     │                    │                   │
+    │                    │                     │                    │    Agent clicks    │
+    │                    │                     │                    │    "Accept"        │
+    │                    │                     │                    │                   │
+10. │                    │                     │◄── POST /accept ──────────────────────│
+    │                    │                     │   {call_id}        │                   │
+    │                    │                     │   (NO sdp_answer   │                   │
+    │                    │                     │    from browser!)   │                   │
+    │                    │                     │                    │                   │
+11. │                    │               ┌─────┴──────┐             │                   │
+    │                    │               │ CallService│             │                   │
+    │                    │               │ (row lock) │             │                   │
+    │                    │               │            │             │                   │
+    │                    │               │ Validate   │             │                   │
+    │                    │               │ still ring │             │                   │
+    │                    │               └─────┬──────┘             │                   │
+    │                    │                     │                    │                   │
+12. │                    │◄── pre_accept ──────│                    │                   │
+    │                    │    + accept          │                    │                   │
+    │                    │    (SDP from media   │                    │                   │
+    │                    │     server, stored   │                    │                   │
+    │                    │     in Call.meta)    │                    │                   │
+    │                    │                     │                    │                   │
+13. │◄════════════ Audio (SRTP) ═══════════════════════════════════►│ (Peer A)         │
+    │                    │                     │                    │                   │
+    │                    │                     │                    │                   │
+14. │                    │                     │── POST /sessions/  │                   │
+    │                    │                     │   :id/agent-offer ►│                   │
+    │                    │                     │                    │                   │
+15. │                    │                     │              ┌─────┴──────┐            │
+    │                    │                     │              │ Create     │            │
+    │                    │                     │              │ Peer B     │            │
+    │                    │                     │              │ (agent-    │            │
+    │                    │                     │              │  side)     │            │
+    │                    │                     │              │            │            │
+    │                    │                     │              │ Create     │            │
+    │                    │                     │              │ SDP offer  │            │
+    │                    │                     │              │ for agent  │            │
+    │                    │                     │              └─────┬──────┘            │
+    │                    │                     │                    │                   │
+16. │                    │                     │◄── {sdp_offer} ───│                   │
+    │                    │                     │                    │                   │
+17. │                    │                     │── ActionCable ─────────────────────────►│
+    │                    │                     │  whatsapp_call.agent_offer              │
+    │                    │                     │  {sdp_offer, ice_servers}               │
+    │                    │                     │                    │                   │
+18. │                    │                     │                    │            ┌──────┴───┐
+    │                    │                     │                    │            │getUserMe-│
+    │                    │                     │                    │            │dia(audio)│
+    │                    │                     │                    │            │          │
+    │                    │                     │                    │            │setRemote-│
+    │                    │                     │                    │            │Desc(offer│
+    │                    │                     │                    │            │from media│
+    │                    │                     │                    │            │server)   │
+    │                    │                     │                    │            │          │
+    │                    │                     │                    │            │createAns-│
+    │                    │                     │                    │            │wer + ICE │
+    │                    │                     │                    │            └──────┬───┘
+    │                    │                     │                    │                   │
+19. │                    │                     │◄── POST /agent-answer ────────────────│
+    │                    │                     │   {sdp_answer}     │                   │
+    │                    │                     │                    │                   │
+20. │                    │                     │── POST /sessions/  │                   │
+    │                    │                     │   :id/agent-answer►│                   │
+    │                    │                     │                    │                   │
+21. │                    │                     │              ┌─────┴──────┐            │
+    │                    │                     │              │ Set agent  │            │
+    │                    │                     │              │ SDP answer │            │
+    │                    │                     │              │ on Peer B  │            │
+    │                    │                     │              │            │            │
+    │                    │                     │              │ Bridge     │            │
+    │                    │                     │              │ audio:     │            │
+    │                    │                     │              │ A <-> B    │            │
+    │                    │                     │              │            │            │
+    │                    │                     │              │ Start      │            │
+    │                    │                     │              │ recording  │            │
+    │                    │                     │              └─────┬──────┘            │
+    │                    │                     │                    │                   │
+22. │◄══════ Audio (Meta ↔ Media Server) ════►│◄══ Audio (Media Server ↔ Browser) ══►│
+    │                    │                     │                    │                   │
+    │  Agent hears customer, customer hears agent. Recording captures both.           │
+```
+
+### Key Differences from Current Architecture
+
+| Aspect                       | Current (browser WebRTC)              | New (server WebRTC)                    |
+|------------------------------|---------------------------------------|----------------------------------------|
+| Who answers Meta's SDP       | Agent's browser                       | Media server (Pion)                    |
+| Audio path                   | Meta <-> Browser (direct)             | Meta <-> Media Server <-> Browser      |
+| Accept API payload           | Browser sends `sdp_answer`            | Browser sends nothing (just call ID)   |
+| SDP answer source            | Browser's RTCPeerConnection           | Media server's Pion peer               |
+| Agent-side connection        | N/A (direct to Meta)                  | Separate WebRTC peer (Peer B)          |
+| Recording                    | Browser MediaRecorder                 | Media server OGG/Opus writer           |
+| Survives page reload         | No (active call dies)                 | Yes (Peer A stays up, Peer B reconnects)|
+| SDP fix (actpass -> active)  | Backend string replacement            | Media server generates correct SDP     |
+
+---
+
+## 5. Outbound Call Flow
+
+```
+  Agent                 Chatwoot              Media               Meta              WhatsApp
+  Browser               Backend               Server              Cloud             Contact
+    │                     │                     │                    │                   │
+ 1. │── Click phone icon  │                     │                    │                   │
+    │                     │                     │                    │                   │
+ 2. │── POST /initiate ──►│                     │                    │                   │
+    │  {conversation_id}  │                     │                    │                   │
+    │  (NO sdp_offer      │                     │                    │                   │
+    │   from browser!)    │                     │                    │                   │
+    │                     │                     │                    │                   │
+ 3. │                     │── POST /sessions ──►│                    │                   │
+    │                     │  {call_id: temp,    │                    │                   │
+    │                     │   direction: out}   │                    │                   │
+    │                     │                     │                    │                   │
+ 4. │                     │              ┌──────┴───────┐            │                   │
+    │                     │              │ Create Peer A │            │                   │
+    │                     │              │ (Meta-side)   │            │                   │
+    │                     │              │               │            │                   │
+    │                     │              │ Create SDP    │            │                   │
+    │                     │              │ offer for     │            │                   │
+    │                     │              │ Meta          │            │                   │
+    │                     │              └──────┬───────┘            │                   │
+    │                     │                     │                    │                   │
+ 5. │                     │◄── {sdp_offer,      │                    │                   │
+    │                     │     session_id}     │                    │                   │
+    │                     │                     │                    │                   │
+ 6. │                     │── initiate_call ────────────────────────►│                   │
+    │                     │  {to, sdp_offer     │                    │── Rings phone ──►│
+    │                     │   from media server}│                    │                   │
+    │                     │                     │                    │                   │
+    │                     │◄── {call_id} ───────────────────────────│                   │
+    │                     │                     │                    │                   │
+ 7. │                     │  Create Call record  │                    │                   │
+    │                     │  (outgoing, ringing) │                    │                   │
+    │                     │  Store session_id    │                    │                   │
+    │                     │                     │                    │                   │
+ 8. │◄── {status: calling,│                     │                    │                   │
+    │     call_id, id}    │                     │                    │                   │
+    │                     │                     │                    │                   │
+    │  Widget: "Ringing.."│                     │                    │                   │
+    │                     │                     │                    │                   │
+    │                     │                     │               Contact answers          │
+    │                     │                     │                    │◄─────────────────│
+    │                     │                     │                    │                   │
+ 9. │                     │◄── Webhook ─────────────────────────────│                   │
+    │                     │  event: connect     │                    │                   │
+    │                     │  {call_id,          │                    │                   │
+    │                     │   sdp_answer}       │                    │                   │
+    │                     │                     │                    │                   │
+10. │                     │── POST /sessions/   │                    │                   │
+    │                     │   :id/meta-sdp      │                    │                   │
+    │                     │   {sdp_answer}     ►│                    │                   │
+    │                     │                     │                    │                   │
+11. │                     │              ┌──────┴───────┐            │                   │
+    │                     │              │ Set Meta's   │            │                   │
+    │                     │              │ SDP answer   │            │                   │
+    │                     │              │ on Peer A    │            │                   │
+    │                     │              └──────┬───────┘            │                   │
+    │                     │                     │                    │                   │
+12. │◄══════════ Audio (Meta ↔ Media Server, Peer A) ══════════════►│                   │
+    │                     │                     │                    │                   │
+    │            (Now set up Peer B for agent)  │                    │                   │
+    │                     │                     │                    │                   │
+13-21.  [Same agent-side SDP exchange as inbound steps 14-22]       │                   │
+    │                     │                     │                    │                   │
+22. │◄══ Audio (Media Server ↔ Browser, Peer B) ══►│               │                   │
+    │                     │                     │                    │                   │
+    │  Full duplex audio: Agent <-> Media Server <-> Meta <-> Contact                  │
+```
+
+---
+
+## 6. Recording Pipeline
+
+### Architecture
+
+```
+            chatwoot-media-server
+  ┌──────────────────────────────────────────────────────┐
+  │                                                      │
+  │   Peer A (Meta)                Peer B (Agent)        │
+  │   ┌─────────┐                 ┌─────────┐           │
+  │   │ Remote   │                 │ Remote   │           │
+  │   │ track    │─────┐     ┌────│ track    │           │
+  │   │ (customer│     │     │    │ (agent   │           │
+  │   │  audio)  │     │     │    │  audio)  │           │
+  │   └─────────┘     │     │    └─────────┘           │
+  │                    │     │                           │
+  │              ┌─────▼─────▼──────┐                   │
+  │              │   Recording Mux   │                   │
+  │              │                   │                   │
+  │              │  Option A:        │                   │
+  │              │  Single mixed     │                   │
+  │              │  OGG/Opus file    │                   │
+  │              │                   │                   │
+  │              │  Option B:        │                   │
+  │              │  Two separate     │                   │
+  │              │  tracks (stereo:  │                   │
+  │              │  L=customer,      │                   │
+  │              │  R=agent)         │                   │
+  │              │                   │                   │
+  │              └────────┬─────────┘                   │
+  │                       │                             │
+  │                       ▼                             │
+  │              ┌─────────────────┐                    │
+  │              │ /recordings/    │                    │
+  │              │ {session_id}.ogg│                    │
+  │              │                 │                    │
+  │              │ Written in real │                    │
+  │              │ time as packets │                    │
+  │              │ arrive          │                    │
+  │              └─────────────────┘                    │
+  │                                                      │
+  └──────────────────────────────────────────────────────┘
+                         │
+                   On call end
+                         │
+                         ▼
+                ┌─────────────────┐
+                │ Rails callback   │
+                │                 │
+                │ Media server    │
+                │ POSTs to Rails: │
+                │ /callbacks/     │
+                │ recording_ready │
+                │ {session_id,    │
+                │  file_path}     │
+                └────────┬────────┘
+                         │
+                         ▼
+                ┌─────────────────┐
+                │ Rails downloads  │
+                │ file from media  │
+                │ server via       │
+                │ GET /sessions/   │
+                │ :id/recording    │
+                │                 │
+                │ Attaches to     │
+                │ ActiveStorage   │
+                │                 │
+                │ Enqueues        │
+                │ transcription   │
+                │ job             │
+                └─────────────────┘
+```
+
+### Recording Implementation Details
+
+**Format:** OGG container with Opus codec. This is the native codec for WebRTC audio,
+so no transcoding is needed. The Pion interceptor taps RTP packets before
+encryption/after decryption and writes Opus frames into OGG pages.
+
+**Real-time writing:** Recording starts when both peers are connected and audio is
+bridged. Opus frames are written to disk as they arrive (not buffered in memory). This
+means even if the media server crashes, the recording up to that point is preserved on
+disk.
+
+**Stereo separation (recommended):** Record customer audio on the left channel and
+agent audio on the right channel. This enables:
+- Better transcription accuracy (speaker diarization is trivial)
+- Post-processing flexibility (adjust volumes, filter noise per channel)
+- Compliance with regulations that require separate party recordings
+
+**File lifecycle:**
+1. File created when recording starts: `/recordings/{session_id}.ogg`
+2. Appended in real time as audio packets arrive
+3. Finalized (OGG trailer written) when call ends
+4. Rails fetches via HTTP, attaches to ActiveStorage
+5. Media server deletes local file after Rails confirms receipt
+
+**Failure mode:** If the media server process crashes mid-recording, the OGG file on
+disk is incomplete but still playable (most players handle truncated OGG). A startup
+recovery routine scans for orphaned recording files and reports them to Rails.
+
+---
+
+## 7. Frontend-to-Backend Audio Relay
+
+### Mechanism: Standard WebRTC (Peer B)
+
+The agent's browser establishes a normal WebRTC peer connection -- but to the media
+server instead of Meta. From the browser's perspective, it looks identical to the
+current implementation:
+
+```
+  Current:   Browser <--WebRTC--> Meta Media Servers
+  New:       Browser <--WebRTC--> chatwoot-media-server <--WebRTC--> Meta Media Servers
+```
+
+The browser still uses `getUserMedia`, `RTCPeerConnection`, `ontrack`, etc. The only
+difference is the SDP it receives comes from the media server rather than Meta.
+
+### SDP Exchange for Agent-Side Peer (Peer B)
+
+```
+  Rails                            Media Server                    Browser
+    │                                  │                              │
+    │── POST /sessions/:id/            │                              │
+    │   agent-offer ──────────────────►│                              │
+    │                                  │── Create Peer B              │
+    │                                  │── Generate SDP offer         │
+    │                                  │── Gather ICE candidates      │
+    │◄── {sdp_offer, ice_servers} ─────│                              │
+    │                                  │                              │
+    │── ActionCable: agent_offer ──────────────────────────────────►│
+    │   {sdp_offer, ice_servers}       │                              │
+    │                                  │                     ┌────────┴──────┐
+    │                                  │                     │getUserMedia   │
+    │                                  │                     │setRemoteDesc  │
+    │                                  │                     │createAnswer   │
+    │                                  │                     │ICE gather     │
+    │                                  │                     └────────┬──────┘
+    │                                  │                              │
+    │◄── POST /whatsapp_calls/:id/agent-answer ──────────────────────│
+    │   {sdp_answer}                   │                              │
+    │                                  │                              │
+    │── POST /sessions/:id/            │                              │
+    │   agent-answer ─────────────────►│                              │
+    │                                  │── Set remote desc on Peer B  │
+    │                                  │── Bridge audio A <-> B       │
+    │                                  │── Start recording            │
+    │                                  │                              │
+    │                                  │◄═══════ SRTP audio ════════►│
+```
+
+### Why WebRTC (not WebSocket audio streaming)
+
+Alternatives considered:
+
+| Approach              | Latency    | Complexity | Browser support | Quality        |
+|-----------------------|------------|------------|-----------------|----------------|
+| **WebRTC (Peer B)**   | ~20-50ms   | Low        | Native          | Opus, adaptive |
+| WebSocket + PCM       | ~100-200ms | High       | Manual codec    | Fixed bitrate  |
+| WebSocket + Opus      | ~80-150ms  | Medium     | Manual decode   | Good           |
+| HTTP chunked          | ~200-500ms | Medium     | Standard        | Variable       |
+
+WebRTC is the clear winner:
+- **Latency**: Sub-50ms, critical for real-time voice conversation
+- **Codec negotiation**: Opus bitrate adaptation is automatic
+- **Echo cancellation**: Built into browser WebRTC stack
+- **NAT traversal**: ICE/STUN/TURN handled automatically
+- **No custom audio code**: Browser handles decode/playback natively
+
+WebSocket audio would require building a custom audio pipeline in the browser:
+decoding Opus, managing jitter buffers, handling echo cancellation, and scheduling
+audio playback -- all of which WebRTC already handles.
+
+---
+
+## 8. Call Lifecycle and Reconnection
+
+### Call State Machine (Server-Side)
+
+```
+                              ┌─────────────┐
+                              │   created    │  Media server session allocated
+                              └──────┬──────┘
+                                     │
+                              Meta SDP exchanged (Peer A ready)
+                                     │
+                              ┌──────▼──────┐
+                              │   ringing    │  Waiting for agent to accept
+                              └──┬───┬───┬──┘
+                                 │   │   │
+                        accepted │   │   │ timeout / reject
+                                 │   │   │
+                          ┌──────▼┐  │  ┌▼──────────┐
+                          │ meta_ │  │  │ no_answer  │
+                          │ conn  │  │  │ / failed   │
+                          └──┬────┘  │  └────────────┘
+                             │       │
+                   agent SDP │       │ agent never connected
+                   exchanged │       │
+                             │       │
+                      ┌──────▼──────┐│
+                      │ in_progress ││  Both peers connected, audio bridged
+                      └──────┬──────┘│
+                             │       │
+                      ┌──────▼──────┐│
+                      │agent_disconn││  Agent page reload / network issue
+                      │(Peer B down)││  Peer A still holds Meta audio
+                      └──┬───┬──────┘│
+                         │   │       │
+                reconnect│   │timeout│
+                         │   │(30s)  │
+                  ┌──────▼┐  │       │
+                  │in_prog│  │       │
+                  │(reconn│  │       │
+                  │ected) │  │       │
+                  └──┬────┘  │       │
+                     │       │       │
+                     ├───────┤       │
+                     │       │       │
+              ┌──────▼───────▼───────▼──┐
+              │      completed          │  Call ended (any reason)
+              └─────────────────────────┘
+```
+
+### Reconnection After Page Reload
+
+This is the primary motivation for the architecture change. Here is the reconnection
+flow:
+
+```
+  Agent Browser                  Rails                      Media Server
+      │                           │                             │
+      │ ═══ Active call ══════════╪═════════════════════════════╡
+      │ (Peer B established)      │                             │ Peer A: active
+      │                           │                             │ Peer B: active
+      │                           │                             │ Audio: bridged
+      │                           │                             │ Recording: active
+      │                           │                             │
+      │── Page refresh ──►        │                             │
+      │  (Peer B connection dies) │                             │
+      │                           │                             │
+      │                           │◄── Callback: agent_disconn ─│ (Peer B ICE fails)
+      │                           │                             │
+      │                           │  Call status stays          │ Peer A: STILL ACTIVE
+      │                           │  "in_progress"              │ Audio from Meta: still
+      │                           │  Start 30s reconnect timer  │  flowing (into void)
+      │                           │                             │ Recording: paused
+      │                           │                             │  (agent track silent)
+      │                           │                             │
+      │── Page loads              │                             │
+      │   Vue mounts              │                             │
+      │                           │                             │
+      │── GET /whatsapp_calls/    │                             │
+      │   active ─────────────────►│                             │
+      │                           │                             │
+      │◄── {call in progress,     │                             │
+      │     call_id, id}          │                             │
+      │                           │                             │
+      │  Widget auto-shows:       │                             │
+      │  "Call in progress -      │                             │
+      │   Reconnecting..."        │                             │
+      │                           │                             │
+      │── POST /whatsapp_calls/   │                             │
+      │   :id/reconnect ──────────►│                             │
+      │                           │                             │
+      │                           │── POST /sessions/:id/       │
+      │                           │   agent-reconnect ──────────►│
+      │                           │                             │
+      │                           │                      ┌──────┴──────┐
+      │                           │                      │ Tear down   │
+      │                           │                      │ old Peer B  │
+      │                           │                      │             │
+      │                           │                      │ Create new  │
+      │                           │                      │ Peer B      │
+      │                           │                      │             │
+      │                           │                      │ Generate    │
+      │                           │                      │ new SDP     │
+      │                           │                      │ offer       │
+      │                           │                      └──────┬──────┘
+      │                           │                             │
+      │                           │◄── {sdp_offer} ────────────│
+      │                           │                             │
+      │◄── ActionCable: agent_offer│                             │
+      │   {sdp_offer, ice_servers}│                             │
+      │                           │                             │
+      │  getUserMedia (mic)       │                             │
+      │  setRemoteDescription     │                             │
+      │  createAnswer + ICE       │                             │
+      │                           │                             │
+      │── POST /agent-answer ─────►│                             │
+      │  {sdp_answer}             │                             │
+      │                           │── POST /sessions/:id/       │
+      │                           │   agent-answer ─────────────►│
+      │                           │                             │
+      │                           │                      ┌──────┴──────┐
+      │                           │                      │ Set answer  │
+      │                           │                      │ on new      │
+      │                           │                      │ Peer B      │
+      │                           │                      │             │
+      │                           │                      │ Re-bridge   │
+      │                           │                      │ audio       │
+      │                           │                      │             │
+      │                           │                      │ Resume      │
+      │                           │                      │ recording   │
+      │                           │                      └──────┴──────┘
+      │                           │                             │
+      │◄══════════ Audio restored (< 2 seconds gap) ════════════╡
+      │                           │                             │
+      │  Widget: call timer       │                             │
+      │  resumes from server-     │                             │
+      │  tracked duration         │                             │
+```
+
+### Key Reconnection Details
+
+1. **Reconnect window:** The media server holds Peer A (Meta-side) for 30 seconds
+   after Peer B (agent-side) disconnects. If the agent reconnects within that window,
+   the call continues seamlessly. If the timeout expires, the media server tells Rails
+   to terminate the call with Meta.
+
+2. **Audio gap:** The customer hears silence during the reconnection (typically 1-3
+   seconds for a page reload). This is acceptable for a page reload scenario. The
+   media server could optionally play a hold tone to the Meta side during disconnection.
+
+3. **Timer continuity:** The call duration timer is tracked server-side
+   (`Call.started_at`). The frontend calculates elapsed time from `started_at` rather
+   than running a local timer. On reconnection, the widget immediately shows the correct
+   elapsed time.
+
+4. **Recording continuity:** The recording file on disk continues to receive the
+   customer's audio during the agent disconnect period. The agent's channel is silent
+   during the gap. When the agent reconnects, their audio resumes in the recording.
+
+5. **Multiple reconnections:** Each reconnection creates a new Peer B. There is no
+   limit on the number of reconnections during a single call.
+
+### Multi-Agent Visibility
+
+The existing pattern is preserved:
+
+- When a call is ringing, all agents in the account see the incoming call widget
+- When one agent accepts, ActionCable `whatsapp_call.accepted` dismisses the call from
+  all other agents' widgets
+- The accepting agent's browser is the only one that establishes Peer B
+- If the accepting agent's Peer B disconnects and they do not reconnect within 30s,
+  the call could optionally be re-offered to other agents (future enhancement)
+
+### Media Server Restart
+
+If the Go media server process crashes or restarts:
+
+1. All active Peer A and Peer B connections are lost
+2. The media server has no persistent state -- all sessions are in-memory
+3. On startup, it scans `/recordings/` for orphaned files and reports them to Rails
+4. Rails detects the loss via HTTP health check failure or callback timeout
+5. Rails terminates all `in_progress` calls associated with the failed media server
+6. Recordings up to the crash point are preserved on disk
+
+For high availability, multiple media server instances can run behind a load balancer
+with session affinity (sticky sessions by `session_id`). Redis can optionally store
+session metadata for cross-instance recovery, but this adds complexity and is not
+recommended for the initial implementation.
+
+---
+
+## 9. Database Schema Changes
+
+### Migration: Add media_session_id to calls
+
+```
+add_column :calls, :media_session_id, :string
+add_index  :calls, :media_session_id
+```
+
+The `media_session_id` is the unique identifier for the session on the Go media server.
+Rails uses it to make API calls to the media server for a given call.
+
+### Updated Call.meta structure
+
+```json
+{
+  "media_session_id": "sess_abc123",
+  "meta_sdp_offer": "v=0\r\n...",
+  "meta_sdp_answer": "v=0\r\n...",
+  "agent_sdp_offer": "v=0\r\n...",
+  "agent_sdp_answer": "v=0\r\n...",
+  "ice_servers": [{"urls": "stun:stun.l.google.com:19302"}],
+  "agent_reconnect_count": 0,
+  "recording_file": "sess_abc123.ogg"
+}
+```
+
+### New InstallationConfig keys
+
+| Key                          | Type    | Description                                    |
+|------------------------------|---------|------------------------------------------------|
+| `MEDIA_SERVER_URL`           | string  | Internal URL of the media server (e.g., `http://media:4000`) |
+| `MEDIA_SERVER_AUTH_TOKEN`    | string  | Shared secret for Rails <-> media server auth  |
+| `MEDIA_SERVER_STUN_SERVERS`  | string  | Comma-separated STUN server URLs               |
+| `MEDIA_SERVER_TURN_SERVERS`  | string  | Comma-separated TURN server URLs               |
+| `MEDIA_SERVER_TURN_USERNAME` | string  | TURN server username                           |
+| `MEDIA_SERVER_TURN_PASSWORD` | string  | TURN server password                           |
+
+---
+
+## 10. File Structure
+
+### New Go sidecar (separate repository or monorepo subdirectory)
+
+```
+enterprise/media-server/
+├── Dockerfile
+├── go.mod
+├── go.sum
+├── main.go                          # Entry point, HTTP server setup
+├── config/
+│   └── config.go                    # Environment variable parsing
+├── api/
+│   ├── handler.go                   # HTTP route definitions
+│   ├── middleware.go                 # Auth token validation
+│   ├── session_handler.go           # POST /sessions, GET /sessions/:id
+│   ├── meta_sdp_handler.go          # POST /sessions/:id/meta-sdp
+│   ├── agent_handler.go             # agent-offer, agent-answer, agent-reconnect
+│   └── recording_handler.go         # GET /sessions/:id/recording
+├── session/
+│   ├── manager.go                   # Session lifecycle (create, find, cleanup)
+│   ├── session.go                   # Single call session (two peers + bridge)
+│   ├── peer.go                      # WebRTC peer connection wrapper
+│   └── bridge.go                    # RTP packet forwarding between peers
+├── recording/
+│   ├── recorder.go                  # OGG/Opus file writer
+│   ├── ogg_writer.go                # Low-level OGG container writing
+│   └── cleanup.go                   # Orphaned file detection on startup
+├── callback/
+│   └── rails_client.go              # HTTP client for callbacks to Rails
+└── recordings/                      # Runtime directory for recording files
+    └── .gitkeep
+```
+
+### Modified Rails files (enterprise)
+
+```
+enterprise/
+├── app/
+│   ├── controllers/api/v1/accounts/
+│   │   └── whatsapp_calls_controller.rb     # MODIFIED: new endpoints
+│   │       # - accept: no longer receives sdp_answer from browser
+│   │       # - new: reconnect action
+│   │       # - new: agent_answer action
+│   │       # - remove: upload_recording (server handles it)
+│   │
+│   ├── services/whatsapp/
+│   │   ├── call_service.rb                  # MODIFIED: delegates SDP to media server
+│   │   ├── incoming_call_service.rb         # MODIFIED: creates media session
+│   │   ├── media_server_client.rb           # NEW: HTTP client for media server API
+│   │   ├── call_recording_service.rb        # NEW: fetches recording from media server
+│   │   └── call_reconnect_service.rb        # NEW: handles agent reconnection
+│   │
+│   ├── jobs/whatsapp/
+│   │   ├── call_recording_fetch_job.rb      # NEW: async fetch recording on call end
+│   │   └── call_transcription_job.rb        # UNCHANGED
+│   │
+│   └── models/
+│       └── call.rb                          # MODIFIED: add media_session_id accessor
+│
+├── config/
+│   └── media_server.yml                     # Media server connection config
+```
+
+### Modified frontend files
+
+```
+app/javascript/dashboard/
+├── composables/
+│   └── useWhatsappCallSession.js            # HEAVILY MODIFIED
+│       # - No longer sends SDP to Meta
+│       # - Receives SDP offer from media server via ActionCable
+│       # - Sends SDP answer to Rails (which forwards to media server)
+│       # - No longer handles recording
+│       # - Adds reconnection logic
+│       # - beforeunload no longer terminates call (just disconnects Peer B)
+│
+├── stores/
+│   └── whatsappCalls.js                     # MODIFIED
+│       # - New state: isReconnecting, reconnectAttempts
+│       # - New action: handleAgentOffer (for reconnection)
+│       # - Remove: outbound WebRTC state (moved to server)
+│
+├── api/
+│   └── whatsappCalls.js                     # MODIFIED
+│       # - accept: no sdp_answer parameter
+│       # - new: agentAnswer(callId, sdpAnswer)
+│       # - new: reconnect(callId)
+│       # - remove: uploadRecording
+│       # - new: getActiveCall()
+│
+├── components/widgets/
+│   └── WhatsappCallWidget.vue               # MODIFIED
+│       # - Reconnection UI state
+│       # - Timer from server-tracked started_at
+│
+├── helper/
+│   └── actionCable.js                       # MODIFIED
+│       # - Handle new event: whatsapp_call.agent_offer
+│       # - Handle new event: whatsapp_call.agent_disconnected
+```
+
+---
+
+## 11. Deployment Architecture
+
+### Docker Compose Addition
+
+```yaml
+# Added to docker-compose.yml
+services:
+  media-server:
+    build:
+      context: ./enterprise/media-server
+      dockerfile: Dockerfile
+    ports:
+      - "4000:4000"      # Internal HTTP API (Rails communication)
+      - "10000-10100:10000-10100/udp"  # RTP/SRTP media ports
+    environment:
+      - AUTH_TOKEN=${MEDIA_SERVER_AUTH_TOKEN}
+      - STUN_SERVERS=stun:stun.l.google.com:19302
+      - TURN_SERVERS=${TURN_SERVERS:-}
+      - TURN_USERNAME=${TURN_USERNAME:-}
+      - TURN_PASSWORD=${TURN_PASSWORD:-}
+      - RAILS_CALLBACK_URL=http://web:3000
+      - RECORDINGS_DIR=/recordings
+      - LOG_LEVEL=info
+      - UDP_PORT_MIN=10000
+      - UDP_PORT_MAX=10100
+    volumes:
+      - media-recordings:/recordings
+    networks:
+      - chatwoot
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "wget", "--spider", "-q", "http://localhost:4000/health"]
+      interval: 10s
+      timeout: 5s
+      retries: 3
+
+volumes:
+  media-recordings:
+```
+
+### Procfile Addition
+
+```
+media: ./enterprise/media-server/chatwoot-media-server
+```
+
+### Network Architecture
+
+```
+  ┌─────────────────────────────────────────────────────────────────────┐
+  │                        Docker Network                               │
+  │                                                                     │
+  │  ┌──────────┐   ┌──────────┐   ┌──────────────┐   ┌────────────┐  │
+  │  │  web      │   │  worker  │   │ media-server │   │  redis     │  │
+  │  │  (Rails)  │   │ (Sidekiq)│   │   (Pion Go)  │   │            │  │
+  │  │  :3000    │   │          │   │   :4000 HTTP  │   │  :6379     │  │
+  │  │          ◄────────────────────►              │   │            │  │
+  │  │          │   │          │   │   :10000-10100│   │            │  │
+  │  └────┬─────┘   └──────────┘   │   UDP (media) │   └────────────┘  │
+  │       │                        └───────┬──────┘                    │
+  │       │                                │                           │
+  └───────┼────────────────────────────────┼───────────────────────────┘
+          │                                │
+          │ :3000 (HTTPS via LB)           │ :10000-10100/UDP
+          │                                │ (must be exposed to internet
+          │                                │  for WebRTC ICE connectivity)
+          ▼                                ▼
+   ┌─────────────┐                ┌──────────────────┐
+   │   Internet   │                │    Internet       │
+   │  (browsers,  │                │  (Meta servers,   │
+   │   webhooks)  │                │   agent browsers)  │
+   └─────────────┘                └──────────────────┘
+```
+
+### Critical: UDP Port Exposure
+
+The media server MUST have UDP ports exposed to the internet for WebRTC ICE to work.
+This is because:
+
+1. **Meta-side (Peer A):** Meta's media servers send SRTP packets to the media server's
+   public IP/port. The media server must be reachable from Meta's infrastructure.
+
+2. **Agent-side (Peer B):** The agent's browser sends SRTP packets to the media server.
+   If the agent is behind a NAT, STUN handles discovery, but the media server must still
+   have publicly-accessible UDP ports.
+
+If UDP ports cannot be directly exposed (e.g., behind a restrictive firewall or
+cloud load balancer that does not support UDP), a **TURN server** is required as a
+relay. The media server's ICE configuration should include TURN credentials for both
+Peer A and Peer B.
+
+### STUN/TURN Configuration
+
+| Component      | STUN needed?                     | TURN needed?                         |
+|----------------|----------------------------------|--------------------------------------|
+| Peer A (Meta)  | Yes (discover server's public IP)| Only if Meta can't reach server UDP  |
+| Peer B (Agent) | Yes (standard)                   | If agent is behind restrictive NAT   |
+
+Recommended setup:
+- Deploy a TURN server (coturn) alongside the media server
+- Or use a managed TURN service (Twilio Network Traversal, Cloudflare TURN)
+- Configure TURN credentials in environment variables
+
+---
+
+## 12. Scalability Analysis
+
+### Per-Call Resource Consumption (Media Server)
+
+| Resource       | Per call     | Notes                                           |
+|----------------|--------------|--------------------------------------------------|
+| Memory         | ~2-3 MB      | Two peer connections, RTP buffers, SRTP contexts |
+| CPU            | ~0.5-1%      | Packet forwarding + Opus frame copying (no transcoding) |
+| Bandwidth      | ~100 kbps    | Opus audio, both directions (~50kbps each way)   |
+| Disk I/O       | ~12 KB/s     | Recording write (Opus @ 48kbps / 8 = 6KB/s * 2 streams) |
+| UDP ports      | 4 per call   | 2 for Peer A (RTP + RTCP), 2 for Peer B          |
+| File handles   | 3 per call   | 2 sockets + 1 recording file                     |
+
+### Capacity Estimates (Single Media Server Instance)
+
+| Server Size     | RAM    | CPU   | Concurrent Calls | Notes                        |
+|-----------------|--------|-------|-------------------|------------------------------|
+| Small (2 CPU)   | 2 GB   | 2 core| ~50               | Suitable for most deployments|
+| Medium (4 CPU)  | 4 GB   | 4 core| ~200              | Mid-size contact centers     |
+| Large (8 CPU)   | 8 GB   | 8 core| ~500              | Large deployments            |
+
+The bottleneck is typically network bandwidth, not CPU or memory. At 100 kbps per
+call, 500 concurrent calls require ~50 Mbps of sustained bandwidth.
+
+### Horizontal Scaling
+
+For deployments exceeding 500 concurrent calls:
+
+```
+                    ┌─────────────────┐
+                    │   Rails App     │
+                    │                 │
+                    │ Routes calls to │
+                    │ media servers   │
+                    │ via consistent  │
+                    │ hashing on      │
+                    │ call_id         │
+                    └────────┬────────┘
+                             │
+              ┌──────────────┼──────────────┐
+              │              │              │
+       ┌──────▼──────┐ ┌────▼────────┐ ┌──▼──────────┐
+       │ media-srv-1 │ │ media-srv-2 │ │ media-srv-3 │
+       │ :4000       │ │ :4001       │ │ :4002       │
+       │ UDP 10000-  │ │ UDP 10100-  │ │ UDP 10200-  │
+       │     10099   │ │     10199   │ │     10299   │
+       └─────────────┘ └─────────────┘ └─────────────┘
+```
+
+Each media server instance gets a unique range of UDP ports. Rails assigns calls to
+instances using consistent hashing on `call_id`. The media server URL is stored in
+`Call.meta['media_server_url']` so Rails always routes to the correct instance.
+
+---
+
+## 13. Security Considerations
+
+### Internal API Authentication
+
+```
+Rails ──── Bearer {MEDIA_SERVER_AUTH_TOKEN} ────► Media Server
+```
+
+The shared secret is configured via environment variable. The media server validates
+the token on every request. This is sufficient for co-located services on the same
+Docker network.
+
+### SRTP Encryption
+
+All audio is encrypted via SRTP (Secure Real-time Transport Protocol). Pion handles
+DTLS key exchange automatically as part of the WebRTC handshake. The media server
+decrypts incoming SRTP from one peer and re-encrypts it for the other peer. Audio
+is briefly in plaintext within the media server's memory during forwarding.
+
+### Recording Security
+
+- Recording files are stored on a Docker volume, not in a web-accessible directory
+- Files are transferred to Rails via internal HTTP and stored in ActiveStorage
+- ActiveStorage enforces authentication for blob downloads
+- Recording files are deleted from the media server after successful transfer
+
+### ICE Candidate Filtering
+
+The media server should filter ICE candidates to avoid exposing internal network
+topology. Only `srflx` (server-reflexive) and `relay` (TURN) candidates should be
+included in SDP offers to agent browsers. `host` candidates revealing internal IPs
+should be stripped.
+
+### Rate Limiting
+
+The media server should enforce:
+- Maximum concurrent sessions per account (configurable, default: 10)
+- Maximum session duration (configurable, default: 2 hours)
+- Session creation rate limit (configurable, default: 5 per minute per account)
+
+---
+
+## 14. Pros, Cons, and Trade-offs
+
+### Pros
+
+1. **Call persistence across page reloads.** The primary goal. The Meta-side WebRTC
+   connection is held by the server; the agent can reconnect within 30 seconds.
+
+2. **Reliable server-side recording.** No dependency on browser memory. Recording is
+   written to disk in real time. Even if the browser crashes, the recording up to that
+   point is saved.
+
+3. **Centralized call lifecycle.** Rails and the media server fully control the call.
+   The browser is a "dumb terminal" for audio I/O. This simplifies state management
+   and reduces frontend complexity.
+
+4. **No SDP fix needed in Rails.** The media server generates its own SDP answers using
+   Pion, which produces correct `a=setup:active` natively. The `actpass` -> `active`
+   string replacement hack is eliminated.
+
+5. **Foundation for advanced features.** Server-side audio access enables:
+   - Real-time transcription (stream audio to STT service)
+   - Call transfer (redirect Peer B to a different agent)
+   - Conference calls (mix multiple Peer B connections)
+   - Hold music (play audio file into Peer A while agent is disconnected)
+   - Supervisory monitoring (add a listen-only Peer C)
+
+6. **Recording format upgrade.** OGG/Opus with stereo channel separation (customer L,
+   agent R) improves transcription accuracy and post-processing flexibility vs the
+   current single-channel WebM blob.
+
+### Cons
+
+1. **Increased latency.** Audio passes through an additional hop (media server). Expected
+   additional latency: 1-5ms within the same datacenter. Unlikely to be perceptible
+   for voice calls (human perception threshold ~40ms).
+
+2. **New infrastructure component.** The Go sidecar is a new process to deploy, monitor,
+   and maintain. It adds operational complexity. Teams unfamiliar with Go need to learn
+   the codebase for troubleshooting.
+
+3. **UDP port management.** WebRTC requires UDP ports exposed to the internet. This is
+   non-trivial in cloud environments with TCP-only load balancers. May require
+   additional infrastructure (dedicated UDP-capable load balancer, or direct IP exposure).
+
+4. **Double encryption overhead.** Audio is SRTP-encrypted on both Peer A and Peer B.
+   The media server decrypts and re-encrypts every packet. This adds minimal CPU
+   overhead (~0.5% per call) but is architecturally unavoidable for a B2BUA.
+
+5. **Single point of failure.** If the media server crashes, all active calls drop. The
+   recovery is recordings on disk and Rail terminating lingering calls, but the calls
+   themselves cannot be recovered. Mitigated by health checks and automatic restart.
+
+6. **Increased bandwidth.** The media server doubles bandwidth consumption because it
+   receives audio from Meta AND sends it to the agent (and vice versa). In the browser-
+   direct model, Chatwoot's server uses zero media bandwidth.
+
+### Trade-offs Accepted
+
+| Trade-off                           | Justification                                  |
+|-------------------------------------|------------------------------------------------|
+| +1 network hop latency              | <5ms, imperceptible for voice                  |
+| New Go service to maintain          | Pion is stable; service is small (~2000 LoC)   |
+| UDP ports exposed                   | Standard WebRTC requirement; TURN as fallback  |
+| Double bandwidth                    | ~100kbps/call is trivial for modern infra       |
+| Recordings briefly on local disk    | Cleaned up after ActiveStorage transfer         |
+
+---
+
+## 15. Migration Path
+
+### Phase 1: Build Media Server (2-3 weeks)
+
+**Goal:** Standalone Go binary that can hold a WebRTC peer and record audio.
+
+- Implement session management (create, find, destroy)
+- Implement Peer A: accept SDP offer, generate SDP answer, hold SRTP connection
+- Implement Peer B: generate SDP offer, accept SDP answer
+- Implement audio bridge (forward RTP packets A <-> B)
+- Implement OGG/Opus recording
+- Implement HTTP API with auth token
+- Implement health check endpoint
+- Write integration tests with Pion's built-in test utilities
+- Dockerize
+
+### Phase 2: Rails Integration (1-2 weeks)
+
+**Goal:** Rails delegates SDP handling to media server; recording fetched server-side.
+
+- Add `Whatsapp::MediaServerClient` service
+- Modify `IncomingCallService` to create media session on webhook
+- Modify `CallService#pre_accept_and_accept` to use server-generated SDP
+- Add `CallReconnectService`
+- Add `CallRecordingFetchJob`
+- Add new controller actions: `reconnect`, `agent_answer`
+- Remove `upload_recording` action
+- Add ActionCable event: `whatsapp_call.agent_offer`
+- Add media server health check to deployment monitoring
+- Feature flag: `whatsapp_call_server_media` (separate from `whatsapp_call`)
+
+### Phase 3: Frontend Migration (1-2 weeks)
+
+**Goal:** Browser connects to media server (Peer B) instead of Meta directly.
+
+- Modify `useWhatsappCallSession.js`:
+  - Accept flow: wait for `agent_offer` ActionCable event instead of using Meta's SDP
+  - Send `agent_answer` to Rails instead of Meta's SDP answer
+  - Remove `MediaRecorder` logic entirely
+  - Add reconnection on page load: detect active call, trigger reconnect
+  - `beforeunload`: do NOT terminate call, just clean up Peer B locally
+- Modify `whatsappCalls.js` store:
+  - Add reconnection state
+  - Handle `agent_offer` event
+  - Timer from `started_at` instead of local counter
+- Modify `ConversationHeader.vue` (outbound):
+  - No longer generate SDP offer in browser
+  - Just POST to `/initiate` without `sdp_offer`
+  - Wait for `agent_offer` event after contact answers
+- Remove recording-related code from frontend
+
+### Phase 4: Cutover Strategy
+
+**Approach:** Feature flag per account.
+
+```ruby
+# In IncomingCallService and CallService:
+if account.feature_enabled?('whatsapp_call_server_media')
+  # New path: delegate to media server
+else
+  # Legacy path: browser-direct WebRTC
+end
+```
+
+```javascript
+// In useWhatsappCallSession.js:
+const useServerMedia = computed(() =>
+  currentAccount.value?.features?.includes('whatsapp_call_server_media')
+);
+```
+
+This allows:
+1. Gradual rollout to test accounts first
+2. Instant rollback by disabling the feature flag
+3. Both paths coexist during the migration period
+4. Legacy path removed once all accounts are migrated
+
+### Phase 5: Cleanup (1 week)
+
+After all accounts are migrated:
+- Remove browser-direct WebRTC code path
+- Remove `upload_recording` endpoint
+- Remove `MediaRecorder` and `startCallRecording` from frontend
+- Remove feature flag check (`whatsapp_call_server_media` becomes default)
+- Update documentation
+
+### Timeline Summary
+
+| Phase | Duration | Deliverable                                         |
+|-------|----------|-----------------------------------------------------|
+| 1     | 2-3 wks  | Standalone media server binary, tested              |
+| 2     | 1-2 wks  | Rails integration, new endpoints                    |
+| 3     | 1-2 wks  | Frontend migration, reconnection                    |
+| 4     | 1 wk     | Feature-flagged rollout, validation                 |
+| 5     | 1 wk     | Cleanup legacy code                                 |
+| **Total** | **6-9 wks** | **Full migration complete**                    |
+
+---
+
+## Appendix A: Alternative Approaches Considered and Rejected
+
+### A1. WebSocket Audio Streaming (No Peer B WebRTC)
+
+Instead of a second WebRTC peer connection to the browser, stream raw audio over
+WebSocket.
+
+**Rejected because:**
+- 3-5x higher latency (WebSocket has no jitter buffer, no adaptive bitrate)
+- Must build custom audio decode/playback pipeline in browser
+- No browser echo cancellation (WebRTC AEC is tied to RTCPeerConnection)
+- No NAT traversal (WebSocket is TCP, goes through proxies)
+- Significantly more frontend code complexity
+
+### A2. SIP Trunking (No WebRTC to Meta)
+
+Meta supports SIP as an alternative to WebRTC for the business endpoint. Use a SIP
+server (Asterisk/FreeSWITCH) instead of WebRTC.
+
+**Rejected for initial implementation because:**
+- Adds another large infrastructure component (Asterisk/FreeSWITCH)
+- SIP requires dedicated infrastructure for NAT traversal (SIP ALG, RTP proxy)
+- More complex debugging (SIP signaling + RTP + codec negotiation)
+- May be a good Phase 2 option for enterprises already running PBX infrastructure
+
+### A3. Browser Service Worker for Call Persistence
+
+Use a Service Worker to hold the WebRTC peer connection, surviving page reloads.
+
+**Rejected because:**
+- Service Workers cannot access `RTCPeerConnection` (not available in SW context)
+- `SharedWorker` can hold JS objects across tabs but not across page reloads
+- No browser API supports WebRTC connections that survive navigation
+- This is a fundamental browser architecture limitation, not a coding problem
+
+### A4. Iframe-Based WebRTC Isolation
+
+Put WebRTC code in a hidden iframe that persists across SPA navigation.
+
+**Rejected because:**
+- Only works for SPA navigation (Vue Router), not actual page reloads
+- Fragile: iframe can be garbage-collected by browser memory pressure
+- Does not solve recording reliability (still browser-dependent)
+- Adds significant complexity for marginal benefit
+
+---
+
+## Appendix B: Media Server API Specification (Draft)
+
+### POST /sessions
+
+Create a new call session.
+
+**Request:**
+```json
+{
+  "call_id": "chatwoot_call_42",
+  "account_id": 1,
+  "direction": "incoming",
+  "meta_sdp_offer": "v=0\r\no=- ...",
+  "ice_servers": [
+    {"urls": "stun:stun.l.google.com:19302"},
+    {"urls": "turn:turn.example.com:3478", "username": "user", "credential": "pass"}
+  ]
+}
+```
+
+**Response (201):**
+```json
+{
+  "session_id": "sess_abc123",
+  "meta_sdp_answer": "v=0\r\no=- ...",
+  "status": "meta_peer_ready"
+}
+```
+
+For incoming calls, the response includes the SDP answer to send to Meta. For
+outgoing calls, `meta_sdp_offer` is null initially; the server generates an offer
+that Rails sends to Meta via `initiate_call`.
+
+### POST /sessions/:id/agent-offer
+
+Generate an SDP offer for the agent-side peer connection.
+
+**Response (200):**
+```json
+{
+  "sdp_offer": "v=0\r\no=- ...",
+  "ice_servers": [...]
+}
+```
+
+### POST /sessions/:id/agent-answer
+
+Set the agent's SDP answer and begin audio bridging.
+
+**Request:**
+```json
+{
+  "sdp_answer": "v=0\r\no=- ..."
+}
+```
+
+**Response (200):**
+```json
+{
+  "status": "bridged",
+  "recording": true
+}
+```
+
+### POST /sessions/:id/agent-reconnect
+
+Tear down old agent peer and create a new one.
+
+**Response (200):**
+```json
+{
+  "sdp_offer": "v=0\r\no=- ...",
+  "ice_servers": [...]
+}
+```
+
+### POST /sessions/:id/terminate
+
+End the session, finalize recording.
+
+**Response (200):**
+```json
+{
+  "status": "terminated",
+  "recording_file": "sess_abc123.ogg",
+  "recording_size_bytes": 245760,
+  "duration_seconds": 135
+}
+```
+
+### GET /sessions/:id/recording
+
+Download the finalized recording file.
+
+**Response:** Binary OGG/Opus file with `Content-Type: audio/ogg`.
+
+### GET /health
+
+**Response (200):**
+```json
+{
+  "status": "ok",
+  "active_sessions": 12,
+  "uptime_seconds": 86400
+}
+```
diff --git a/docs/SERVER_SIDE_WEBRTC_IMPLEMENTATION_PLAN.md b/docs/SERVER_SIDE_WEBRTC_IMPLEMENTATION_PLAN.md
new file mode 100644
index 000000000..8b665098c
--- /dev/null
+++ b/docs/SERVER_SIDE_WEBRTC_IMPLEMENTATION_PLAN.md
@@ -0,0 +1,1314 @@
+# Server-Side WebRTC Migration -- Implementation Plan & Tracking
+
+> **Feature branch:** `feat/whatsapp-call` | **Base branch:** `develop`
+> **Feature flag (existing):** `whatsapp_call` | **Feature flag (new):** `whatsapp_call_server_media`
+> **Created:** 2026-04-21 | **Status:** Planning
+
+---
+
+## Table of Contents
+
+1. [Feature Requirements](#1-feature-requirements)
+2. [Architecture Decision: WebRTC Peer B](#2-architecture-decision-webrtc-peer-b-not-websocket-audio)
+3. [Current State Assessment](#3-current-state-assessment)
+4. [Implementation Phases](#4-implementation-phases)
+   - [Phase 1: Foundation](#phase-1-foundation--database--configuration--go-scaffold)
+   - [Phase 2: Core Call Flow](#phase-2-core-call-flow)
+   - [Phase 3: Recording](#phase-3-server-side-recording)
+   - [Phase 4: Call Persistence & Reconnection](#phase-4-call-persistence--reconnection)
+   - [Phase 5: Multi-Participant](#phase-5-multi-participant)
+   - [Phase 6: Audio Injection](#phase-6-audio-injection--hold-music)
+   - [Phase 7: AI Foundation](#phase-7-ai-captain-foundation)
+5. [API Surface Changes](#5-api-surface-changes)
+6. [Database Changes](#6-database-changes)
+7. [Configuration & Environment Variables](#7-configuration--environment-variables)
+8. [Risk Register](#8-risk-register)
+9. [Testing Strategy](#9-testing-strategy)
+10. [Rollout Plan](#10-rollout-plan)
+
+---
+
+## 1. Feature Requirements
+
+Six core requirements drive this migration. Each is a hard prerequisite for considering the project complete.
+
+### R1: End-to-End Calling Works Correctly
+
+Inbound and outbound calls must complete the full lifecycle: ring, accept, two-way audio, hang up. The audio path changes from `Browser <-> Meta` to `Browser <-> Media Server <-> Meta`, but from the user's perspective behavior is identical. Latency increase must stay below 10ms (datacenter hop).
+
+**Acceptance criteria:**
+- Agent hears customer and customer hears agent with no perceptible quality loss.
+- Outbound call flow (initiate, ring, connect, terminate) works end to end.
+- Inbound call flow (webhook, ring, accept, audio, terminate) works end to end.
+- SDP negotiation no longer requires the `actpass -> active` string replacement hack.
+
+### R2: Call Persists When Browser Closes or Refreshes
+
+The Meta-side WebRTC connection (Peer A) is held by the Go media server. When the agent's browser closes or refreshes, only the agent-side connection (Peer B) drops. The call stays alive for a configurable window (default 30 seconds), and the agent can reconnect automatically on page reload.
+
+**Acceptance criteria:**
+- Agent refreshes the page during an active call. The call does not terminate.
+- On reload, the dashboard detects the active call and reconnects within 3 seconds.
+- Customer hears silence (or hold tone) during the reconnection gap, not a disconnect.
+- If the agent does not reconnect within 30s, the call terminates gracefully.
+- The `beforeunload` handler no longer calls `terminateCallOnUnload`.
+
+### R3: Call Recording Saved to Database / S3
+
+Recording happens server-side in the Go media server. Both audio streams (customer via Peer A, agent via Peer B) are captured as OGG/Opus with stereo channel separation (L=customer, R=agent). On call end, Rails fetches the recording file from the media server via internal HTTP and attaches it to ActiveStorage.
+
+**Acceptance criteria:**
+- Recording is captured entirely server-side. No `MediaRecorder`, `AudioContext`, or WebM blob logic in the browser.
+- Recording survives agent browser crash (server was recording the whole time).
+- Recording is stereo: left channel = customer, right channel = agent.
+- Recording is available in ActiveStorage within 60 seconds of call end.
+- Existing transcription pipeline (`CallTranscriptionJob`) works with the new OGG/Opus format.
+
+### R4: Multiple Frontends Can Join the Same Call
+
+Multiple agent browser tabs or different agents can connect to the same call session. The media server supports multiple Peer B connections with roles: `active` (sends and receives audio), `listen_only` (receives audio, mic muted server-side), and `inject_only` (sends audio only, for playback systems).
+
+**Acceptance criteria:**
+- A supervisor can join an active call in listen-only mode and hear both sides.
+- The primary agent's audio is not affected by a listener joining.
+- A `call_participants` table tracks who is connected and their role.
+- Frontend shows a participant list during active calls.
+
+### R5: Play Song/Message to Caller
+
+The media server can inject audio from a file (MP3, OGG, WAV) into the Meta-side peer (Peer A) as RTP packets. This enables hold music when the agent disconnects and pre-recorded announcements.
+
+**Acceptance criteria:**
+- When the agent disconnects, the customer automatically hears hold music instead of silence.
+- An API endpoint allows playing an audio file to the caller mid-call.
+- Audio injection does not interrupt the agent's audio when the agent is connected.
+- Default hold music is configurable per account or inbox.
+
+### R6: AI Captain Integration Readiness
+
+The media server architecture supports tapping the audio stream for real-time AI processing. A plugin interface (`AudioConsumer`) allows external systems to receive a copy of the audio in real time. A "virtual peer" concept allows AI to inject audio (e.g., suggested responses, automated greetings) into the call.
+
+**Acceptance criteria:**
+- An `AudioConsumer` plugin interface exists in the Go media server.
+- An RTP tap can stream audio to an external service (WebSocket or gRPC).
+- A virtual peer can inject synthesized audio into the call.
+- Rails has service hooks for AI streaming integration.
+- No AI features ship in this migration -- this is the foundation only.
+
+---
+
+## 2. Architecture Decision: WebRTC Peer B (NOT WebSocket Audio)
+
+### The Decision
+
+The agent's browser connects to the Go media server via a standard WebRTC peer connection (Peer B). The browser still uses `RTCPeerConnection`, `getUserMedia`, and native audio playback -- but it peers with the Go server, not with Meta directly.
+
+### Why WebRTC Peer B Over Binary WebSocket Relay
+
+The alternative considered was streaming raw audio over WebSocket (binary frames of PCM or Opus). This was rejected for five reasons:
+
+**1. Latency.** WebRTC delivers sub-50ms end-to-end latency via UDP with jitter buffers, adaptive bitrate, and congestion control built into the protocol. WebSocket runs over TCP, which adds 100-200ms of latency due to head-of-line blocking, Nagle's algorithm, and the lack of purpose-built jitter compensation. For real-time voice, this difference is audible.
+
+**2. Echo cancellation.** Browser echo cancellation (AEC) is tightly coupled to the WebRTC stack. It operates on the `RTCPeerConnection` audio pipeline. With WebSocket audio, there is no native AEC -- it would need to be implemented manually or disabled entirely, causing echo for agents without headsets.
+
+**3. No custom audio pipeline needed.** WebRTC handles decode, jitter buffering, volume normalization, and playback natively. WebSocket audio requires building all of this in JavaScript: decoding Opus frames, managing a playback buffer, scheduling `AudioContext` output, and handling underruns. This is hundreds of lines of fragile browser code.
+
+**4. NAT traversal.** WebRTC handles NAT traversal automatically via ICE/STUN/TURN. WebSocket requires the server to be directly addressable on a stable URL (typically behind a reverse proxy), and does not support UDP fallback for restrictive networks.
+
+**5. Code reuse.** The browser already has WebRTC code for the current direct-to-Meta flow. Switching to Peer B requires minimal frontend changes (different SDP source, remove recording). Switching to WebSocket audio would be a complete rewrite of the audio pipeline.
+
+### What Changes for the Browser
+
+| Aspect | Current (direct to Meta) | New (Peer B to media server) |
+|--------|--------------------------|------------------------------|
+| `RTCPeerConnection` target | Meta media servers | Go media server |
+| SDP offer source | Meta webhook payload | Media server (via ActionCable) |
+| SDP answer destination | Meta API (via Rails) | Media server (via Rails) |
+| `MediaRecorder` | Active (browser records) | Removed (server records) |
+| `beforeunload` behavior | Terminates call | Does nothing (call persists) |
+| Reconnect on reload | Not possible | Automatic via `GET /active` |
+
+### What Does NOT Change for the Browser
+
+- Still uses `getUserMedia({ audio: true })` for microphone access.
+- Still creates `RTCPeerConnection` with ICE servers.
+- Still uses `ontrack` to play remote audio.
+- Still uses `setRemoteDescription` and `createAnswer` for SDP exchange.
+- The Vue composable API surface (`acceptCall`, `endActiveCall`, `toggleMute`) stays the same.
+
+---
+
+## 3. Current State Assessment
+
+### What Exists Today (on `feat/whatsapp-call` branch)
+
+The browser-direct WhatsApp calling feature is substantially implemented across 9 planned PRs. The following is already built or merged:
+
+**Merged to `develop`:**
+- PR-1: `Call` model, migration (`20260408170902_create_calls.rb`), error classes, feature flag definition.
+
+**On `feat/whatsapp-call` branch (not yet merged):**
+- `Whatsapp::IncomingCallService` -- processes Meta webhooks, creates Call records, broadcasts ActionCable events.
+- `Whatsapp::CallService` -- accept/reject/terminate orchestration with `pre_accept_and_accept(sdp_answer)`.
+- `Whatsapp::CallMessageBuilder` -- creates `voice_call` message content type.
+- `Whatsapp::CallTranscriptionService` + `CallTranscriptionJob` -- OpenAI Whisper integration.
+- `Whatsapp::CallPermissionReplyService` -- handles outbound call permission opt-in.
+- `WhatsappCallsController` -- 6 endpoints (show, accept, reject, terminate, initiate, upload_recording).
+- `WhatsappCloudCallMethods` -- Meta Cloud API provider layer.
+- Frontend: API client, Pinia store, WebRTC composable, WhatsappCallWidget, VoiceCall bubble, ActionCable handlers, outbound UI in ConversationHeader.
+
+### What Needs to Change for Server-Side WebRTC
+
+The migration modifies existing code rather than replacing it entirely. The key changes are:
+
+**Rails services (modify):**
+- `IncomingCallService`: instead of storing Meta's SDP offer for the browser, create a media server session and store `media_session_id`.
+- `CallService#pre_accept_and_accept`: no longer receives `sdp_answer` from the browser. Instead, the SDP answer comes from the media server. Orchestrates Peer B setup after accepting Meta's call.
+- Controller: `accept` no longer requires `sdp_answer` parameter. New actions: `active`, `agent_answer`, `reconnect`. Remove `upload_recording`.
+
+**Rails services (new):**
+- `Whatsapp::MediaServerClient` -- HTTP client for the Go media server internal API.
+- `Whatsapp::CallReconnectService` -- handles agent reconnection after page reload.
+- `Whatsapp::CallRecordingFetchJob` -- Sidekiq job to fetch recording from media server on call end.
+
+**Frontend (modify):**
+- `useWhatsappCallSession.js`: remove `MediaRecorder` logic, remove `terminateCallOnUnload`, add reconnection flow, receive SDP from media server instead of Meta.
+- `whatsappCalls.js` store: add reconnection state, handle `agent_offer` event.
+- `whatsappCalls.js` API: remove `uploadRecording`, add `agentAnswer`, `reconnect`, `getActiveCall`.
+- `ConversationHeader.vue`: outbound initiate no longer sends `sdp_offer` from browser.
+
+**New component (Go):**
+- `chatwoot-media-server` -- Pion-based sidecar handling Peer A (Meta), Peer B (agent), audio bridge, and recording.
+
+### Known Technical Debt in Current Implementation
+
+These issues exist in the current branch and should be resolved during or before the migration:
+
+1. **Duplicated ICE gathering logic** -- `waitForOutboundIceGathering` in ConversationHeader duplicates `waitForIceGatheringComplete` in the composable. With Peer B, ICE gathering moves to the media server for Peer A and stays in the browser only for Peer B.
+2. **No `onUnmounted` cleanup** for outbound calls in ConversationHeader. The outbound WebRTC objects (`outboundCall.pc`, `.stream`) leak if the component unmounts mid-call.
+3. **Hardcoded STUN server** -- `stun:stun.l.google.com:19302` with no backend-provided configuration. The media server migration introduces proper ICE server configuration via environment variables.
+4. **`console.log` left in** -- ICE state logging in ConversationHeader.
+5. **Recording mimeType assumption** -- `audio/webm;codecs=opus` with no browser feature detection. Moot after migration (server records).
+6. **Bare string in ActionCable** -- `onWhatsappCallPermissionGranted` uses template literal instead of i18n key.
+7. **Feature flag unused on frontend** -- `FEATURE_FLAGS.WHATSAPP_CALL` declared but no component checks it.
+
+---
+
+## 4. Implementation Phases
+
+### Phase 1: Foundation -- Database, Configuration, Go Scaffold
+
+**Goal:** Infrastructure prerequisites. The media server has a health endpoint, Rails can talk to it, and the database supports media session tracking.
+
+**Estimated effort:** 1 week
+
+#### Database Migration
+
+- [ ] **`db/migrate/YYYYMMDDHHMMSS_add_media_session_id_to_calls.rb`** (NEW)
+  - Add `media_session_id` string column to `calls` table
+  - Add index on `media_session_id`
+  - Migration is backward-compatible (nullable column, no default)
+
+#### Rails Configuration
+
+- [ ] **`enterprise/app/services/whatsapp/media_server_client.rb`** (NEW)
+  - HTTP client wrapping Faraday for communication with the Go media server
+  - Methods: `create_session`, `meta_sdp`, `agent_offer`, `agent_answer`, `agent_reconnect`, `terminate`, `session_status`, `download_recording`, `health`
+  - Authentication via Bearer token from `ENV['MEDIA_SERVER_AUTH_TOKEN']`
+  - Timeout configuration: 5s connect, 30s read (SDP generation may involve ICE gathering)
+  - Error handling: raise `Whatsapp::CallErrors::MediaServerError` on failures
+  - Circuit breaker pattern: if health check fails 3 times, stop attempting new sessions
+
+- [ ] **`config/media_server.yml`** (NEW) or environment variable approach
+  - `MEDIA_SERVER_URL` (default: `http://localhost:4000`)
+  - `MEDIA_SERVER_AUTH_TOKEN`
+  - `MEDIA_SERVER_STUN_SERVERS` (comma-separated, default: `stun:stun.l.google.com:19302`)
+  - `MEDIA_SERVER_TURN_SERVERS` (optional)
+  - `MEDIA_SERVER_TURN_USERNAME` (optional)
+  - `MEDIA_SERVER_TURN_PASSWORD` (optional)
+  - `MEDIA_SERVER_PUBLIC_IP` (required for ICE candidate in SDP)
+
+- [ ] **`enterprise/app/models/call.rb`** (MODIFY)
+  - Add `media_session_id` accessor and convenience methods
+  - Add `media_session_active?` method that checks media server status
+  - Add `meta_server_url` method (for multi-instance routing in the future)
+
+#### Go Media Server Scaffold
+
+- [ ] **`enterprise/media-server/main.go`** (NEW)
+  - HTTP server on configurable port (default 4000)
+  - Graceful shutdown on SIGTERM/SIGINT
+  - Structured logging (JSON format for production)
+
+- [ ] **`enterprise/media-server/config/config.go`** (NEW)
+  - Parse environment variables: `AUTH_TOKEN`, `STUN_SERVERS`, `TURN_SERVERS`, `PUBLIC_IP`, `UDP_PORT_MIN`, `UDP_PORT_MAX`, `RECORDINGS_DIR`, `RAILS_CALLBACK_URL`, `LOG_LEVEL`
+
+- [ ] **`enterprise/media-server/api/handler.go`** (NEW)
+  - Route definitions for all endpoints
+  - `GET /health` returns `{"status": "ok", "active_sessions": N, "uptime_seconds": N}`
+
+- [ ] **`enterprise/media-server/api/middleware.go`** (NEW)
+  - Bearer token authentication middleware
+  - Request logging middleware
+  - Recovery/panic middleware
+
+- [ ] **`enterprise/media-server/go.mod`** (NEW)
+  - Module: `github.com/chatwoot/chatwoot-media-server`
+  - Dependencies: `pion/webrtc/v4`, `pion/interceptor`, standard library HTTP
+
+- [ ] **`enterprise/media-server/Dockerfile`** (NEW)
+  - Multi-stage build: Go build stage + scratch/alpine runtime
+  - Target image size: under 30 MB
+  - Expose port 4000 (HTTP) and UDP port range
+
+- [ ] **`docker-compose.yml`** (MODIFY) or **`docker-compose.deploy.yaml`** (MODIFY)
+  - Add `media-server` service definition
+  - UDP port range exposure: `10000-10100:10000-10100/udp`
+  - Shared volume for recordings
+  - Health check pointing to `/health`
+  - Environment variables from `.env`
+
+- [ ] **`Procfile.dev`** (MODIFY)
+  - Add media server process: `media: ./enterprise/media-server/chatwoot-media-server`
+
+#### Verification
+
+- [ ] `GET /health` returns 200 from inside Docker network
+- [ ] `MediaServerClient.new.health` returns successfully from Rails console
+- [ ] Migration runs cleanly: `bundle exec rails db:migrate`
+- [ ] `Call.new(media_session_id: 'test')` works
+
+---
+
+### Phase 2: Core Call Flow
+
+**Goal:** Inbound and outbound calls work end-to-end through the media server. The browser peers with the Go server, not Meta directly.
+
+**Estimated effort:** 2-3 weeks
+
+#### Go Media Server: Peer A (Meta-side WebRTC)
+
+- [ ] **`enterprise/media-server/session/manager.go`** (NEW)
+  - Thread-safe session map (sync.RWMutex)
+  - `CreateSession(callID, metaSDP, iceServers)` -- creates session and Peer A
+  - `FindSession(sessionID)` -- lookup by ID
+  - `DestroySession(sessionID)` -- teardown both peers
+  - Periodic cleanup goroutine: destroy sessions idle for >2 hours
+  - Session creation rate limit per account_id
+
+- [ ] **`enterprise/media-server/session/session.go`** (NEW)
+  - Holds Peer A, Peer B (optional), bridge, recording state
+  - State machine: `created -> meta_peer_ready -> bridged -> agent_disconnected -> terminated`
+  - `SetMetaSDP(offer) -> answer` -- set Meta's SDP on Peer A, return generated answer
+  - `CreateAgentOffer() -> sdpOffer` -- create Peer B, generate SDP offer for agent
+  - `SetAgentAnswer(answer)` -- complete Peer B, start bridge and recording
+  - `AgentReconnect() -> sdpOffer` -- tear down old Peer B, create new one
+  - `Terminate()` -- close both peers, finalize recording, notify Rails
+
+- [ ] **`enterprise/media-server/session/peer.go`** (NEW)
+  - Wraps `pion/webrtc.PeerConnection`
+  - Configures audio-only media (no video)
+  - ICE candidate handling: trickle or full gather (configurable)
+  - ICE candidate filtering: strip `host` candidates from agent-facing offers
+  - `OnTrack` callback registration for the bridge
+  - `OnICEConnectionStateChange` callback for disconnect detection
+
+- [ ] **`enterprise/media-server/session/bridge.go`** (NEW)
+  - Forward RTP packets from Peer A remote track to Peer B local track
+  - Forward RTP packets from Peer B remote track to Peer A local track
+  - Tap both streams for the recording pipeline
+  - Packet copying (not pointer sharing) to avoid races between bridge and recorder
+  - Graceful handling of one peer disconnecting while the other stays up
+
+#### Go Media Server: Peer B (Agent-side WebRTC)
+
+- [ ] **Peer B creation in `session.go`** (part of session implementation above)
+  - Create `PeerConnection` with STUN/TURN configuration
+  - Add audio transceiver (sendrecv)
+  - Generate SDP offer with ICE candidates
+  - Public IP override in SDP if `MEDIA_SERVER_PUBLIC_IP` is set
+  - On Peer B ICE failure: transition to `agent_disconnected`, notify Rails via callback
+
+#### Go Media Server: HTTP API Endpoints
+
+- [ ] **`enterprise/media-server/api/session_handler.go`** (NEW)
+  - `POST /sessions` -- create session with Meta SDP, return session_id + SDP answer
+  - `GET /sessions/:id/status` -- return session state, peer connection states, duration
+  - `DELETE /sessions/:id` -- force-destroy session
+
+- [ ] **`enterprise/media-server/api/meta_sdp_handler.go`** (NEW)
+  - `POST /sessions/:id/meta-sdp` -- for outbound calls: set Meta's SDP answer on Peer A
+
+- [ ] **`enterprise/media-server/api/agent_handler.go`** (NEW)
+  - `POST /sessions/:id/agent-offer` -- generate SDP offer for agent browser
+  - `POST /sessions/:id/agent-answer` -- set agent's SDP answer, start bridge
+  - `POST /sessions/:id/agent-reconnect` -- tear down old Peer B, create new offer
+
+- [ ] **`enterprise/media-server/api/recording_handler.go`** (NEW, stub for Phase 3)
+  - `GET /sessions/:id/recording` -- download recording file (returns 404 until Phase 3)
+
+- [ ] **`enterprise/media-server/callback/rails_client.go`** (NEW)
+  - HTTP client for callbacks to Rails
+  - `POST /api/internal/media_server/callbacks` with events: `agent_disconnected`, `agent_reconnected`, `session_terminated`, `recording_ready`
+  - Retry logic: 3 attempts with exponential backoff
+  - Authentication: same shared secret token
+
+#### Rails: Modify IncomingCallService
+
+- [ ] **`enterprise/app/services/whatsapp/incoming_call_service.rb`** (MODIFY)
+  - In `handle_call_connect` for inbound calls:
+    - After creating the Call record, call `MediaServerClient.create_session` with Meta's SDP offer
+    - Store `media_session_id` on the Call record
+    - Store the media server's SDP answer (to send to Meta) instead of Meta's SDP offer (for the browser)
+    - The SDP answer sent to Meta comes from the media server, not the browser
+  - Feature-flagged: check `whatsapp_call_server_media` flag to use new path vs legacy
+  - In `broadcast_incoming_call`: do NOT include `sdp_offer` in the ActionCable payload (the browser no longer needs it for direct peering)
+
+#### Rails: Modify CallService
+
+- [ ] **`enterprise/app/services/whatsapp/call_service.rb`** (MODIFY)
+  - `pre_accept_and_accept` no longer receives `sdp_answer` from the browser
+  - New flow:
+    1. Lock the call row, validate ringing state
+    2. Call Meta's `pre_accept_call` with the SDP answer stored in `Call.meta` (from the media server)
+    3. Call Meta's `accept_call` with the same SDP answer
+    4. Update call status to `in_progress`
+    5. Request agent-side SDP offer from media server: `MediaServerClient.agent_offer(media_session_id)`
+    6. Broadcast `whatsapp_call.agent_offer` via ActionCable with the SDP offer and ICE servers
+  - Outbound `initiate` flow:
+    1. Create media session (direction: outbound, no Meta SDP yet)
+    2. Get SDP offer from media server for Meta
+    3. Call Meta's `initiate_call` with the media server's SDP offer
+    4. On Meta's webhook with SDP answer, call `MediaServerClient.meta_sdp(session_id, sdp_answer)` to complete Peer A
+    5. Then set up Peer B same as inbound
+  - New method: `agent_answer(sdp_answer)` -- forwards agent's SDP answer to media server
+
+#### New Controller Actions
+
+- [ ] **`enterprise/app/controllers/api/v1/accounts/whatsapp_calls_controller.rb`** (MODIFY)
+  - `GET /active` (NEW action) -- return the agent's currently active call (if any), used for reconnection on page load
+    ```
+    GET /api/v1/accounts/:account_id/whatsapp_calls/active
+    Response: { id, call_id, status, conversation_id, started_at, duration_seconds } or 204 No Content
+    ```
+  - `POST /:id/agent_answer` (NEW action) -- receive SDP answer from agent browser, forward to media server
+    ```
+    POST /api/v1/accounts/:account_id/whatsapp_calls/:id/agent_answer
+    Body: { sdp_answer: "..." }
+    ```
+  - `POST /:id/reconnect` (NEW action) -- agent reconnects to an active call after page reload
+    ```
+    POST /api/v1/accounts/:account_id/whatsapp_calls/:id/reconnect
+    Response: { sdp_offer: "...", ice_servers: [...] }
+    ```
+  - `POST /:id/accept` (MODIFY) -- remove `sdp_answer` requirement from params
+  - `POST /initiate` (MODIFY) -- remove `sdp_offer` requirement from params
+
+- [ ] **`config/routes.rb`** (MODIFY)
+  - Add `member` routes: `agent_answer`, `reconnect`
+  - Add `collection` route: `active`
+
+#### Rails: Internal Callbacks Controller
+
+- [ ] **`enterprise/app/controllers/api/internal/media_server/callbacks_controller.rb`** (NEW)
+  - Receives events from the Go media server
+  - Authentication: validate shared secret token
+  - Events handled:
+    - `agent_disconnected`: broadcast `whatsapp_call.agent_disconnected` via ActionCable, start reconnect timer
+    - `recording_ready`: enqueue `CallRecordingFetchJob`
+    - `session_terminated`: if call not already terminated, update status and broadcast
+
+- [ ] **`config/routes.rb`** (MODIFY)
+  - Add internal API namespace for media server callbacks
+
+#### ActionCable Event Changes
+
+- [ ] **`app/javascript/dashboard/helper/actionCable.js`** (MODIFY)
+  - Add handler for `whatsapp_call.agent_offer` -- delivers SDP offer from media server to the agent browser for Peer B setup
+  - Add handler for `whatsapp_call.agent_disconnected` -- notifies other tabs/agents that the primary agent's connection dropped
+  - Modify `whatsapp_call.incoming` handler -- no longer includes `sdp_offer` in payload
+  - Modify `whatsapp_call.outbound_connected` handler -- no longer includes `sdp_answer` in payload (SDP exchange happens via media server)
+
+#### Frontend Composable Refactor
+
+- [ ] **`app/javascript/dashboard/composables/useWhatsappCallSession.js`** (MODIFY)
+  - **Remove:** `startCallRecording`, `stopAndUploadRecording`, `mediaRecorder`, `recordedChunks`, `recordingCallId` -- all recording logic
+  - **Remove:** `terminateCallOnUnload` -- call persists on page close
+  - **Modify `doAcceptCall`:**
+    - No longer receives `sdp_offer` from Meta
+    - No longer calls `pc.setRemoteDescription` with Meta's offer
+    - No longer calls `WhatsappCallsAPI.accept(call.id, completeSdp)`
+    - New flow: call `WhatsappCallsAPI.accept(call.id)` (no SDP), then wait for `agent_offer` ActionCable event
+  - **Add `handleAgentOffer(sdpOffer, iceServers)`:**
+    - Called when `whatsapp_call.agent_offer` event arrives
+    - `getUserMedia({ audio: true })`
+    - Create `RTCPeerConnection` with provided `iceServers`
+    - `setRemoteDescription(offer)` with media server's SDP offer
+    - `createAnswer()` + ICE gathering
+    - POST SDP answer to `WhatsappCallsAPI.agentAnswer(callId, sdpAnswer)`
+  - **Modify `beforeunload` handler:**
+    - Do NOT call `terminateCallOnUnload`
+    - Just clean up the local `RTCPeerConnection` and `MediaStream` (Peer B dies naturally)
+  - **Remove** `startCallRecording` call from `pc.ontrack` handler
+
+- [ ] **`app/javascript/dashboard/stores/whatsappCalls.js`** (MODIFY)
+  - Add state: `isReconnecting` (boolean), `reconnectAttempts` (number)
+  - Add action: `handleAgentOffer(payload)` -- stores the SDP offer and triggers the composable
+  - Add action: `setReconnecting(value)` -- manages reconnection UI state
+  - Remove: outbound call `sdp_offer` handling (the browser no longer generates the initial offer for outbound)
+  - Add action: `handleAgentDisconnected(callId)` -- handles notification that agent connection dropped (for multi-tab awareness)
+
+- [ ] **`app/javascript/dashboard/api/whatsappCalls.js`** (MODIFY)
+  - `accept(callId)` -- remove `sdpAnswer` parameter
+  - `initiate(conversationId)` -- remove `sdpOffer` parameter
+  - **Add:** `agentAnswer(callId, sdpAnswer)` -- POST SDP answer to new endpoint
+  - **Add:** `reconnect(callId)` -- POST to reconnect endpoint
+  - **Add:** `getActiveCall()` -- GET active call for current agent
+  - **Remove:** `uploadRecording(callId, blob)`
+
+- [ ] **`app/javascript/dashboard/components/widgets/conversation/ConversationHeader.vue`** (MODIFY)
+  - Remove outbound `RTCPeerConnection` creation and SDP offer generation
+  - Remove `waitForOutboundIceGathering` (duplicated ICE logic)
+  - Remove `console.log` statements for ICE state
+  - Outbound initiate now just calls `WhatsappCallsAPI.initiate(conversationId)` with no SDP
+  - Wait for `agent_offer` event (same as inbound) after contact answers
+
+#### Verification
+
+- [ ] Inbound call: Meta webhook -> media server session -> agent accepts -> audio flows through media server
+- [ ] Outbound call: agent initiates -> media server creates offer -> Meta receives -> contact answers -> audio flows
+- [ ] SDP exchange does not require `actpass -> active` string replacement
+- [ ] Both browser-direct (legacy) and server-media paths work when feature-flagged
+
+---
+
+### Phase 3: Server-Side Recording
+
+**Goal:** Recording happens entirely on the Go media server. Browser recording code is removed. Recordings are fetched by Rails on call end.
+
+**Estimated effort:** 1 week
+
+#### Go Media Server: Recording Pipeline
+
+- [ ] **`enterprise/media-server/recording/recorder.go`** (NEW)
+  - Receives decoded Opus frames from both Peer A and Peer B via the bridge's tap
+  - Writes frames into OGG/Opus container in real time
+  - Stereo separation: Peer A (customer) on left channel, Peer B (agent) on right channel
+  - File path: `/recordings/{session_id}.ogg`
+  - Starts when both peers are connected and bridge is active
+  - Pauses agent channel (writes silence) when Peer B is disconnected (reconnection gap)
+  - Finalizes (writes OGG trailer) when session terminates
+
+- [ ] **`enterprise/media-server/recording/ogg_writer.go`** (NEW)
+  - Low-level OGG page construction
+  - Handles page sequencing, checksums, and granule position tracking
+  - Based on Pion's `oggreader`/`oggwriter` examples
+
+- [ ] **`enterprise/media-server/recording/cleanup.go`** (NEW)
+  - On startup: scan `/recordings/` for orphaned files (sessions that no longer exist)
+  - Report orphaned files to Rails via callback
+  - Delete orphaned files older than 24 hours
+
+- [ ] **`enterprise/media-server/api/recording_handler.go`** (MODIFY -- implement the stub from Phase 2)
+  - `GET /sessions/:id/recording` -- stream the finalized OGG file with `Content-Type: audio/ogg`
+  - `POST /sessions/:id/terminate` response now includes `recording_file`, `recording_size_bytes`, `duration_seconds`
+
+#### Rails: Recording Fetch Job
+
+- [ ] **`enterprise/app/jobs/whatsapp/call_recording_fetch_job.rb`** (NEW)
+  - Triggered by `recording_ready` callback from media server
+  - Downloads recording from `MediaServerClient.download_recording(session_id)`
+  - Attaches to `call.recording` via ActiveStorage
+  - Updates the message bubble with recording URL via `CallMessageBuilder.update_recording_url!`
+  - Enqueues `CallTranscriptionJob` after successful attachment
+  - Retry: 3 attempts with exponential backoff
+  - On final failure: log error, mark call with `recording_fetch_failed` in meta
+
+#### Rails: Remove Browser Upload Path
+
+- [ ] **`enterprise/app/controllers/api/v1/accounts/whatsapp_calls_controller.rb`** (MODIFY)
+  - Remove `upload_recording` action (behind feature flag -- keep for legacy path)
+  - Remove `attach_recording_and_enqueue_transcription` private method (behind feature flag)
+
+#### Frontend: Remove Recording Code
+
+- [ ] **`app/javascript/dashboard/composables/useWhatsappCallSession.js`** (MODIFY)
+  - Remove `startCallRecording` export
+  - Remove `stopAndUploadRecording` function
+  - Remove `mediaRecorder`, `recordedChunks`, `recordingCallId` module-level variables
+  - Remove `startCallRecording(pc, stream, call.id)` call from `ontrack` handler
+  - Remove `stopAndUploadRecording()` from cleanup callback and `endActiveCall`
+
+- [ ] **`app/javascript/dashboard/api/whatsappCalls.js`** (MODIFY)
+  - Remove `uploadRecording` method (if not already removed in Phase 2)
+
+#### Verification
+
+- [ ] Call completes -> recording appears in ActiveStorage within 60 seconds
+- [ ] Recording is OGG/Opus format, playable in browser audio player
+- [ ] Recording has stereo channels (customer left, agent right)
+- [ ] Transcription job runs successfully on the new format
+- [ ] Browser has zero recording-related code when `whatsapp_call_server_media` is enabled
+- [ ] Agent browser crash mid-call -> recording is still captured up to the crash point
+
+---
+
+### Phase 4: Call Persistence & Reconnection
+
+**Goal:** Calls survive browser close/refresh. Automatic reconnection on page reload.
+
+**Estimated effort:** 1-2 weeks
+
+#### Go Media Server: Disconnect Detection & Hold
+
+- [ ] **`enterprise/media-server/session/session.go`** (MODIFY)
+  - On Peer B ICE connection state `disconnected` or `failed`:
+    - Transition session state to `agent_disconnected`
+    - Keep Peer A alive (Meta audio continues to flow into the bridge's buffer)
+    - Start reconnect timeout (configurable, default 30s)
+    - Callback to Rails: `agent_disconnected` event
+    - If hold music is configured (Phase 6), start playing it to Peer A
+  - On reconnect timeout expiry:
+    - Callback to Rails: `session_terminated` with reason `agent_reconnect_timeout`
+    - Terminate session
+
+- [ ] **`enterprise/media-server/session/session.go`** (MODIFY -- reconnect logic)
+  - `AgentReconnect()`:
+    - Tear down old Peer B (close connection, release resources)
+    - Create new Peer B with fresh SDP offer
+    - On successful answer: re-bridge audio, resume recording
+    - Callback to Rails: `agent_reconnected` event
+    - Increment reconnect counter on session
+
+#### Rails: Reconnection Support
+
+- [ ] **`enterprise/app/services/whatsapp/call_reconnect_service.rb`** (NEW)
+  - Called from `WhatsappCallsController#reconnect`
+  - Validates: call is `in_progress`, call has `media_session_id`, requesting agent is the accepted agent
+  - Calls `MediaServerClient.agent_reconnect(media_session_id)`
+  - Returns new SDP offer for the agent browser
+  - Broadcasts `whatsapp_call.agent_offer` via ActionCable
+
+- [ ] **`enterprise/app/controllers/api/v1/accounts/whatsapp_calls_controller.rb`** (MODIFY -- `active` action)
+  - `GET /active`: find the current user's active call (status `in_progress`, `accepted_by_agent_id` = current_user.id)
+  - Return call details including `media_session_id`, `started_at`, `conversation_id`
+  - Used by the frontend on page load to detect if a call needs reconnection
+
+#### Frontend: Reconnection Composable
+
+- [ ] **`app/javascript/dashboard/composables/useCallReconnection.js`** (NEW)
+  - On mount: call `WhatsappCallsAPI.getActiveCall()`
+  - If active call exists:
+    - Set store state: `isReconnecting = true`
+    - Show reconnection UI: "Call in progress -- Reconnecting..."
+    - Call `WhatsappCallsAPI.reconnect(callId)`
+    - Handle `agent_offer` event (same flow as initial accept)
+    - On success: `isReconnecting = false`, show active call UI with correct timer
+    - On failure: offer "Retry" button or end call
+  - Timer continuity: calculate elapsed time from `started_at` returned by server, not local state
+
+- [ ] **`app/javascript/dashboard/composables/useWhatsappCallSession.js`** (MODIFY)
+  - **Remove `terminateCallOnUnload`** function entirely
+  - **Modify `handleBeforeUnload`:**
+    - Do NOT terminate the call
+    - Clean up local WebRTC resources (close `RTCPeerConnection`, stop `MediaStream` tracks)
+    - The media server detects Peer B disconnect via ICE and handles it
+  - **Add reconnection integration:**
+    - On composable mount, check for active call via `useCallReconnection`
+    - If reconnecting, skip the incoming call widget and go straight to active call UI
+
+- [ ] **`app/javascript/dashboard/stores/whatsappCalls.js`** (MODIFY)
+  - Add `isReconnecting` state
+  - Add `reconnectAttempts` counter
+  - `handleAgentDisconnected(callId)`: set `isReconnecting = true` if this is our active call
+
+- [ ] **`app/javascript/dashboard/components/widgets/WhatsappCallWidget.vue`** (MODIFY)
+  - Add reconnecting state to the widget UI
+  - Show "Reconnecting..." with a spinner instead of the normal call controls
+  - Display server-tracked call duration (from `started_at`) instead of local timer
+
+#### Verification
+
+- [ ] Agent refreshes page during active call -> call does not terminate
+- [ ] On reload, dashboard shows "Reconnecting..." and audio resumes within 3 seconds
+- [ ] Call duration timer is continuous (no reset on reconnect)
+- [ ] Customer hears silence (or hold tone) during the 1-3 second gap
+- [ ] If agent does not reconnect within 30s, call terminates and Meta receives hangup
+- [ ] Multiple reconnections work (refresh 5 times in a row)
+- [ ] Recording is continuous across reconnections (single file, agent channel silent during gaps)
+
+---
+
+### Phase 5: Multi-Participant
+
+**Goal:** Multiple agents can join the same call with different roles.
+
+**Estimated effort:** 2 weeks
+
+#### Database
+
+- [ ] **`db/migrate/YYYYMMDDHHMMSS_create_call_participants.rb`** (NEW)
+  ```
+  create_table :call_participants do |t|
+    t.bigint :call_id, null: false
+    t.bigint :user_id, null: false
+    t.string :role, null: false, default: 'active'  # active, listen_only, inject_only
+    t.string :peer_id  # media server peer identifier
+    t.datetime :joined_at
+    t.datetime :left_at
+    t.timestamps
+  end
+  add_index :call_participants, [:call_id, :user_id], unique: true
+  add_index :call_participants, :call_id
+  ```
+
+- [ ] **`enterprise/app/models/call_participant.rb`** (NEW)
+  - `belongs_to :call`
+  - `belongs_to :user`
+  - Validations: role inclusion, uniqueness of user per call
+  - Scopes: `active`, `connected` (where `left_at` is nil)
+
+- [ ] **`enterprise/app/models/call.rb`** (MODIFY)
+  - `has_many :call_participants`
+  - `has_many :participants, through: :call_participants, source: :user`
+
+#### Go Media Server: Multi-Peer Support
+
+- [ ] **`enterprise/media-server/session/session.go`** (MODIFY)
+  - Support multiple Peer B connections per session (keyed by `peer_id`)
+  - Each peer has a role:
+    - `active`: bidirectional audio (current single-agent behavior)
+    - `listen_only`: receives mixed audio from Peer A + all active peers, does not transmit
+    - `inject_only`: can send audio into the mix but does not receive
+  - Audio bridge modification: mix audio from Peer A + all active peer B connections, send mixed output to each peer
+
+- [ ] **`enterprise/media-server/session/mixer.go`** (NEW)
+  - Audio mixer: combine Opus frames from multiple sources
+  - For each output peer: mix all other sources (exclude self to prevent echo)
+  - Efficient: only active when multiple active peers exist, otherwise pass-through
+
+#### Rails: Join/Leave Endpoints
+
+- [ ] **`enterprise/app/controllers/api/v1/accounts/whatsapp_calls_controller.rb`** (MODIFY)
+  - `POST /:id/join` -- join an active call as listener or active participant
+  - `POST /:id/leave` -- leave the call (close your Peer B)
+  - `GET /:id/participants` -- list current participants and their roles
+
+- [ ] **`enterprise/app/services/whatsapp/call_participant_service.rb`** (NEW)
+  - `join(call, user, role)`: create participant record, request peer from media server
+  - `leave(call, user)`: update participant record, disconnect peer on media server
+  - Authorization: only agents with access to the conversation can join
+
+#### Frontend: Participant List
+
+- [ ] **`app/javascript/dashboard/components/widgets/WhatsappCallParticipants.vue`** (NEW)
+  - Show list of connected participants with their roles
+  - "Join as listener" button for supervisors
+  - Uses Tailwind for styling, Composition API with `<script setup>`
+
+#### Verification
+
+- [ ] Supervisor joins active call in listen_only mode and hears both sides
+- [ ] Primary agent's audio quality unaffected by listener joining
+- [ ] `call_participants` table accurately reflects join/leave events
+- [ ] Participant list UI updates in real time via ActionCable
+
+---
+
+### Phase 6: Audio Injection / Hold Music
+
+**Goal:** The media server can play audio files to the caller. Hold music plays automatically when the agent disconnects.
+
+**Estimated effort:** 1-2 weeks
+
+#### Go Media Server: Audio File Injection
+
+- [ ] **`enterprise/media-server/audio/decoder.go`** (NEW)
+  - Decode audio files (MP3, OGG, WAV) to PCM
+  - Resample to 48kHz mono (Opus input format)
+  - Use Go standard library + minimal decoder packages
+
+- [ ] **`enterprise/media-server/audio/encoder.go`** (NEW)
+  - Encode PCM frames to Opus
+  - Package Opus frames as RTP packets with correct timestamps
+
+- [ ] **`enterprise/media-server/audio/injector.go`** (NEW)
+  - `InjectFile(session, filePath, loop bool)` -- decode file, encode to Opus, inject RTP packets into Peer A's send track
+  - `StopInjection(session)` -- stop current injection
+  - Loop support for hold music (seamless restart when file ends)
+  - Mixing: if agent is connected, mix injected audio with agent audio. If agent is disconnected, injected audio is the only source.
+
+- [ ] **`enterprise/media-server/session/session.go`** (MODIFY)
+  - On agent disconnect: if hold music path is configured, automatically start injection
+  - On agent reconnect: stop hold music injection, resume agent audio bridge
+
+- [ ] **`enterprise/media-server/api/audio_handler.go`** (NEW)
+  - `POST /sessions/:id/play_audio` -- trigger audio file playback
+    ```
+    Body: { file_path: "/audio/hold_music.ogg", loop: true }
+    ```
+  - `POST /sessions/:id/stop_audio` -- stop current playback
+
+#### Rails: Audio Asset Management
+
+- [ ] **Model or ActiveStorage approach for audio assets** (decision needed)
+  - Option A: `CallAudioAsset` model with ActiveStorage attachment + account_id
+  - Option B: Pre-deploy audio files to the media server's filesystem
+  - Recommendation: Option B for MVP (simpler), Option A for production
+  - Default hold music file ships with the media server Docker image
+
+- [ ] **`enterprise/app/controllers/api/v1/accounts/whatsapp_calls_controller.rb`** (MODIFY)
+  - `POST /:id/play_audio` -- trigger audio playback for a call
+  - Parameters: `audio_asset_id` or `audio_type` (e.g., "hold_music")
+
+#### Configuration
+
+- [ ] **Hold music configuration:**
+  - Default file: bundled with media server Docker image at `/audio/default_hold_music.ogg`
+  - Environment variable: `HOLD_MUSIC_PATH` (override default)
+  - Future: per-account or per-inbox configuration via `CallAudioAsset` model
+
+#### Verification
+
+- [ ] Agent disconnects -> customer hears hold music within 2 seconds
+- [ ] Agent reconnects -> hold music stops, agent audio resumes
+- [ ] `play_audio` API endpoint plays a file to the caller mid-call
+- [ ] Audio injection mixes correctly with agent audio when both are present
+
+---
+
+### Phase 7: AI Captain Foundation
+
+**Goal:** The architecture supports real-time audio streaming for AI processing. No AI features ship -- this is infrastructure only.
+
+**Estimated effort:** 1-2 weeks
+
+#### Go Media Server: Plugin Interface
+
+- [ ] **`enterprise/media-server/plugin/consumer.go`** (NEW)
+  - `AudioConsumer` interface:
+    ```go
+    type AudioConsumer interface {
+        OnAudioFrame(sessionID string, source string, frame []byte, timestamp uint32)
+        OnSessionStart(sessionID string, metadata map[string]string)
+        OnSessionEnd(sessionID string)
+    }
+    ```
+  - Registry: `RegisterConsumer(name string, consumer AudioConsumer)`
+  - Bridge modification: after forwarding each RTP packet, call all registered consumers
+
+- [ ] **`enterprise/media-server/plugin/rtp_tap.go`** (NEW)
+  - `RTPTap` implementation of `AudioConsumer`
+  - Streams decoded audio frames to an external service via WebSocket or gRPC
+  - Configurable target URL
+  - Buffering: ring buffer to handle temporary target unavailability
+  - Backpressure: drop frames if buffer is full (real-time audio cannot wait)
+
+- [ ] **`enterprise/media-server/session/virtual_peer.go`** (NEW)
+  - "Virtual peer" concept: a peer that exists only in software (no browser, no external WebRTC)
+  - Can inject audio into the bridge (e.g., TTS output from AI)
+  - Can receive audio from the bridge (e.g., for STT input)
+  - Registered as a special participant with role `ai`
+
+#### Rails: AI Service Hooks
+
+- [ ] **`enterprise/app/services/whatsapp/call_ai_streaming_service.rb`** (NEW, stub)
+  - Interface for connecting a call session to AI Captain
+  - Methods: `start_streaming(call)`, `stop_streaming(call)`, `inject_audio(call, audio_data)`
+  - Stub implementation that logs actions -- actual AI integration is a separate project
+
+#### Verification
+
+- [ ] `AudioConsumer` interface compiles and can be registered
+- [ ] RTP tap successfully streams audio frames to a test WebSocket endpoint
+- [ ] Virtual peer can inject audio that the customer hears
+- [ ] Rails AI service hooks exist and are callable (even though they are stubs)
+
+---
+
+## 5. API Surface Changes
+
+### New Go Media Server Internal HTTP API
+
+All endpoints are internal-only, authenticated via Bearer token.
+
+| Method | Path | Phase | Description |
+|--------|------|-------|-------------|
+| `GET` | `/health` | 1 | Health check with active session count |
+| `POST` | `/sessions` | 2 | Create session with Meta SDP, return SDP answer |
+| `POST` | `/sessions/:id/meta-sdp` | 2 | Set Meta's SDP answer (outbound calls) |
+| `POST` | `/sessions/:id/agent-offer` | 2 | Generate SDP offer for agent browser |
+| `POST` | `/sessions/:id/agent-answer` | 2 | Set agent's SDP answer, start audio bridge |
+| `POST` | `/sessions/:id/agent-reconnect` | 4 | Tear down old Peer B, create new SDP offer |
+| `POST` | `/sessions/:id/terminate` | 2 | End session, finalize recording |
+| `GET` | `/sessions/:id/status` | 2 | Session state, peer ICE states, duration |
+| `GET` | `/sessions/:id/recording` | 3 | Download finalized recording file |
+| `DELETE` | `/sessions/:id` | 2 | Force-destroy session |
+| `POST` | `/sessions/:id/play_audio` | 6 | Play audio file to caller |
+| `POST` | `/sessions/:id/stop_audio` | 6 | Stop current audio playback |
+
+### New/Modified Rails API Endpoints
+
+| Method | Path | Phase | Change | Description |
+|--------|------|-------|--------|-------------|
+| `GET` | `/api/v1/accounts/:id/whatsapp_calls/active` | 2 | NEW | Get agent's currently active call |
+| `POST` | `/api/v1/accounts/:id/whatsapp_calls/:id/accept` | 2 | MODIFY | No longer requires `sdp_answer` param |
+| `POST` | `/api/v1/accounts/:id/whatsapp_calls/:id/agent_answer` | 2 | NEW | Forward agent's SDP answer to media server |
+| `POST` | `/api/v1/accounts/:id/whatsapp_calls/:id/reconnect` | 4 | NEW | Reconnect to active call after page reload |
+| `POST` | `/api/v1/accounts/:id/whatsapp_calls/initiate` | 2 | MODIFY | No longer requires `sdp_offer` param |
+| `POST` | `/api/v1/accounts/:id/whatsapp_calls/:id/upload_recording` | 3 | REMOVE | Server records now; endpoint deprecated |
+| `POST` | `/api/v1/accounts/:id/whatsapp_calls/:id/join` | 5 | NEW | Join call as participant |
+| `POST` | `/api/v1/accounts/:id/whatsapp_calls/:id/leave` | 5 | NEW | Leave call |
+| `GET` | `/api/v1/accounts/:id/whatsapp_calls/:id/participants` | 5 | NEW | List call participants |
+| `POST` | `/api/v1/accounts/:id/whatsapp_calls/:id/play_audio` | 6 | NEW | Play audio to caller |
+| `POST` | `/api/internal/media_server/callbacks` | 2 | NEW | Receive events from media server |
+
+### Modified ActionCable Events
+
+| Event | Phase | Change | Payload Diff |
+|-------|-------|--------|-------------|
+| `whatsapp_call.incoming` | 2 | MODIFY | Remove `sdp_offer` and `ice_servers` (browser no longer needs Meta's SDP) |
+| `whatsapp_call.agent_offer` | 2 | NEW | `{ call_id, sdp_offer, ice_servers }` -- media server's SDP offer for Peer B |
+| `whatsapp_call.agent_disconnected` | 4 | NEW | `{ call_id, reconnect_timeout_seconds }` |
+| `whatsapp_call.agent_reconnected` | 4 | NEW | `{ call_id }` |
+| `whatsapp_call.outbound_connected` | 2 | MODIFY | Remove `sdp_answer` (SDP goes through media server) |
+| `whatsapp_call.participant_joined` | 5 | NEW | `{ call_id, user_id, role }` |
+| `whatsapp_call.participant_left` | 5 | NEW | `{ call_id, user_id }` |
+
+---
+
+## 6. Database Changes
+
+### Migration 1: Add media_session_id to calls (Phase 1)
+
+```ruby
+class AddMediaSessionIdToCalls < ActiveRecord::Migration[7.0]
+  def change
+    add_column :calls, :media_session_id, :string
+    add_index :calls, :media_session_id
+  end
+end
+```
+
+**Backward compatibility:** The column is nullable with no default. Existing calls (from the browser-direct path) will have `media_session_id = nil`. The feature flag `whatsapp_call_server_media` determines which path is used.
+
+### Migration 2: Create call_participants (Phase 5)
+
+```ruby
+class CreateCallParticipants < ActiveRecord::Migration[7.0]
+  def change
+    create_table :call_participants do |t|
+      t.bigint :call_id, null: false
+      t.bigint :user_id, null: false
+      t.string :role, null: false, default: 'active'
+      t.string :peer_id
+      t.datetime :joined_at
+      t.datetime :left_at
+      t.timestamps
+    end
+
+    add_index :call_participants, [:call_id, :user_id], unique: true
+    add_index :call_participants, :call_id
+    add_foreign_key :call_participants, :calls
+    add_foreign_key :call_participants, :users
+  end
+end
+```
+
+### Model Changes Summary
+
+| Model | Phase | Change |
+|-------|-------|--------|
+| `Call` | 1 | Add `media_session_id` attribute, `media_session_active?` method |
+| `Call` | 5 | Add `has_many :call_participants` and `has_many :participants` |
+| `CallParticipant` | 5 | New model with `belongs_to :call`, `belongs_to :user` |
+
+### Index Summary
+
+| Table | Index | Phase | Purpose |
+|-------|-------|-------|---------|
+| `calls` | `media_session_id` | 1 | Lookup call by media server session |
+| `call_participants` | `[call_id, user_id]` (unique) | 5 | Prevent duplicate join |
+| `call_participants` | `call_id` | 5 | List participants for a call |
+
+---
+
+## 7. Configuration & Environment Variables
+
+### Required (Phase 1)
+
+| Variable | Example | Description |
+|----------|---------|-------------|
+| `MEDIA_SERVER_URL` | `http://media:4000` | Internal URL where Rails reaches the Go media server |
+| `MEDIA_SERVER_AUTH_TOKEN` | `ms_secret_token_abc123` | Shared secret for mutual authentication |
+| `MEDIA_SERVER_PUBLIC_IP` | `203.0.113.50` | Public IP for ICE candidates in SDP offers to agents |
+
+### Required (Go Media Server)
+
+| Variable | Example | Description |
+|----------|---------|-------------|
+| `AUTH_TOKEN` | `ms_secret_token_abc123` | Must match `MEDIA_SERVER_AUTH_TOKEN` in Rails |
+| `RAILS_CALLBACK_URL` | `http://web:3000` | Internal URL for callbacks to Rails |
+| `RECORDINGS_DIR` | `/recordings` | Directory for recording files (Docker volume) |
+| `UDP_PORT_MIN` | `10000` | Lowest UDP port for WebRTC media |
+| `UDP_PORT_MAX` | `10100` | Highest UDP port for WebRTC media |
+| `PUBLIC_IP` | `203.0.113.50` | Public IP for ICE candidate generation |
+| `LOG_LEVEL` | `info` | Logging verbosity: debug, info, warn, error |
+
+### Optional
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MEDIA_SERVER_STUN_SERVERS` | `stun:stun.l.google.com:19302` | Comma-separated STUN server URLs |
+| `MEDIA_SERVER_TURN_SERVERS` | (none) | Comma-separated TURN server URLs |
+| `MEDIA_SERVER_TURN_USERNAME` | (none) | TURN server authentication username |
+| `MEDIA_SERVER_TURN_PASSWORD` | (none) | TURN server authentication password |
+| `RECONNECT_TIMEOUT_SECONDS` | `30` | How long to hold Peer A after Peer B disconnects |
+| `MAX_SESSION_DURATION_SECONDS` | `7200` | Maximum call duration before forced termination |
+| `MAX_SESSIONS_PER_ACCOUNT` | `10` | Concurrent call limit per account |
+| `HOLD_MUSIC_PATH` | `/audio/default_hold_music.ogg` | Path to default hold music file |
+
+### Self-Hosted Deployment Note
+
+Self-hosted users must ensure:
+
+1. **UDP ports are exposed.** The media server needs direct UDP access from the internet for both Meta's media servers (Peer A) and agent browsers (Peer B). Cloud load balancers that only support TCP will not work for the media path.
+2. **Public IP is configured.** The `MEDIA_SERVER_PUBLIC_IP` / `PUBLIC_IP` must be the IP address reachable from the internet. Without this, ICE candidates in SDP will contain private IPs and connections will fail.
+3. **TURN server is deployed** if UDP is blocked. A TURN relay (e.g., coturn) handles this scenario by relaying media over TCP/TLS. TURN adds latency but guarantees connectivity.
+
+---
+
+## 8. Risk Register
+
+### R1: Go Media Server as Single Point of Failure
+
+**Severity:** High | **Likelihood:** Medium | **Phase:** All
+
+**Description:** If the Go media server process crashes, all active calls drop immediately. Both Peer A (Meta) and Peer B (agent) connections are lost. There is no automatic recovery of in-progress calls.
+
+**Mitigation:**
+- Health checks with automatic container restart (Docker `restart: unless-stopped`)
+- Recording files on disk survive crashes (written in real-time, not buffered)
+- Rails detects media server failure via health check timeout and terminates orphaned calls
+- Startup recovery routine scans for orphaned recordings and reports them to Rails
+- Phase 2+ consideration: run multiple media server instances with session affinity
+
+**Residual risk:** Calls in progress at crash time are lost. Acceptable for initial deployment given low concurrent call volumes.
+
+### R2: Meta SDP Compatibility with Pion
+
+**Severity:** High | **Likelihood:** Low-Medium | **Phase:** 2
+
+**Description:** Meta's WebRTC implementation may produce SDP offers/answers with non-standard extensions or codec configurations that Pion cannot parse or negotiate. The current browser-based approach works because Chrome's WebRTC stack is highly tolerant of SDP variations.
+
+**Mitigation:**
+- Capture real Meta SDP offers/answers from the existing system for testing
+- Pion supports standard SDP; most compatibility issues are in video (not audio)
+- Build SDP logging and comparison tooling in the media server
+- Fallback: if Pion cannot negotiate, the feature flag allows instant rollback to browser-direct
+
+**Detection:** Integration test with captured real-world SDP from Meta.
+
+### R3: UDP Port Exposure for Self-Hosted Deployments
+
+**Severity:** Medium | **Likelihood:** High | **Phase:** 1
+
+**Description:** Many self-hosted Chatwoot deployments run behind cloud load balancers or reverse proxies that only support TCP. WebRTC requires UDP for media transport. Without UDP access, calls will fail to establish audio.
+
+**Mitigation:**
+- TURN server support as fallback (relay media over TCP/TLS)
+- Clear documentation on network requirements
+- `MEDIA_SERVER_PUBLIC_IP` configuration for NAT environments
+- Health check in Rails UI: test media server reachability from agent browser
+
+**Residual risk:** Self-hosted users in highly restrictive networks may need to deploy a TURN server, adding operational complexity.
+
+### R4: No Test Coverage on Existing Call Code
+
+**Severity:** Medium | **Likelihood:** High | **Phase:** All
+
+**Description:** The existing WhatsApp calling code on `feat/whatsapp-call` has no automated test coverage. The PR breakdown document lists testing strategies per PR, but no specs have been written. Modifying untested code increases regression risk.
+
+**Mitigation:**
+- Write integration specs for `IncomingCallService` and `CallService` before modifying them
+- Use WebMock to stub Meta API calls and media server HTTP calls
+- Add request specs for controller endpoints
+- Frontend: add unit tests for the Pinia store actions
+- Manual testing checklist for each phase (see Section 9)
+
+### R5: Recording Format Change Breaks Transcription
+
+**Severity:** Medium | **Likelihood:** Low | **Phase:** 3
+
+**Description:** The current recording format is `audio/webm;codecs=opus`. The new format is `audio/ogg;codecs=opus`. OpenAI's Whisper API accepts both formats, but the file extension and content type change may affect downstream processing.
+
+**Mitigation:**
+- Verify OpenAI Whisper accepts OGG/Opus files (documentation confirms this)
+- Test with a sample OGG recording before deploying
+- The `CallTranscriptionService` sends the file to OpenAI as a binary upload -- the content type header is what matters, not the extension
+
+### R6: Increased Latency in Audio Path
+
+**Severity:** Low | **Likelihood:** Low | **Phase:** 2
+
+**Description:** Audio now passes through an extra hop (media server). This adds 1-5ms of latency within the same datacenter. The human perception threshold for voice latency is approximately 40ms (one-way) before conversation becomes awkward.
+
+**Mitigation:**
+- Deploy media server on the same host/network as the Rails application
+- Monitor actual latency via WebRTC stats API in the browser
+- Pion's RTP forwarding is zero-copy within the process (no transcoding)
+
+**Residual risk:** Cross-region deployments (Rails in US, media server in EU) would add significant latency. Documentation should recommend co-location.
+
+### R7: Feature Flag Complexity During Migration
+
+**Severity:** Low | **Likelihood:** Medium | **Phase:** 2-4
+
+**Description:** Two feature flags will coexist: `whatsapp_call` (enables calling) and `whatsapp_call_server_media` (routes through media server). Both Rails services and frontend composables must check the flag and maintain two code paths during the transition.
+
+**Mitigation:**
+- Clear naming convention: all new-path code checks `whatsapp_call_server_media`
+- Both paths share the same controller actions (the flag determines internal routing)
+- Plan a cleanup phase (Phase 5 of the original PR breakdown becomes the cleanup phase after rollout)
+- Time-box the migration: legacy path removed within 4 weeks of full rollout
+
+### R8: Go Language Expertise
+
+**Severity:** Low | **Likelihood:** Medium | **Phase:** 1-2
+
+**Description:** The Chatwoot team primarily works in Ruby and JavaScript. The Go media server introduces a new language to the stack. Debugging, code review, and on-call support require Go knowledge.
+
+**Mitigation:**
+- The media server is small (~2000 lines of Go) and narrowly scoped
+- Pion has extensive documentation and examples
+- Structured logging makes troubleshooting possible without deep Go knowledge
+- The media server is stateless (no database, no persistent state) -- restart fixes most issues
+
+---
+
+## 9. Testing Strategy
+
+### Unit Tests
+
+#### Go Media Server
+
+| Component | Test Approach | Phase |
+|-----------|--------------|-------|
+| Session manager | Create/find/destroy sessions, verify thread safety | 2 |
+| SDP handling | Feed real Meta SDP offers, verify valid answers generated | 2 |
+| Audio bridge | Mock two peers, verify packets forwarded bidirectionally | 2 |
+| OGG recorder | Feed Opus frames, verify valid OGG file produced | 3 |
+| Reconnection | Simulate Peer B disconnect/reconnect, verify Peer A stays up | 4 |
+| Audio decoder | Decode sample MP3/OGG files, verify PCM output | 6 |
+
+Use Pion's `webrtc.NewAPI()` with `SettingEngine` for deterministic testing without real network.
+
+#### Rails
+
+| Component | Test Approach | Phase |
+|-----------|--------------|-------|
+| `MediaServerClient` | WebMock stubs for all media server endpoints | 1 |
+| `IncomingCallService` (new path) | Stub `MediaServerClient`, verify session created and SDP stored | 2 |
+| `CallService` (new path) | Stub `MediaServerClient`, verify accept flow without browser SDP | 2 |
+| `CallReconnectService` | Stub `MediaServerClient.agent_reconnect`, verify ActionCable broadcast | 4 |
+| `CallRecordingFetchJob` | Stub `MediaServerClient.download_recording`, verify ActiveStorage attachment | 3 |
+| Callbacks controller | Verify correct handling of `agent_disconnected`, `recording_ready` events | 2 |
+
+#### Frontend
+
+| Component | Test Approach | Phase |
+|-----------|--------------|-------|
+| Pinia store actions | Vitest: verify state transitions for `handleAgentOffer`, `setReconnecting` | 2 |
+| API client methods | Vitest: verify correct HTTP calls for new endpoints | 2 |
+| `useCallReconnection` | Vitest: mock API calls, verify reconnection flow | 4 |
+
+### Integration Tests
+
+| Scenario | Approach | Phase |
+|----------|----------|-------|
+| Full inbound call | Rails request spec: simulate webhook -> verify media server called -> verify ActionCable events | 2 |
+| Full outbound call | Rails request spec: POST initiate -> verify media server called -> simulate Meta webhook | 2 |
+| Recording fetch | Sidekiq spec: trigger job -> verify file downloaded and attached | 3 |
+| Reconnection flow | Rails request spec: GET active -> POST reconnect -> verify media server called | 4 |
+
+### Manual Testing Checklist
+
+#### Phase 2: Core Call Flow
+
+- [ ] **Inbound call happy path:** WhatsApp contact calls business number -> incoming call widget appears -> agent accepts -> two-way audio works -> agent hangs up -> call record updated
+- [ ] **Outbound call happy path:** Agent clicks phone icon -> contact's phone rings -> contact answers -> two-way audio works -> either side hangs up
+- [ ] **Multi-agent routing:** Two agents online -> both see incoming call -> first to accept wins -> other agent's widget dismisses
+- [ ] **Call rejection:** Agent rejects incoming call -> call marked as failed -> Meta notified
+- [ ] **Feature flag isolation:** Disable `whatsapp_call_server_media` -> calls use browser-direct path -> enable flag -> calls use media server path
+
+#### Phase 3: Recording
+
+- [ ] **Recording captured:** Complete a call -> recording appears in message bubble within 60s
+- [ ] **Recording quality:** Play the recording -> both sides are audible -> stereo separation works
+- [ ] **Transcription:** Recording triggers transcription job -> transcript appears in message bubble
+- [ ] **Browser crash:** Agent force-quits browser during call -> call continues via media server -> recording includes audio up to the point of browser crash
+
+#### Phase 4: Reconnection
+
+- [ ] **Page refresh:** Agent refreshes page during call -> dashboard shows "Reconnecting..." -> audio resumes within 3s -> call timer continues from correct duration
+- [ ] **Browser close and reopen:** Agent closes browser -> reopens Chatwoot within 30s -> active call detected -> reconnection succeeds
+- [ ] **Reconnect timeout:** Agent disconnects and does NOT reconnect within 30s -> call terminates -> customer hears disconnect tone -> Meta receives hangup
+- [ ] **Multiple refreshes:** Agent refreshes 5 times rapidly -> each reconnection succeeds -> single continuous recording
+
+#### Phase 5: Multi-Participant
+
+- [ ] **Supervisor listen:** Supervisor clicks "Join as listener" on active call -> hears both sides -> agent and customer are unaware
+- [ ] **Participant list:** Join UI shows connected participants and their roles in real time
+
+#### Phase 6: Audio Injection
+
+- [ ] **Hold music:** Agent disconnects (page close) -> customer hears hold music within 2s -> agent reconnects -> hold music stops -> normal audio resumes
+- [ ] **On-demand playback:** Agent triggers "Play message" -> customer hears the audio file -> agent audio resumes after file completes
+
+---
+
+## 10. Rollout Plan
+
+### Feature Flag Strategy
+
+Two flags control the rollout:
+
+| Flag | Purpose | Default |
+|------|---------|---------|
+| `whatsapp_call` | Enables WhatsApp calling (existing) | Off |
+| `whatsapp_call_server_media` | Routes calls through media server instead of browser-direct | Off |
+
+Both flags must be enabled for the new architecture to be used. If `whatsapp_call_server_media` is disabled, the system falls back to the browser-direct path (current behavior).
+
+### Rollout Phases
+
+**Stage 1: Internal testing (1 week)**
+- Enable both flags on the Chatwoot team's internal account
+- Conduct all manual testing checklist items
+- Monitor media server health, latency, and recording quality
+
+**Stage 2: Beta accounts (1-2 weeks)**
+- Enable `whatsapp_call_server_media` on 5-10 volunteer customer accounts
+- Monitor for regressions: call success rate, recording completeness, reconnection reliability
+- Gather feedback on audio quality and latency
+
+**Stage 3: General availability (1 week)**
+- Enable `whatsapp_call_server_media` for all accounts with `whatsapp_call` enabled
+- Monitor dashboards for 1 week
+
+**Stage 4: Legacy cleanup (1 week)**
+- Remove browser-direct WebRTC code path
+- Remove `upload_recording` endpoint
+- Remove `MediaRecorder` and `startCallRecording` from frontend
+- Remove `whatsapp_call_server_media` feature flag (server-media becomes the only path)
+- Remove `terminateCallOnUnload` function
+- Remove `fix_sdp_setup` method (the `actpass -> active` hack)
+
+### Rollback Procedure
+
+If issues are discovered after enabling `whatsapp_call_server_media`:
+
+1. Disable the `whatsapp_call_server_media` feature flag on affected accounts (instant, no deploy needed)
+2. All new calls will use the browser-direct path
+3. Active calls through the media server will continue until they end naturally
+4. No data migration needed -- the `media_session_id` column is additive
+
+### Monitoring
+
+Key metrics to track during rollout:
+
+| Metric | Source | Alert Threshold |
+|--------|--------|----------------|
+| Media server health | `/health` endpoint | 3 consecutive failures |
+| Call setup success rate | Rails logs (CallService errors) | Below 95% |
+| Average call setup time | Rails logs (webhook to audio bridged) | Above 5 seconds |
+| Recording fetch success rate | `CallRecordingFetchJob` success/failure | Below 98% |
+| Reconnection success rate | `CallReconnectService` success/failure | Below 90% |
+| Media server memory usage | Docker stats / Prometheus | Above 80% of limit |
+| Active session count | `/health` endpoint | Above 80% of capacity |
+| UDP port utilization | Media server metrics | Above 80% of range |
+
+---
+
+## Appendix A: Timeline Summary
+
+| Phase | Duration | Key Deliverable | Dependencies |
+|-------|----------|----------------|--------------|
+| 1: Foundation | 1 week | DB migration, MediaServerClient, Go scaffold with health endpoint | None |
+| 2: Core Call Flow | 2-3 weeks | End-to-end inbound + outbound calls through media server | Phase 1 |
+| 3: Recording | 1 week | Server-side recording, remove browser recording | Phase 2 |
+| 4: Reconnection | 1-2 weeks | Call persistence across page reload, automatic reconnect | Phase 2 |
+| 5: Multi-Participant | 2 weeks | Supervisor listen, participant management | Phase 2 |
+| 6: Audio Injection | 1-2 weeks | Hold music, on-demand audio playback | Phase 4 |
+| 7: AI Foundation | 1-2 weeks | Plugin interface, RTP tap, virtual peer | Phase 2 |
+| **Total** | **9-13 weeks** | **Full migration with all 6 requirements met** | |
+
+Phases 3, 4, 5, 6, and 7 can be parallelized after Phase 2 is complete. The critical path is: Phase 1 -> Phase 2 -> Phase 4 (reconnection is the primary motivation for the migration).
+
+**Minimum viable migration (R1 + R2 + R3):** Phases 1 + 2 + 3 + 4 = 5-7 weeks.
+
+---
+
+## Appendix B: File Inventory
+
+Complete list of files created or modified, grouped by component.
+
+### New Files
+
+| File | Phase | Component |
+|------|-------|-----------|
+| `db/migrate/YYYYMMDDHHMMSS_add_media_session_id_to_calls.rb` | 1 | Rails |
+| `enterprise/app/services/whatsapp/media_server_client.rb` | 1 | Rails |
+| `enterprise/app/services/whatsapp/call_reconnect_service.rb` | 4 | Rails |
+| `enterprise/app/services/whatsapp/call_participant_service.rb` | 5 | Rails |
+| `enterprise/app/services/whatsapp/call_ai_streaming_service.rb` | 7 | Rails |
+| `enterprise/app/jobs/whatsapp/call_recording_fetch_job.rb` | 3 | Rails |
+| `enterprise/app/controllers/api/internal/media_server/callbacks_controller.rb` | 2 | Rails |
+| `enterprise/app/models/call_participant.rb` | 5 | Rails |
+| `db/migrate/YYYYMMDDHHMMSS_create_call_participants.rb` | 5 | Rails |
+| `app/javascript/dashboard/composables/useCallReconnection.js` | 4 | Frontend |
+| `app/javascript/dashboard/components/widgets/WhatsappCallParticipants.vue` | 5 | Frontend |
+| `enterprise/media-server/main.go` | 1 | Go |
+| `enterprise/media-server/go.mod` | 1 | Go |
+| `enterprise/media-server/config/config.go` | 1 | Go |
+| `enterprise/media-server/api/handler.go` | 1 | Go |
+| `enterprise/media-server/api/middleware.go` | 1 | Go |
+| `enterprise/media-server/api/session_handler.go` | 2 | Go |
+| `enterprise/media-server/api/meta_sdp_handler.go` | 2 | Go |
+| `enterprise/media-server/api/agent_handler.go` | 2 | Go |
+| `enterprise/media-server/api/recording_handler.go` | 2 | Go |
+| `enterprise/media-server/api/audio_handler.go` | 6 | Go |
+| `enterprise/media-server/session/manager.go` | 2 | Go |
+| `enterprise/media-server/session/session.go` | 2 | Go |
+| `enterprise/media-server/session/peer.go` | 2 | Go |
+| `enterprise/media-server/session/bridge.go` | 2 | Go |
+| `enterprise/media-server/session/mixer.go` | 5 | Go |
+| `enterprise/media-server/session/virtual_peer.go` | 7 | Go |
+| `enterprise/media-server/recording/recorder.go` | 3 | Go |
+| `enterprise/media-server/recording/ogg_writer.go` | 3 | Go |
+| `enterprise/media-server/recording/cleanup.go` | 3 | Go |
+| `enterprise/media-server/callback/rails_client.go` | 2 | Go |
+| `enterprise/media-server/audio/decoder.go` | 6 | Go |
+| `enterprise/media-server/audio/encoder.go` | 6 | Go |
+| `enterprise/media-server/audio/injector.go` | 6 | Go |
+| `enterprise/media-server/plugin/consumer.go` | 7 | Go |
+| `enterprise/media-server/plugin/rtp_tap.go` | 7 | Go |
+| `enterprise/media-server/Dockerfile` | 1 | Go |
+
+### Modified Files
+
+| File | Phase | Change Summary |
+|------|-------|---------------|
+| `enterprise/app/models/call.rb` | 1, 5 | Add `media_session_id`, participant association |
+| `enterprise/app/services/whatsapp/incoming_call_service.rb` | 2 | Create media session instead of storing SDP for browser |
+| `enterprise/app/services/whatsapp/call_service.rb` | 2 | Accept without browser SDP, orchestrate Peer B setup |
+| `enterprise/app/controllers/api/v1/accounts/whatsapp_calls_controller.rb` | 2, 3, 4, 5, 6 | New actions, remove upload_recording |
+| `config/routes.rb` | 2, 4, 5 | New routes for agent_answer, reconnect, active, join, leave, callbacks |
+| `app/javascript/dashboard/composables/useWhatsappCallSession.js` | 2, 3, 4 | Remove recording, remove terminateCallOnUnload, add reconnection |
+| `app/javascript/dashboard/stores/whatsappCalls.js` | 2, 4 | Add reconnection state, handle agent_offer |
+| `app/javascript/dashboard/api/whatsappCalls.js` | 2, 3 | New methods, remove uploadRecording |
+| `app/javascript/dashboard/helper/actionCable.js` | 2, 4, 5 | New event handlers |
+| `app/javascript/dashboard/components/widgets/WhatsappCallWidget.vue` | 4 | Reconnection UI |
+| `app/javascript/dashboard/components/widgets/conversation/ConversationHeader.vue` | 2 | Remove browser SDP generation for outbound |
+| `docker-compose.yml` or `docker-compose.deploy.yaml` | 1 | Add media-server service |
+| `Procfile.dev` | 1 | Add media-server process |
diff --git a/docs/WHATSAPP_CALL_FEATURE_SPEC.md b/docs/WHATSAPP_CALL_FEATURE_SPEC.md
new file mode 100644
index 000000000..8f0fbcf52
--- /dev/null
+++ b/docs/WHATSAPP_CALL_FEATURE_SPEC.md
@@ -0,0 +1,272 @@
+# WhatsApp Calling — Feature Spec
+
+> **Edition:** Enterprise (Premium) | **Feature Flag:** `whatsapp_call` | **Branch:** `feat/whatsapp-call`
+
+## What is it?
+
+Agents can **receive and make voice calls** with WhatsApp contacts directly from the Chatwoot dashboard. Calls are browser-based (WebRTC) — no Twilio, no phone hardware, zero telephony cost.
+
+Calls are **automatically recorded** and **transcribed** (OpenAI Whisper), and appear inline in the conversation thread.
+
+---
+
+## How it works (30-second version)
+
+```
+                          SIGNALING                              AUDIO
+                     (who calls whom,                     (actual voice data)
+                      accept/reject)
+
+  ┌──────────┐    REST / Webhooks     ┌──────────────┐
+  │ WhatsApp │◄──────────────────────►│   Chatwoot   │
+  │ Contact  │                        │   Backend    │
+  └────┬─────┘                        └──────┬───────┘
+       │                                     │ ActionCable (WebSocket)
+       │                                     │
+       │      ┌────────────────┐      ┌──────▼───────┐
+       └─────►│  Meta Media    │◄════►│   Agent's    │
+              │  Servers       │ SRTP │   Browser    │
+              └────────────────┘      └──────────────┘
+
+  Key insight: Chatwoot backend handles signaling only.
+              Audio flows directly between browser and Meta.
+```
+
+---
+
+## Call lifecycle
+
+```
+  ┌─────────┐     ┌──────────┐     ┌────────┐     ┌────────────┐
+  │ RINGING │────►│ ACCEPTED │────►│ ENDED  │────►│ TRANSCRIBED│
+  └─────────┘     └──────────┘     └────────┘     └────────────┘
+       │
+       ├──► REJECTED
+       ├──► MISSED (30s timeout)
+       └──► FAILED
+```
+
+---
+
+## Inbound call flow
+
+```
+Customer dials business number
+        │
+        ▼
+Meta sends webhook ──► IncomingCallService
+                        ├── Find/create contact & conversation
+                        ├── Create Call record (status: ringing)
+                        ├── Create voice_call message
+                        └── Broadcast via ActionCable
+                                │
+                                ▼
+                    All agents see floating widget
+                    with Accept / Reject buttons
+                                │
+                      Agent clicks Accept
+                        ├── Browser requests mic (getUserMedia)
+                        ├── WebRTC peer connection created
+                        ├── SDP answer generated + sent to backend
+                        └── Backend relays to Meta API
+                                │
+                                ▼
+                    Audio flows (Meta servers ↔ Browser)
+                    Recording starts automatically
+                                │
+                      Call ends (either side hangs up)
+                        ├── Recording uploaded
+                        └── Transcription triggered (async)
+```
+
+## Outbound call flow
+
+```
+Agent clicks phone icon in conversation header
+        │
+        ▼
+Browser creates WebRTC offer ──► POST /whatsapp_calls/initiate
+                                        │
+                                 ┌──────┴──────┐
+                                 │             │
+                              Success      Error 138006
+                                 │         (no permission)
+                                 │             │
+                                 │      Send permission request
+                                 │      to customer via WhatsApp
+                                 │             │
+                                 │      Customer approves ──► retry call
+                                 │
+                          Customer's phone rings
+                                 │
+                          Meta webhook with SDP answer
+                                 │
+                          Audio connected + recording starts
+```
+
+## Call permission flow
+
+Meta requires customers to **opt-in** before a business can call them. If the customer hasn't opted in:
+
+1. Agent tries to call → Meta returns error `138006`
+2. Chatwoot auto-sends an interactive permission request to the customer
+3. Customer approves on WhatsApp
+4. Agent retries the call → succeeds
+5. Rate-limited: 1 permission request per 5 minutes per conversation
+
+---
+
+## UI touchpoints
+
+| Where | What |
+|-------|------|
+| **Conversation Header** | Phone icon to initiate outbound calls |
+| **Floating Widget** (bottom-right) | Incoming call notification (accept/reject), active call controls (mute/hangup/timer) |
+| **Message Bubble** (VoiceCall type) | Call status, duration, recording audio player, transcript (expandable), "answered by" agent |
+| **Inbox Settings** | Toggle to enable/disable calling per WhatsApp inbox |
+
+---
+
+## Data model
+
+```
+calls table
+├── account_id, inbox_id, conversation_id
+├── message_id, accepted_by_agent_id
+├── provider (enum: twilio=0, whatsapp=1)
+├── direction (enum: incoming=0, outgoing=1)
+├── status (ringing → accepted → ended)
+├── duration_seconds, end_reason
+├── meta (jsonb: SDP offer/answer, ICE servers)
+├── transcript (text)
+└── recording (ActiveStorage attachment)
+```
+
+Voice calls create messages with `content_type: 'voice_call'` containing call metadata in `content_attributes`.
+
+---
+
+## API endpoints
+
+**Base:** `POST /api/v1/accounts/:account_id/whatsapp_calls`
+
+| Endpoint | What it does |
+|----------|-------------|
+| `GET /:id` | Get call details (SDP offer, ICE servers, caller info) |
+| `POST /:id/accept` | Accept call with SDP answer |
+| `POST /:id/reject` | Reject incoming call |
+| `POST /:id/terminate` | End active call |
+| `POST /initiate` | Start outbound call with SDP offer |
+| `POST /:id/upload_recording` | Upload recorded audio blob |
+
+## ActionCable events
+
+| Event | When |
+|-------|------|
+| `whatsapp_call.incoming` | New inbound call (all agents receive) |
+| `whatsapp_call.accepted` | Call accepted (dismisses widget for other agents) |
+| `whatsapp_call.ended` | Call terminated |
+| `whatsapp_call.outbound_connected` | Outbound call answered by customer |
+| `whatsapp_call.permission_granted` | Customer approved call permission |
+
+---
+
+## Recording & transcription
+
+```
+Agent mic ──┐
+            ├──► AudioContext mixer ──► MediaRecorder ──► WebM blob
+Remote audio┘                                                │
+                                                       Upload to server
+                                                             │
+                                                    ActiveStorage attachment
+                                                             │
+                                              CallTranscriptionJob (async)
+                                                             │
+                                                   OpenAI Whisper API
+                                                    (whisper-1, temp 0.4)
+                                                             │
+                                                    Transcript stored on
+                                                    call + message bubble
+```
+
+**Requires:** `captain_integration` feature flag + OpenAI API key configured.
+
+---
+
+## Enterprise architecture
+
+All calling code lives under `enterprise/`. Integration with OSS via `prepend_mod_with`:
+
+```
+enterprise/app/
+├── controllers/api/v1/accounts/whatsapp_calls_controller.rb
+├── models/call.rb
+├── services/whatsapp/
+│   ├── call_service.rb              (accept/reject/terminate orchestration)
+│   ├── incoming_call_service.rb     (webhook processing)
+│   ├── call_message_builder.rb      (voice_call message creation)
+│   ├── call_permission_reply_service.rb
+│   ├── call_transcription_service.rb
+│   └── providers/whatsapp_cloud_call_methods.rb  (Meta API HTTP layer)
+└── jobs/
+    ├── whatsapp/call_transcription_job.rb
+    └── enterprise/webhooks/whatsapp_events_job.rb
+```
+
+**OSS changes (minimal):** `WhatsappEventsJob` gets a `prepend_mod_with` hook + `ActionCableListener` nil safety fix.
+
+---
+
+## Key technical details
+
+| Topic | Detail |
+|-------|--------|
+| **SDP fix** | Meta requires `a=setup:active` but WebRTC generates `a=setup:actpass` — rewritten server-side |
+| **ICE gathering** | 10s timeout, default STUN: `stun:stun.l.google.com:19302` |
+| **Module-scope WebRTC** | `RTCPeerConnection`/`MediaStream` stored outside Pinia (not serializable) |
+| **Multi-agent routing** | All agents see incoming call; first to accept wins, others get dismissed |
+| **Page unload** | Active calls terminated via `fetch({ keepalive: true })` on `beforeunload` |
+| **Recording format** | `audio/webm;codecs=opus`, chunked at 1s intervals |
+
+---
+
+## Limitations
+
+| Constraint | Why |
+|------------|-----|
+| Browser-only | WebRTC requires a browser — no mobile app or SIP phones |
+| No rejoin after refresh | P2P connection (unlike Twilio's conference model) |
+| Audio only | Meta API doesn't support video calling |
+| One call per agent | Single active call at a time |
+| Client-side recording | Lost if browser crashes mid-call |
+| No TURN server | May fail behind restrictive firewalls blocking UDP |
+| Customer opt-in needed | Outbound calls require Meta's permission flow |
+
+---
+
+## WhatsApp vs Twilio comparison
+
+| | WhatsApp Calling | Twilio Voice |
+|---|---|---|
+| **Model** | Peer-to-peer (browser ↔ Meta) | Conference (Twilio media server) |
+| **Cost** | Free | Per-minute billing |
+| **Rejoin** | Not possible | Yes (conference persists) |
+| **Recording** | Client-side (browser) | Server-side (Twilio) |
+| **Video** | Not supported | Possible |
+| **SIP phones** | Not supported | Supported |
+
+---
+
+## How to test
+
+1. Enable `whatsapp_call` feature flag on account
+2. Enable calling in WhatsApp Cloud inbox settings
+3. Test inbound: call the business WhatsApp number → widget appears → accept → audio flows
+4. Test outbound: click phone icon in conversation → customer answers → audio flows
+5. Verify: recording uploads, transcript appears in message bubble
+6. Verify: multiple agents see incoming call, first-to-accept wins
+
+---
+
+*See [PR Breakdown](./WHATSAPP_CALL_PR_BREAKDOWN.md) for the 9-PR implementation plan.*
diff --git a/docs/WHATSAPP_CALL_PR_BREAKDOWN.md b/docs/WHATSAPP_CALL_PR_BREAKDOWN.md
new file mode 100644
index 000000000..8f5dc1922
--- /dev/null
+++ b/docs/WHATSAPP_CALL_PR_BREAKDOWN.md
@@ -0,0 +1,347 @@
+# WhatsApp Calling — PR Breakdown Plan
+
+> **Branch:** `feat/whatsapp-call` → **Base:** `develop`
+> **Date:** 2026-04-14 (updated)
+> **Goal:** Split the monolithic feature branch into **8 backend + 1 frontend = 9 mergeable PRs**, each covering a single concept.
+
+---
+
+## Merge Order & Dependency Graph
+
+```
+BACKEND                                         FRONTEND
+
+PR-1: Call Model + Migration ✅ MERGED
+  │
+  ├── PR-2: Meta API Provider Methods
+  │     │
+  │     ├── PR-3: Inbound Webhook Pipeline
+  │     │     │
+  │     │     └── PR-4: Call Service +
+  │     │           Controller + Routes ──────► PR-9: All Frontend Changes
+  │     │                                       (API, Store, WebRTC, Widget,
+  │     └─────────────────────────────────►      Bubble, Outbound UI,
+  │                                              ActionCable, Settings,
+  ├── PR-5: Transcription Pipeline               Voice Guard, i18n, Feature Flag)
+  │
+  ├── PR-6: Feature Flag + Enterprise Gating
+  │
+  ├── PR-7: OSS Touchpoints (webhook job refactor + ActionCable fix)
+  │
+  └── PR-8: Inbox Calling Config (provider_config + serializer)
+```
+
+---
+
+## Backend PRs
+
+### PR-1: Call Model + Migration + Error Classes ✅ MERGED
+
+> **Status:** Merged via PR #14026 (`feat/voice-call-model` branch).
+
+**Files included:** `db/migrate/20260408170902_create_calls.rb`, `enterprise/app/models/call.rb`, association concerns, `enterprise/lib/whatsapp/call_errors.rb`, `config/features.yml` (whatsapp_call flag definition).
+
+**No action required — already in `develop`.**
+
+---
+
+### PR-2: Meta Cloud API Provider Methods
+
+**Concept:** Low-level HTTP methods that communicate with Meta's WhatsApp Cloud API v22.0 for voice calls. No business logic — just the raw API client layer.
+
+**Files:**
+
+| File | Action | Lines |
+|------|--------|-------|
+| `enterprise/app/services/whatsapp/providers/whatsapp_cloud_call_methods.rb` | NEW | ~85 |
+| `enterprise/app/services/enterprise/whatsapp/providers/whatsapp_cloud_service.rb` | MODIFY | +include |
+| `enterprise/app/services/enterprise/whatsapp/facebook_api_client.rb` | MODIFY | +`calls` to webhook fields |
+
+**Methods provided:**
+```
+pre_accept_call(call_id)           → 200 OK (keeps call alive for SDP exchange)
+accept_call(call_id, sdp_answer)   → 200 OK
+reject_call(call_id)               → 200 OK
+terminate_call(call_id)            → 200 OK
+initiate_call(to, sdp_offer)       → {call_id, sdp_answer, ice_servers}
+send_call_permission_request(to)   → 200 OK (interactive permission template)
+```
+
+**Dependencies:** PR-1 ✅ (merged).
+
+**Risk:** Low. Methods exist but are dormant until consumers ship.
+
+---
+
+### PR-3: Inbound Webhook Pipeline
+
+**Concept:** The complete server-side flow for processing incoming call webhooks from Meta: event routing → call creation → message building → ActionCable broadcasting.
+
+**Files:**
+
+| File | Action | Lines |
+|------|--------|-------|
+| `enterprise/app/services/whatsapp/incoming_call_service.rb` | NEW | ~211 |
+| `enterprise/app/services/whatsapp/call_message_builder.rb` | NEW | ~108 |
+| `enterprise/app/services/whatsapp/call_permission_reply_service.rb` | NEW | ~61 |
+| `enterprise/app/jobs/enterprise/webhooks/whatsapp_events_job.rb` | NEW | ~40 |
+
+**How it works:**
+1. Meta sends webhook with `calls` field → `WhatsappEventsJob` routes to `IncomingCallService`
+2. `IncomingCallService` creates/updates `Call` record based on event type (`connect` or `terminate`)
+3. `CallMessageBuilder` creates `voice_call` content-type messages in the conversation
+4. ActionCable broadcasts `whatsapp_call.incoming` / `whatsapp_call.ended` to the account channel
+5. For `call_permission_reply` interactive messages → `CallPermissionReplyService` handles opt-in
+
+**Key detail:** `IncomingCallService` does NOT call Meta's API — it only processes incoming data. No dependency on PR-2.
+
+**Dependencies:** PR-1 ✅ (merged), PR-7 (OSS touchpoints for `prepend_mod_with` hook).
+
+**Risk:** Medium. The webhook event routing (`prepend_mod_with` in the enterprise job) overrides `handle_message_events`. Must ensure `super` delegation doesn't break existing message processing.
+
+---
+
+### PR-4: Call Service + Controller + Routes
+
+**Concept:** The REST API surface for agent-driven call actions (accept, reject, terminate, initiate) and the service orchestrating those actions.
+
+**Files:**
+
+| File | Action | Lines |
+|------|--------|-------|
+| `enterprise/app/services/whatsapp/call_service.rb` | NEW | ~109 |
+| `enterprise/app/controllers/api/v1/accounts/whatsapp_calls_controller.rb` | NEW | ~142 |
+| `config/routes.rb` | MODIFY | +resources |
+| `enterprise/app/models/enterprise/conversation.rb` | MODIFY | +`allowed_keys?` for `call_status` |
+
+**Endpoints:**
+
+| Method | Path | Action | Description |
+|--------|------|--------|-------------|
+| GET | `/api/v1/accounts/:account_id/whatsapp_calls/:id` | show | Get call details (SDP offer, ICE servers) |
+| POST | `/api/v1/accounts/:account_id/whatsapp_calls/:id/accept` | accept | Accept with SDP answer |
+| POST | `/api/v1/accounts/:account_id/whatsapp_calls/:id/reject` | reject | Reject the call |
+| POST | `/api/v1/accounts/:account_id/whatsapp_calls/:id/terminate` | terminate | End active call |
+| POST | `/api/v1/accounts/:account_id/whatsapp_calls/initiate` | initiate | Start outbound call |
+| POST | `/api/v1/accounts/:account_id/whatsapp_calls/:id/upload_recording` | upload_recording | Upload recording blob |
+
+**CallService flow (accept):**
+```
+pre_accept_call → WebRTC SDP exchange → accept_call (with SDP fix: actpass→active) → update status → broadcast
+```
+
+**Dependencies:** PR-1 ✅ (merged), PR-2 (Meta API methods), PR-3 (CallMessageBuilder).
+
+**Risk:** Medium. The controller's `initiate` action handles the permission flow (error 138006 → `send_call_permission_request`). The `upload_recording` action enqueues `CallTranscriptionJob` (PR-5). If PR-5 hasn't merged, temporarily guard the enqueue.
+
+---
+
+### PR-5: Recording Upload + Transcription Pipeline
+
+**Concept:** Async transcription of call recordings using OpenAI Whisper.
+
+**Files:**
+
+| File | Action | Lines |
+|------|--------|-------|
+| `enterprise/app/services/whatsapp/call_transcription_service.rb` | NEW | ~82 |
+| `enterprise/app/jobs/whatsapp/call_transcription_job.rb` | NEW | ~15 |
+
+**Pipeline:**
+```
+Browser records audio (MediaRecorder) → upload_recording endpoint →
+ActiveStorage attachment → CallTranscriptionJob →
+CallTranscriptionService → OpenAI Whisper (whisper-1, temp 0.4) →
+call.transcript + message.content_attributes updated
+```
+
+**Gating:** Requires `captain_integration` feature flag + usage limits check. Inherits from `Llm::LegacyBaseOpenAiService`.
+
+**Error handling:** Retries on `ActiveStorage::FileNotFoundError`, discards on `Faraday::BadRequestError`.
+
+**Dependencies:** PR-1 ✅ (merged). Can merge before or with PR-4.
+
+**Risk:** Low. Fully async, failure-tolerant. No impact on call flow if transcription fails.
+
+---
+
+### PR-6: Feature Flag + Enterprise Gating
+
+**Concept:** Ensure the `whatsapp_call` feature flag is properly checked at all entry points.
+
+**What it covers:**
+- Controller: `ensure_whatsapp_call_enabled` before_action
+- IncomingCallService: `account.feature_enabled?('whatsapp_call')` check
+- CallPermissionReplyService: same check
+- Inbox-level toggle: `provider_config['calling_enabled']` on Channel::Whatsapp
+
+> **Note:** The feature flag definition in `config/features.yml` shipped with PR-1. This PR adds the runtime guard logic across services and controllers. May be bundled into PR-4 if too small standalone.
+
+---
+
+### PR-7: OSS Touchpoints
+
+**Concept:** Minimal changes to OSS (non-enterprise) files required for the calling feature to work.
+
+**Files:**
+
+| File | Action | Lines | Change |
+|------|--------|-------|--------|
+| `app/jobs/webhooks/whatsapp_events_job.rb` | MODIFY | ~10 | Add `prepend_mod_with` hook + extract `handle_message_events` |
+| `app/listeners/action_cable_listener.rb` | MODIFY | ~2 | Nil safety fix in `typing_event_listener_tokens` |
+
+**Why separate:** These are the only two OSS Ruby files modified. Keeping them in a dedicated PR makes review clear — reviewers can verify the `super` delegation path and ensure existing message processing isn't broken.
+
+> **Note:** The `handle_message_events` extraction from the webhook job also supports the `smb_message_echoes` feature (PR #13371). If that's already merged to `develop`, this extraction may already exist. Check before creating this PR.
+
+**Dependencies:** None. Should merge early (before PR-3 which depends on the `prepend_mod_with` hook).
+
+**Risk:** Low but critical to verify. The `super` call path must be tested to ensure non-call webhooks still process correctly.
+
+---
+
+### PR-8: Inbox Calling Config (provider_config + serializer)
+
+**Concept:** Backend support for the per-inbox `calling_enabled` toggle in `provider_config` for WhatsApp Cloud channels.
+
+**What it covers:**
+- Allow `calling_enabled` in strong params for Channel::Whatsapp updates
+- Expose `calling_enabled` in inbox serializer response
+- Ensure `provider_config` merge (not overwrite) when updating
+
+**Dependencies:** PR-1 ✅ (merged).
+
+**Risk:** Low. Purely additive config key — no behavior change if not set.
+
+---
+
+## Frontend PR
+
+### PR-9: All Frontend Changes (Combined)
+
+**Concept:** The complete frontend implementation — API client, store, WebRTC engine, UI widgets, ActionCable integration, message bubble enhancements, outbound calling, inbox settings toggle, voice helper guard, i18n, and feature flag registration.
+
+**Files:**
+
+| File | Action | Lines | Layer |
+|------|--------|-------|-------|
+| `app/javascript/dashboard/api/whatsappCalls.js` | NEW | ~43 | API client |
+| `app/javascript/dashboard/stores/whatsappCalls.js` | NEW | ~94 | State management |
+| `app/javascript/dashboard/featureFlags.js` | MODIFY | +2 | Feature flag |
+| `app/javascript/dashboard/i18n/locale/en/whatsappCall.json` | NEW | ~20 | i18n |
+| `app/javascript/dashboard/i18n/locale/en/index.js` | MODIFY | +1 | i18n |
+| `app/javascript/dashboard/helper/voice.js` | MODIFY | ~20 | Voice guard |
+| `app/javascript/dashboard/composables/useWhatsappCallSession.js` | NEW | ~406 | WebRTC engine |
+| `app/javascript/dashboard/helper/actionCable.js` | MODIFY | +5 handlers | Real-time events |
+| `app/javascript/dashboard/components/widgets/WhatsappCallWidget.vue` | NEW | ~216 | Call widget UI |
+| `app/javascript/dashboard/routes/dashboard/Dashboard.vue` | MODIFY | +import | Widget mount |
+| `app/javascript/dashboard/components-next/message/bubbles/VoiceCall.vue` | MODIFY | ~145 | Message bubble |
+| `app/javascript/dashboard/i18n/locale/en/conversation.json` | MODIFY | +6 keys | i18n |
+| `app/javascript/dashboard/components/widgets/conversation/ConversationHeader.vue` | MODIFY | ~130 | Outbound calling |
+| `app/javascript/dashboard/routes/dashboard/settings/inbox/settingsPage/ConfigurationPage.vue` | MODIFY | ~20 | Inbox settings |
+| `app/javascript/dashboard/i18n/locale/en/inboxMgmt.json` | MODIFY | +3 keys | i18n |
+
+**Key components:**
+
+1. **API Client** — `show`, `accept`, `reject`, `terminate`, `initiate`, `uploadRecording`
+2. **Pinia Store** — Module-scoped WebRTC objects (non-serializable) outside reactive state
+3. **WebRTC Composable** — `useWhatsappCallSession()`, `acceptWhatsappCallById()`, `startCallRecording()`
+4. **ActionCable Events** — `incoming`, `accepted`, `ended`, `outbound_connected`, `permission_granted`
+5. **Floating Widget** — Incoming/active call states with accept/reject/mute/hangup
+6. **VoiceCall Bubble** — Accept button, recording player, transcript toggle, "answered by" display
+7. **Outbound UI** — Phone icon in ConversationHeader, full WebRTC offer/answer flow
+8. **Inbox Toggle** — `calling_enabled` checkbox in WhatsApp Cloud inbox settings
+9. **Voice Guard** — Prevents WhatsApp call messages from triggering Twilio store
+
+**Backend prerequisites:** PR-4 (REST endpoints), PR-3 (ActionCable broadcasts), PR-8 (inbox config).
+
+**Risk:** ⚠️ HIGH — Largest PR. Review focus areas:
+- Duplicated ICE gathering logic in ConversationHeader vs composable
+- Missing `onUnmounted` cleanup for outbound calls in ConversationHeader
+- `console.log` left in ConversationHeader ICE state logging
+- Hardcoded STUN server with no backend-provided config
+- Recording mimeType `audio/webm;codecs=opus` with no browser feature detection
+- Bare string in ActionCable `onWhatsappCallPermissionGranted` (should use i18n)
+- Frontend feature flag declared but unused (gated server-side only)
+
+**Estimated size:** ~1,200 lines across 15 files.
+
+---
+
+## Recommended Merge Sequence
+
+### Phase 1: Foundation (Week 1)
+
+| Order | PR | Type | Depends On | Est. Size |
+|-------|-----|------|------------|-----------|
+| — | **PR-1:** Call Model + Migration | Backend | None | ✅ MERGED |
+| 1 | **PR-7:** OSS Touchpoints | Backend | None | ~12 lines |
+| 2 | **PR-8:** Inbox Calling Config | Backend | PR-1 ✅ | ~30 lines |
+
+### Phase 2: Backend Services (Week 1-2)
+
+| Order | PR | Type | Depends On | Est. Size |
+|-------|-----|------|------------|-----------|
+| 3 | **PR-2:** Meta API Provider Methods | Backend | PR-1 ✅ | ~90 lines |
+| 4 | **PR-3:** Inbound Webhook Pipeline | Backend | PR-1 ✅, PR-7 | ~420 lines |
+| 5 | **PR-5:** Transcription Pipeline | Backend | PR-1 ✅ | ~97 lines |
+| 6 | **PR-6:** Feature Flag Gating | Backend | PR-1 ✅ | ~20 lines |
+
+### Phase 3: Backend API + Frontend (Week 2-3)
+
+| Order | PR | Type | Depends On | Est. Size |
+|-------|-----|------|------------|-----------|
+| 7 | **PR-4:** Call Service + Controller + Routes | Backend | PR-2, PR-3, PR-5 | ~260 lines |
+| 8 | **PR-9:** All Frontend Changes | Frontend | PR-4, PR-3, PR-8 | ~1,200 lines |
+
+---
+
+## Parallel Merge Opportunities
+
+These PRs have no dependencies on each other and can be reviewed/merged in parallel:
+
+- **PR-7, PR-8** — independent foundation PRs
+- **PR-2, PR-3, PR-5, PR-6** — all depend only on PR-1 (merged) and/or PR-7
+
+---
+
+## Issues Found During Analysis
+
+| # | Issue | Severity | PR Affected |
+|---|-------|----------|-------------|
+| 1 | **Duplicated ICE gathering logic** — `waitForOutboundIceGathering` in ConversationHeader vs `waitForIceGatheringComplete` in composable | Medium | PR-9 |
+| 2 | **No `onUnmounted` cleanup** for outbound calls in ConversationHeader | Medium | PR-9 |
+| 3 | **Feature flag unused on frontend** — `FEATURE_FLAGS.WHATSAPP_CALL` declared but no component checks it | Low | PR-9 |
+| 4 | **Bare string in ActionCable** — `onWhatsappCallPermissionGranted` uses template literal instead of i18n key | Low | PR-9 |
+| 5 | **Hardcoded STUN server** — `stun:stun.l.google.com:19302` with no backend-provided config | Low | PR-9 |
+| 6 | **Recording mimeType assumption** — `audio/webm;codecs=opus` with no browser feature detection | Low | PR-9 |
+| 7 | **`console.log` left in** — ICE state logging in ConversationHeader | Low | PR-9 |
+
+---
+
+## Cherry-Pick Strategy
+
+Since the branch has ~270+ commits (including develop merges), cherry-picking individual commits won't work cleanly. Instead:
+
+1. **For each PR**, create a new branch from `develop`
+2. **Copy the specific files** from `feat/whatsapp-call` using:
+   ```bash
+   git checkout feat/whatsapp-call -- path/to/file1 path/to/file2
+   ```
+3. **For modified files** (routes.rb, actionCable.js, etc.), manually apply only the relevant diff hunks
+4. **Run tests** for each PR independently before opening
+
+---
+
+## Testing Checklist Per PR
+
+| PR | Test Strategy |
+|----|---------------|
+| PR-2 | Unit test Meta API methods with WebMock/VCR stubs |
+| PR-3 | Integration test: simulate Meta webhook payload → verify Call record + message created |
+| PR-4 | Request specs: hit each endpoint, verify response + side effects |
+| PR-5 | Unit test: mock OpenAI API, verify transcript stored on call + message |
+| PR-6 | Verify feature flag gating blocks unauthorized accounts |
+| PR-7 | Verify existing WhatsApp message webhook processing still works |
+| PR-8 | Verify inbox serializer includes `calling_enabled` |
+| PR-9 | `pnpm test` on store + manual E2E: inbound call, outbound call, recording, settings toggle |
diff --git a/docs/WHATSAPP_CALL_SERVER_RELAY_ARCHITECTURE.md b/docs/WHATSAPP_CALL_SERVER_RELAY_ARCHITECTURE.md
new file mode 100644
index 000000000..2a5744a38
--- /dev/null
+++ b/docs/WHATSAPP_CALL_SERVER_RELAY_ARCHITECTURE.md
@@ -0,0 +1,694 @@
+# Frontend Architecture: Server-Side WebRTC WhatsApp Calling
+
+> Design document for migrating WhatsApp calling from browser-side WebRTC to server-side WebRTC with browser audio relay.
+
+---
+
+## 1. Architecture Overview
+
+### Current model (being replaced)
+
+```
+Agent Browser                    Meta Media Servers
+┌─────────────────────┐          ┌──────────────┐
+│  RTCPeerConnection  │◄═══════►│  SRTP Audio   │
+│  SDP offer/answer   │  direct  │              │
+│  ICE candidates     │  media   │              │
+│  MediaRecorder      │          │              │
+│  AudioContext mixer  │          │              │
+└─────────────────────┘          └──────────────┘
+         ▲
+         │ ActionCable (signaling only)
+         ▼
+┌─────────────────────┐
+│  Chatwoot Backend   │
+│  (relay SDP/ICE)    │
+└─────────────────────┘
+```
+
+### New model
+
+```
+Agent Browser                    Chatwoot Backend                Meta Media Servers
+┌──────────────────┐     WS      ┌─────────────────┐   SRTP    ┌──────────────┐
+│  getUserMedia()  │────────────►│  Audio Ingest    │          │              │
+│  (mic capture)   │  agent mic  │                 │          │              │
+│                  │             │  RTCPeerConn    │◄════════►│  Media       │
+│  AudioContext    │◄────────────│  SDP/ICE        │  direct  │  Servers     │
+│  (playback)     │  remote     │  MediaRecorder  │  media   │              │
+│                  │  audio      │  (server-side)  │          │              │
+│  UI Controls    │             │                 │          │              │
+│  (mute/hangup)  │◄───────────►│  ActionCable    │          │              │
+│                  │  signaling  │  (call events)  │          │              │
+└──────────────────┘             └─────────────────┘          └──────────────┘
+```
+
+Key changes:
+- **WebRTC lives on the server.** The backend holds the RTCPeerConnection to Meta.
+- **Browser sends mic audio** to the server over a dedicated binary WebSocket.
+- **Server relays remote audio** back to the browser over the same WebSocket.
+- **Recording is server-side.** No client-side MediaRecorder, no upload step.
+- **Page reload does not kill the call.** The server-side connection persists; the browser just reconnects its audio stream.
+
+---
+
+## 2. Recommended Audio Relay Mechanism
+
+### Evaluation of options
+
+| Mechanism | Latency | Complexity | Browser Support | Reconnection | Verdict |
+|-----------|---------|-----------|----------------|--------------|---------|
+| **Dedicated binary WebSocket** | 20-50ms | Low | Universal | Trivial (new WS) | **Recommended** |
+| Secondary WebRTC (browser to server) | 5-20ms | High | Universal | Hard (new SDP) | Over-engineered |
+| WebTransport | 5-15ms | Medium | Chrome/Edge only | Medium | Not ready |
+| ActionCable binary frames | 30-80ms | Low | Universal | Free (existing) | Too slow, not designed for media |
+
+### Recommendation: Dedicated binary WebSocket
+
+**Why not reuse ActionCable?** ActionCable is JSON-framed, multiplexed, and adds overhead for binary payloads. Audio needs a dedicated low-latency binary channel with no framing overhead.
+
+**Why not a second WebRTC connection?** The entire point of this migration is to remove WebRTC complexity from the browser. Adding a browser-to-server WebRTC leg reintroduces SDP negotiation, ICE gathering, and DTLS setup -- the exact things we are eliminating.
+
+**Why not WebTransport?** Firefox and Safari do not yet have stable support. The latency improvement over WebSocket (5-15ms vs 20-50ms) does not justify excluding a third of agents.
+
+### Audio relay protocol design
+
+```
+Dedicated WebSocket: wss://{host}/cable/audio?call_id={id}&token={jwt}
+
+Frame format (binary):
+┌──────────┬──────────┬─────────────────────────┐
+│ type (1B)│ seq (2B) │ payload (variable)       │
+├──────────┼──────────┼─────────────────────────┤
+│ 0x01     │ uint16   │ Opus frame (agent mic)  │  browser → server
+│ 0x02     │ uint16   │ Opus frame (remote)     │  server → browser
+│ 0x03     │ -        │ JSON control message    │  bidirectional
+└──────────┴──────────┴─────────────────────────┘
+
+Audio encoding:
+- Codec: Opus (native to WebRTC, supported by AudioEncoder API)
+- Sample rate: 48kHz mono (Opus default)
+- Frame duration: 20ms (960 samples per frame)
+- Bitrate: 24-32 kbps (speech-optimized)
+- Frames per WebSocket message: 1 (20ms per message = 50 messages/sec)
+
+Control messages (type 0x03):
+- { "action": "mute" }
+- { "action": "unmute" }
+- { "action": "heartbeat" }
+- { "action": "reconnected", "resumeFrom": seq }
+```
+
+**Why Opus?** It is the codec Meta uses for WhatsApp call audio. The server receives Opus from Meta's SRTP stream and can forward it directly to the browser without transcoding. The browser can also encode mic input as Opus using the WebCodecs `AudioEncoder` API (Chrome 94+, Firefox 130+, Safari 16.4+).
+
+**Fallback for older browsers:** If `AudioEncoder` is unavailable, fall back to sending raw PCM Int16 at 16kHz (32 KB/s). The server transcodes to Opus before injecting into the WebRTC session.
+
+---
+
+## 3. Component Tree
+
+```
+App.vue
+└── DashboardLayout.vue
+    ├── ConversationHeader.vue
+    │   └── [phone icon button] ──► calls store.initiateCall()
+    │
+    ├── MessageBubble (VoiceCall.vue)
+    │   └── [accept/join button] ──► calls store.acceptCall()
+    │
+    └── CallWidget.vue  (fixed position, bottom-right)
+        ├── IncomingCallCard.vue  (for each ringing call)
+        │   ├── Avatar + caller info
+        │   ├── Accept button ──► calls store.acceptCall()
+        │   └── Reject button ──► calls store.rejectCall()
+        │
+        ├── ActiveCallCard.vue  (single active call)
+        │   ├── Avatar + caller info
+        │   ├── Duration timer (formattedDuration from store)
+        │   ├── Mute toggle ──► calls store.toggleMute()
+        │   ├── Hangup button ──► calls store.endCall()
+        │   └── ReconnectingBanner.vue  (shown during audio reconnection)
+        │
+        └── CallErrorBanner.vue
+```
+
+### What changed vs current
+- **Removed:** No WebRTC logic in any component. Components are now pure UI.
+- **Simplified:** ConversationHeader no longer creates RTCPeerConnection or manages SDP. It calls a single store action.
+- **Added:** `ReconnectingBanner` sub-component for the reconnection state.
+- **Same:** WhatsappCallWidget stays as the floating overlay. VoiceCall.vue bubble stays as the message thread display.
+
+---
+
+## 4. Composable Design
+
+The current monolithic `useWhatsappCallSession.js` (406 lines) is split into three focused composables:
+
+### 4a. `useCallAudioStream.js` -- audio capture and playback
+
+This composable owns the dedicated WebSocket, mic capture, and audio playback. It has zero knowledge of call signaling or UI state.
+
+```
+Module-level state (singleton, survives component remounts):
+- audioSocket: WebSocket | null
+- audioContext: AudioContext | null
+- micStream: MediaStream | null
+- audioEncoder: AudioEncoder | null  (WebCodecs)
+- playbackNode: AudioWorkletNode | null
+- sequenceNumber: number
+- isConnected: ref(false)
+- isCapturing: ref(false)
+
+Exported function: useCallAudioStream()
+
+Returns:
+  // State
+  isAudioConnected: Ref<boolean>
+  isCapturing: Ref<boolean>
+  isReconnecting: Ref<boolean>
+  audioLevel: Ref<number>          // 0-1, for visual feedback
+
+  // Actions
+  connect(callId: string): Promise<void>
+    1. Open WS to /cable/audio?call_id={callId}&token={jwt}
+    2. Create AudioContext (48kHz)
+    3. getUserMedia({ audio: true })
+    4. Pipe mic → AudioWorkletNode (capture processor) → AudioEncoder → WS send
+    5. Register WS.onmessage handler: decode Opus frames → playback buffer
+    6. Start playback via AudioWorkletNode (playback processor)
+
+  disconnect(): void
+    1. Close WS
+    2. Stop mic tracks
+    3. Close AudioContext
+    4. Reset all state
+
+  setMuted(muted: boolean): void
+    1. If muted: stop sending mic frames (but keep mic open for fast unmute)
+    2. If unmuted: resume sending
+    // No server round-trip needed. Simply stop emitting frames.
+
+  reconnect(callId: string): Promise<void>
+    1. Disconnect existing
+    2. Connect fresh (server already has the call)
+    3. Resume audio from current server buffer position
+```
+
+**AudioWorklet processors** (two small files):
+
+`mic-capture-processor.js` -- runs on the audio thread:
+```js
+// Receives Float32 PCM from getUserMedia
+// Posts ArrayBuffer to main thread for encoding
+class MicCaptureProcessor extends AudioWorkletProcessor {
+  process(inputs) {
+    const input = inputs[0][0]; // mono channel
+    if (input) {
+      this.port.postMessage(input.buffer, [input.buffer]);
+    }
+    return true;
+  }
+}
+registerProcessor('mic-capture', MicCaptureProcessor);
+```
+
+`audio-playback-processor.js` -- runs on the audio thread:
+```js
+// Receives decoded PCM buffers via port.postMessage
+// Writes them into output for playback
+// Maintains a small jitter buffer (60-100ms)
+class AudioPlaybackProcessor extends AudioWorkletProcessor {
+  constructor() {
+    super();
+    this.buffer = []; // ring buffer of Float32Arrays
+    this.port.onmessage = (e) => this.buffer.push(e.data);
+  }
+  process(outputs) {
+    const output = outputs[0][0];
+    if (this.buffer.length > 0) {
+      const frame = this.buffer.shift();
+      output.set(frame.subarray(0, output.length));
+    }
+    return true;
+  }
+}
+registerProcessor('audio-playback', AudioPlaybackProcessor);
+```
+
+### 4b. `useCallSession.js` -- call lifecycle and UI state
+
+This replaces the current `useWhatsappCallSession.js`. It orchestrates call signaling (via REST API) and delegates audio to `useCallAudioStream`. No WebRTC code.
+
+```
+Exported function: useCallSession()
+
+Internally uses:
+  - useWhatsappCallsStore() (Pinia)
+  - useCallAudioStream()
+  - Timer helper
+
+Returns:
+  // Read-only state (delegated from store)
+  activeCall: ComputedRef<CallData | null>
+  incomingCalls: ComputedRef<CallData[]>
+  hasActiveCall: ComputedRef<boolean>
+  hasIncomingCall: ComputedRef<boolean>
+  firstIncomingCall: ComputedRef<CallData | null>
+  isOutboundRinging: ComputedRef<boolean>
+
+  // Session state
+  isAccepting: Ref<boolean>
+  isMuted: Ref<boolean>
+  isReconnecting: Ref<boolean>       // NEW: true during page-reload rejoin
+  callError: Ref<string | null>
+  formattedCallDuration: ComputedRef<string>
+
+  // Actions
+  acceptCall(call): Promise<void>
+    1. POST /whatsapp_calls/:id/accept  (NO SDP -- server handles WebRTC)
+    2. store.setActiveCall(call)
+    3. audioStream.connect(call.id)
+    4. timer.start()
+
+  rejectCall(call): Promise<void>
+    1. POST /whatsapp_calls/:id/reject
+    2. store.removeIncomingCall(call.callId)
+
+  endCall(): Promise<void>
+    1. audioStream.disconnect()
+    2. POST /whatsapp_calls/:id/terminate
+    3. store.clearActiveCall()
+    4. timer.stop()
+
+  toggleMute(): void
+    1. audioStream.setMuted(!isMuted.value)
+    2. isMuted.value = !isMuted.value
+
+  initiateCall(conversationId): Promise<void>   // NEW: moved from ConversationHeader
+    1. POST /whatsapp_calls/initiate  (NO SDP offer -- server creates its own)
+    2. store.setActiveCall({ status: 'ringing', direction: 'outbound', ... })
+    3. Wait for ActionCable 'whatsapp_call.outbound_connected' event
+    4. audioStream.connect(call.id)
+    5. timer.start()
+
+  rejoinCall(callId): Promise<void>             // NEW: reconnection after page reload
+    1. GET /whatsapp_calls/:id  → verify status is 'accepted' or 'in_progress'
+    2. store.setActiveCall(callData)
+    3. audioStream.connect(callId)
+    4. Fetch elapsed duration from server to resume timer
+
+  dismissIncomingCall(call): void
+    1. store.removeIncomingCall(call.callId)
+```
+
+### 4c. `useCallReconnection.js` -- handles page reload during active call
+
+```
+Exported function: useCallReconnection()
+
+Logic (runs on mount):
+  1. On app startup, check: GET /whatsapp_calls/active
+     - New API endpoint that returns the agent's current active call (if any)
+  2. If an active call exists:
+     - Set isReconnecting = true
+     - Call callSession.rejoinCall(callId)
+     - Set isReconnecting = false
+  3. Register visibility change listener:
+     - On document becoming visible after being hidden, verify audio WS is healthy
+     - If WS is closed, trigger reconnect
+```
+
+---
+
+## 5. Pinia Store Schema
+
+The store becomes drastically simpler. All non-serializable objects (RTCPeerConnection, MediaStream, AudioContext) move out of the store entirely -- they live in `useCallAudioStream` at module scope.
+
+### New store: `stores/whatsappCalls.js`
+
+```js
+// NO module-scoped WebRTC objects. No outboundCall state.
+// The store is now purely serializable call metadata.
+
+defineStore('whatsappCalls', {
+  state: () => ({
+    incomingCalls: [],       // CallData[]
+    activeCall: null,        // CallData | null
+    callTimerOffset: 0,      // seconds already elapsed (for reconnection)
+  }),
+
+  getters: {
+    hasIncomingCall: (state) => state.incomingCalls.length > 0,
+    hasActiveCall: (state) => state.activeCall !== null,
+    hasWhatsappCall: (state) => state.incomingCalls.length > 0 || state.activeCall !== null,
+    firstIncomingCall: (state) => state.incomingCalls[0] || null,
+  },
+
+  actions: {
+    addIncomingCall(callData) { ... },
+    removeIncomingCall(callId) { ... },
+    setActiveCall(callData) { ... },
+    clearActiveCall() { ... },
+    markActiveCallConnected() { ... },
+    handleCallAcceptedByOther(callId) { ... },
+    handleCallEnded(callId) { ... },
+    setTimerOffset(seconds) { this.callTimerOffset = seconds; },
+  },
+});
+```
+
+### CallData type definition
+
+```ts
+interface CallData {
+  id: number;                    // server-side Call record ID
+  callId: string;                // Meta's call_id
+  direction: 'inbound' | 'outbound';
+  status: 'ringing' | 'connected' | 'reconnecting';
+  inboxId: number;
+  conversationId: number;
+  caller: {
+    name?: string;
+    phone?: string;
+    avatar?: string;
+  };
+  // REMOVED: sdpOffer, iceServers -- no longer sent to browser
+}
+```
+
+### What was removed from the store
+
+| Old | New | Why |
+|-----|-----|-----|
+| `outboundCall` (module-scoped `{ pc, stream, audio, callId }`) | Gone | No WebRTC objects in browser |
+| `getOutboundCallState()` | Gone | No peer connection to query |
+| `setOutboundCallProperty()` | Gone | No peer connection to mutate |
+| `cleanupOutboundCall()` | Gone | Audio cleanup is in `useCallAudioStream.disconnect()` |
+| `cleanupCallback` | Gone | No need for cross-concern cleanup registration |
+| `registerCleanupCallback()` | Gone | Store actions directly call composable |
+
+### What was added
+
+| New | Why |
+|-----|-----|
+| `callTimerOffset` | When reconnecting after page reload, the server tells us how many seconds the call has been active. The timer starts from this offset instead of 0. |
+
+---
+
+## 6. Reconnection Flow
+
+This is the primary benefit of the server-side architecture. The server's WebRTC connection to Meta persists across browser page loads.
+
+### Scenario: Agent refreshes page during active call
+
+```
+Timeline:
+─────────────────────────────────────────────────────────────────►
+
+1. Agent is on an active call (audio flowing)
+
+2. Agent hits F5 (page reload)
+   ├── beforeunload fires
+   │   └── Audio WS closes (but we do NOT terminate the call)
+   │       Unlike current code which calls terminateCallOnUnload()
+   ├── Server detects WS disconnect
+   │   └── Server continues holding the Meta WebRTC session
+   │   └── Server buffers incoming remote audio (or drops it, brief gap is OK)
+   └── Browser unloads
+
+3. Page reloads, Vue app mounts
+   ├── useCallReconnection() runs on mount
+   │   └── GET /whatsapp_calls/active
+   │       Response: { id: 42, call_id: "abc", status: "accepted",
+   │                   direction: "inbound", elapsed_seconds: 47, ... }
+   │
+   ├── Store updated: setActiveCall(callData)
+   │   UI immediately shows CallWidget with "Reconnecting..." banner
+   │
+   ├── callSession.rejoinCall(42)
+   │   ├── audioStream.connect(42)
+   │   │   ├── New WS to /cable/audio?call_id=42
+   │   │   ├── getUserMedia() -- browser may re-prompt for mic
+   │   │   ├── AudioContext + worklets initialized
+   │   │   └── Audio flowing again
+   │   │
+   │   └── Timer resumes from elapsed_seconds (47)
+   │       formattedCallDuration shows "00:47" and counting
+   │
+   └── ReconnectingBanner disappears, ActiveCallCard shows normally
+
+4. Call continues as if nothing happened
+   Total audio gap: ~2-4 seconds (page load time)
+```
+
+### Scenario: Network blip (WebSocket drops briefly)
+
+```
+1. Audio WS disconnects unexpectedly
+
+2. useCallAudioStream detects WS close
+   ├── isReconnecting = true
+   ├── UI shows "Reconnecting..." in ActiveCallCard
+   └── Start reconnection with exponential backoff:
+       attempt 1: wait 500ms → try WS connect
+       attempt 2: wait 1000ms → try WS connect
+       attempt 3: wait 2000ms → try WS connect
+       max 5 attempts, then show error
+
+3. WS reconnects
+   ├── isReconnecting = false
+   ├── Audio resumes
+   └── UI returns to normal
+
+4. If all 5 attempts fail:
+   ├── Show error: "Audio connection lost. Call is still active on server."
+   └── Offer "Reconnect" button that retries
+```
+
+### Scenario: Agent opens a second tab
+
+```
+1. Call is active in Tab A
+
+2. Agent opens Tab B (or navigates to Chatwoot in new tab)
+   ├── useCallReconnection() runs
+   │   └── GET /whatsapp_calls/active → returns active call
+   │
+   ├── Two options (backend decides):
+   │   a) TRANSFER audio to new tab: Server closes Tab A's audio WS,
+   │      Tab B becomes the audio source. Tab A shows "Call moved to another tab."
+   │   b) BLOCK: Return { active: true, owned_by_other_session: true }
+   │      Tab B shows the call widget in "view only" mode (timer, no controls)
+   │
+   └── Recommendation: Option (a) -- transfer. Matches user intent
+       (they probably want to continue in the new tab).
+```
+
+---
+
+## 7. File Structure
+
+### Files to create (new)
+
+```
+app/javascript/dashboard/
+├── composables/
+│   ├── useCallAudioStream.js          # Audio capture, WS relay, playback
+│   ├── useCallSession.js              # Call lifecycle (accept/reject/end/initiate)
+│   └── useCallReconnection.js         # Page-reload reconnection logic
+│
+├── workers/
+│   ├── mic-capture-processor.js       # AudioWorklet: mic → main thread
+│   └── audio-playback-processor.js    # AudioWorklet: main thread → speaker
+│
+└── helpers/
+    └── callAudioCodec.js              # WebCodecs Opus encode/decode helpers
+```
+
+### Files to modify
+
+```
+app/javascript/dashboard/
+├── composables/
+│   └── useWhatsappCallSession.js      # DELETE entirely (replaced by useCallSession.js)
+│
+├── stores/
+│   └── whatsappCalls.js               # Simplify: remove all WebRTC state/helpers
+│
+├── api/
+│   └── whatsappCalls.js               # Modify: remove SDP params, add active() endpoint
+│
+├── helper/
+│   └── actionCable.js                 # Modify: simplify event handlers (no SDP relay)
+│
+├── components/widgets/
+│   ├── WhatsappCallWidget.vue         # Minor: use new composable, add reconnection UI
+│   └── conversation/
+│       └── ConversationHeader.vue     # Major simplification: remove all WebRTC code
+│
+└── components-next/message/bubbles/
+    └── VoiceCall.vue                  # Minor: acceptWhatsappCallById → store action
+```
+
+### Files to delete
+
+```
+(none explicitly deleted as files, but the following become unnecessary
+ and their content is removed or replaced:)
+
+- All RTCPeerConnection code in useWhatsappCallSession.js → replaced
+- All SDP/ICE code in ConversationHeader.vue → replaced
+- startCallRecording / stopAndUploadRecording → gone (server-side recording)
+- terminateCallOnUnload → replaced with "do nothing" (call persists)
+```
+
+---
+
+## 8. API Changes Required
+
+The REST API needs small changes to support the new model:
+
+### Modified endpoints
+
+| Endpoint | Old | New |
+|----------|-----|-----|
+| `POST /:id/accept` | Sends `{ sdp_answer }` | Sends `{}` (no SDP, server handles it) |
+| `POST /initiate` | Sends `{ conversation_id, sdp_offer }` | Sends `{ conversation_id }` (no SDP) |
+| `POST /:id/upload_recording` | Browser uploads webm blob | **Removed** -- server records directly |
+
+### New endpoints
+
+| Endpoint | Purpose |
+|----------|---------|
+| `GET /whatsapp_calls/active` | Returns the current agent's active call (if any). Used for reconnection on page load. Returns `null` if no active call. |
+| `WS /cable/audio?call_id={id}&token={jwt}` | Dedicated binary WebSocket for audio relay. Separate from ActionCable. |
+
+### Modified ActionCable events
+
+| Event | Old payload | New payload |
+|-------|-------------|-------------|
+| `whatsapp_call.incoming` | `{ ..., sdp_offer, ice_servers }` | `{ ..., }` (no SDP/ICE -- browser does not need them) |
+| `whatsapp_call.outbound_connected` | `{ call_id, sdp_answer }` | `{ call_id }` (no SDP -- just signals "ready for audio WS") |
+
+---
+
+## 9. ActionCable Handler Changes
+
+The `actionCable.js` handlers simplify significantly:
+
+```
+Current handlers (what changes):
+
+onWhatsappCallIncoming:
+  OLD: Store sdpOffer + iceServers in incoming call data
+  NEW: Store only metadata (id, callId, direction, caller, conversationId)
+       No sdpOffer, no iceServers
+
+onWhatsappCallAccepted:
+  OLD: Same
+  NEW: Same (no change -- purely a signaling event)
+
+onWhatsappCallEnded:
+  OLD: Calls store.handleCallEnded which triggers cleanupCallback (WebRTC teardown)
+  NEW: Calls store.handleCallEnded which is now just state cleanup
+       Audio cleanup happens separately via useCallAudioStream detecting WS close
+
+onWhatsappCallOutboundConnected:
+  OLD: Gets outbound PC, calls pc.setRemoteDescription(sdp_answer)
+  NEW: Calls store.markActiveCallConnected()
+       Triggers useCallSession to open the audio WS
+       No SDP handling at all
+
+onWhatsappCallPermissionGranted:
+  OLD: Same
+  NEW: Same (no change -- purely a UI notification)
+```
+
+---
+
+## 10. Comparison: Old vs New
+
+### Code complexity
+
+| Aspect | Old (browser WebRTC) | New (server relay) |
+|--------|---------------------|-------------------|
+| **useWhatsappCallSession.js** | 406 lines, WebRTC + recording + SDP + ICE | ~80 lines, pure call lifecycle orchestration |
+| **ConversationHeader.vue (call code)** | ~100 lines of WebRTC setup in component | ~10 lines: single `store.initiateCall()` call |
+| **Pinia store** | 94 lines + module-scoped `outboundCall` with PC/Stream | ~60 lines, purely serializable state |
+| **actionCable.js (call handlers)** | 50 lines with SDP relay logic | ~25 lines, metadata-only event handling |
+| **AudioWorklet processors** | N/A | ~30 lines each (two files), standard pattern |
+| **useCallAudioStream.js** | N/A (was inline WebRTC) | ~150 lines, focused audio I/O |
+| **Total frontend call code** | ~650 lines, scattered across 5 files | ~400 lines, organized in 3 composables + 2 worklets |
+
+### Capability comparison
+
+| Capability | Old | New |
+|-----------|-----|-----|
+| Call survives page reload | No | Yes |
+| Call survives network blip | No (ICE restart needed) | Yes (WS reconnect) |
+| Recording reliability | Low (browser crash = lost) | High (server-side) |
+| Multi-tab support | Not possible | Transfer or view-only |
+| Agent on mobile browser | Fragile (background tab kills WebRTC) | Better (WS more resilient) |
+| TURN server needed | Yes (for restrictive NAT) | No (server has public IP) |
+| Browser API surface | RTCPeerConnection, MediaRecorder, AudioContext, ICE, SDP, SRTP | getUserMedia, AudioContext, WebSocket, WebCodecs |
+| Codec flexibility | Locked to WebRTC negotiation | Server can transcode |
+
+### Latency comparison
+
+| Path | Old | New |
+|------|-----|-----|
+| Agent mic to customer | ~50ms (direct P2P via SRTP) | ~70-100ms (+20-50ms WS hop to server) |
+| Customer to agent speaker | ~50ms (direct P2P via SRTP) | ~70-100ms (+20-50ms WS hop from server) |
+
+The added ~20-50ms per direction is imperceptible in voice calls (human perception threshold for audio delay is ~150ms).
+
+### Failure mode comparison
+
+| Failure | Old | New |
+|---------|-----|-----|
+| Browser crashes | Call dead, recording lost | Call continues on server, agent can rejoin |
+| Network drops 5s | ICE restart attempt (often fails) | WS reconnect, brief audio gap |
+| Agent closes tab | Call terminated (beforeunload) | Call persists, agent can rejoin (or timeout) |
+| Server crashes | Call continues (P2P) | Call dead (single point of failure) |
+
+The server becoming a single point of failure is mitigated by the fact that it already is the single point of failure for signaling. If the server goes down in the old model, the agent cannot accept new calls or initiate calls anyway. The incremental risk is that an *in-progress* call dies, which is manageable with standard server redundancy.
+
+---
+
+## 11. Migration Strategy
+
+### Phase 1: Backend (prerequisite)
+- Server-side WebRTC: RTCPeerConnection to Meta from the backend process
+- Audio WebSocket endpoint: `/cable/audio` with binary frame handling
+- Server-side recording with the same Opus stream
+- New `GET /whatsapp_calls/active` endpoint
+- Modified `POST /accept` and `POST /initiate` (no SDP params)
+
+### Phase 2: Frontend (this document)
+- Create `useCallAudioStream.js` + AudioWorklet processors
+- Create `useCallSession.js` to replace `useWhatsappCallSession.js`
+- Create `useCallReconnection.js`
+- Simplify Pinia store
+- Simplify ActionCable handlers
+- Update CallWidget with reconnection UI
+- Remove all WebRTC code from ConversationHeader
+
+### Phase 3: Cleanup
+- Remove `startCallRecording` / `stopAndUploadRecording` exports
+- Remove `uploadRecording` API method
+- Remove `sdpOffer` / `iceServers` from all frontend types
+- Feature flag: `whatsapp_call_server_relay` to toggle between old/new during rollout
+
+---
+
+## 12. Open Questions for Backend Team
+
+1. **Audio WebSocket authentication**: Should we use a short-lived JWT in the WS URL query param, or perform auth in the first WS frame? JWT in URL is simpler but appears in server logs.
+
+2. **Server-side timeout**: When the browser disconnects the audio WS (page reload), how long should the server hold the Meta WebRTC session before auto-terminating? Recommendation: 30 seconds.
+
+3. **Audio buffering during reconnection**: Should the server buffer remote audio during a WS disconnect and replay it when the browser reconnects? Or just drop those frames? Recommendation: Drop -- a 2-4 second gap is acceptable, buffering adds complexity.
+
+4. **Opus passthrough vs transcode**: Can the server forward Meta's Opus frames directly to the browser WS, or does the SRTP decryption produce raw PCM that needs re-encoding? Direct passthrough is ideal (zero CPU cost).
+
+5. **Multi-process deployment**: If Chatwoot runs multiple Rails processes/pods, how does the audio WS route to the process that holds the RTCPeerConnection? Sticky sessions? Redis pub/sub relay? This is a backend architecture question but affects the WS endpoint design.
diff --git a/enterprise/app/controllers/api/v1/accounts/media_server/callbacks_controller.rb b/enterprise/app/controllers/api/v1/accounts/media_server/callbacks_controller.rb
new file mode 100644
index 000000000..ec1ae6f79
--- /dev/null
+++ b/enterprise/app/controllers/api/v1/accounts/media_server/callbacks_controller.rb
@@ -0,0 +1,67 @@
+class Api::V1::Accounts::MediaServer::CallbacksController < Api::V1::Accounts::BaseController
+  skip_before_action :authenticate_user!, raise: false
+  skip_before_action :authenticate_access_token!, raise: false
+  before_action :validate_media_server_token
+
+  def agent_disconnected
+    call = find_call_by_session
+    return head :not_found unless call
+
+    ActionCable.server.broadcast(
+      "account_#{call.account_id}",
+      {
+        event: 'whatsapp_call.agent_disconnected',
+        data: { id: call.id, call_id: call.provider_call_id, conversation_id: call.conversation_id }
+      }
+    )
+    head :ok
+  end
+
+  def recording_ready
+    call = find_call_by_session
+    return head :not_found unless call
+
+    Whatsapp::CallRecordingFetchJob.perform_later(call.id)
+    head :ok
+  end
+
+  def session_terminated
+    call = find_call_by_session
+    return head :not_found unless call
+    return head :ok if call.terminal?
+
+    reason = params[:reason] || 'media_server'
+    was_answered = call.in_progress? || call.accepted_by_agent_id.present?
+    final_status = was_answered ? 'completed' : 'failed'
+
+    call.update!(status: final_status, end_reason: reason)
+
+    ActionCable.server.broadcast(
+      "account_#{call.account_id}",
+      {
+        event: 'whatsapp_call.ended',
+        data: { id: call.id, call_id: call.provider_call_id, status: final_status, conversation_id: call.conversation_id }
+      }
+    )
+
+    # Also terminate on Meta side
+    provider = call.inbox.channel.provider_service
+    provider.terminate_call(call.provider_call_id)
+  rescue StandardError => e
+    Rails.logger.error "[MEDIA SERVER] Failed to terminate on provider: #{e.message}"
+  ensure
+    head :ok unless performed?
+  end
+
+  private
+
+  def validate_media_server_token
+    token = request.headers['Authorization']&.sub('Bearer ', '')
+    expected = ENV.fetch('MEDIA_SERVER_AUTH_TOKEN', '')
+    head :unauthorized unless expected.present? && token.present? && ActiveSupport::SecurityUtils.secure_compare(token, expected)
+  end
+
+  def find_call_by_session
+    Call.find_by(media_session_id: params[:session_id])
+  end
+end
diff --git a/enterprise/app/controllers/api/v1/accounts/whatsapp_calls_controller.rb b/enterprise/app/controllers/api/v1/accounts/whatsapp_calls_controller.rb
index f6ac792c7..2c7c259a1 100644
--- a/enterprise/app/controllers/api/v1/accounts/whatsapp_calls_controller.rb
+++ b/enterprise/app/controllers/api/v1/accounts/whatsapp_calls_controller.rb
@@ -1,6 +1,9 @@
 class Api::V1::Accounts::WhatsappCallsController < Api::V1::Accounts::BaseController
+  ALLOWED_PEER_ROLES = %w[listen_only participant].freeze
+  ALLOWED_AUDIO_MODES = %w[replace mix].freeze
+
   before_action :ensure_whatsapp_call_enabled
-  before_action :set_call, only: [:show, :accept, :reject, :terminate, :upload_recording]
+  before_action :set_call, only: [:show, :accept, :reject, :terminate, :upload_recording, :agent_answer, :reconnect, :join, :play_audio]
 
   def show
     render json: {
@@ -18,11 +21,16 @@ class Api::V1::Accounts::WhatsappCallsController < Api::V1::Accounts::BaseContro
   end
 
   def accept
-    sdp_answer = params[:sdp_answer]
-    return render json: { error: 'sdp_answer is required' }, status: :unprocessable_entity if sdp_answer.blank?
+    if Call.media_server_enabled?
+      call = Whatsapp::CallService.new(call: @call, agent: current_user).accept
+      render json: { id: call.id, status: call.status, message_id: call.message_id, media_session_id: call.media_session_id }
+    else
+      sdp_answer = params[:sdp_answer]
+      return render json: { error: 'sdp_answer is required' }, status: :unprocessable_entity if sdp_answer.blank?
 
-    call = Whatsapp::CallService.new(call: @call, agent: current_user).pre_accept_and_accept(sdp_answer)
-    render json: { id: call.id, status: call.status, message_id: call.message_id }
+      call = Whatsapp::CallService.new(call: @call, agent: current_user).pre_accept_and_accept(sdp_answer)
+      render json: { id: call.id, status: call.status, message_id: call.message_id }
+    end
   rescue Whatsapp::CallErrors::NotRinging, Whatsapp::CallErrors::AlreadyAccepted => e
     render json: { error: e.message }, status: :unprocessable_entity
   rescue StandardError => e
@@ -57,6 +65,89 @@ class Api::V1::Accounts::WhatsappCallsController < Api::V1::Accounts::BaseContro
     render json: { error: 'Failed to upload recording' }, status: :internal_server_error
   end
 
+  def active
+    call = current_account.calls.whatsapp.active_for_agent(current_user.id).last
+    if call
+      elapsed = call.started_at ? (Time.current - call.started_at).to_i : 0
+      render json: {
+        id: call.id,
+        call_id: call.provider_call_id,
+        conversation_id: call.conversation_id,
+        status: call.status,
+        elapsed_seconds: elapsed,
+        media_session_id: call.media_session_id
+      }
+    else
+      render json: { call: nil }
+    end
+  end
+
+  def agent_answer
+    return render json: { error: 'sdp_answer is required' }, status: :unprocessable_entity if params[:sdp_answer].blank?
+    return render json: { error: 'No media session' }, status: :unprocessable_entity if @call.media_session_id.blank?
+
+    client = Whatsapp::MediaServerClient.new
+    client.set_agent_answer(@call.media_session_id, sdp_answer: params[:sdp_answer])
+    render json: { success: true }
+  rescue Whatsapp::MediaServerClient::SessionError, Whatsapp::MediaServerClient::ConnectionError => e
+    Rails.logger.error "[WHATSAPP CALL] agent_answer failed: #{e.message}"
+    render json: { error: 'Failed to set agent answer' }, status: :internal_server_error
+  end
+
+  def reconnect
+    return render json: { error: 'No media session' }, status: :unprocessable_entity if @call.media_session_id.blank?
+    return render json: { error: 'Call is not in progress' }, status: :unprocessable_entity unless @call.in_progress?
+
+    client = Whatsapp::MediaServerClient.new
+    response = client.reconnect_agent(@call.media_session_id)
+    render json: {
+      sdp_offer: response['sdp_offer'],
+      ice_servers: response['ice_servers']
+    }
+  rescue Whatsapp::MediaServerClient::SessionError, Whatsapp::MediaServerClient::ConnectionError => e
+    Rails.logger.error "[WHATSAPP CALL] reconnect failed: #{e.message}"
+    render json: { error: 'Failed to reconnect' }, status: :internal_server_error
+  end
+
+  def join
+    return render json: { error: 'No media session' }, status: :unprocessable_entity if @call.media_session_id.blank?
+
+    role = params[:role] || 'listen_only'
+    return render json: { error: 'Invalid role' }, status: :unprocessable_entity unless ALLOWED_PEER_ROLES.include?(role)
+
+    client = Whatsapp::MediaServerClient.new
+    response = client.add_peer(@call.media_session_id, role: role, label: current_user.name)
+    render json: {
+      peer_id: response['peer_id'],
+      sdp_offer: response['sdp_offer'],
+      ice_servers: response['ice_servers']
+    }
+  rescue Whatsapp::MediaServerClient::SessionError, Whatsapp::MediaServerClient::ConnectionError => e
+    Rails.logger.error "[WHATSAPP CALL] join failed: #{e.message}"
+    render json: { error: 'Failed to join call' }, status: :internal_server_error
+  end
+
+  def play_audio
+    return render json: { error: 'No media session' }, status: :unprocessable_entity if @call.media_session_id.blank?
+    return render json: { error: 'file_path is required' }, status: :unprocessable_entity if params[:file_path].blank?
+    return render json: { error: 'Invalid file_path' }, status: :unprocessable_entity if params[:file_path].include?('..')
+
+    mode = params[:mode] || 'replace'
+    return render json: { error: 'Invalid mode' }, status: :unprocessable_entity unless ALLOWED_AUDIO_MODES.include?(mode)
+
+    client = Whatsapp::MediaServerClient.new
+    response = client.inject_audio(
+      @call.media_session_id,
+      file_path: params[:file_path],
+      mode: mode,
+      loop: ActiveModel::Type::Boolean.new.cast(params[:loop])
+    )
+    render json: { injection_id: response['injection_id'] }
+  rescue Whatsapp::MediaServerClient::SessionError, Whatsapp::MediaServerClient::ConnectionError => e
+    Rails.logger.error "[WHATSAPP CALL] play_audio failed: #{e.message}"
+    render json: { error: 'Failed to play audio' }, status: :internal_server_error
+  end
+
   def initiate
     conversation = current_account.conversations.find(params[:conversation_id])
     authorize conversation, :show?
@@ -81,8 +172,16 @@ class Api::V1::Accounts::WhatsappCallsController < Api::V1::Accounts::BaseContro
   def create_outbound_call(conversation)
     contact_phone = conversation.contact&.phone_number
     raise ArgumentError, 'Contact phone number not available' if contact_phone.blank?
-    raise ArgumentError, 'sdp_offer is required' if params[:sdp_offer].blank?
+    raise ArgumentError, 'sdp_offer is required' if params[:sdp_offer].blank? && !Call.media_server_enabled?
 
+    if Call.media_server_enabled?
+      create_outbound_call_via_media_server(conversation, contact_phone)
+    else
+      create_outbound_call_direct(conversation, contact_phone)
+    end
+  end
+
+  def create_outbound_call_direct(conversation, contact_phone)
     result = conversation.inbox.channel.provider_service.initiate_call(contact_phone.delete('+'), params[:sdp_offer])
     provider_call_id = result.dig('calls', 0, 'id') || result['call_id']
 
@@ -94,6 +193,31 @@ class Api::V1::Accounts::WhatsappCallsController < Api::V1::Accounts::BaseContro
     )
   end
 
+  def create_outbound_call_via_media_server(conversation, contact_phone)
+    client = Whatsapp::MediaServerClient.new
+
+    # Step 1: Create session on media server (generates SDP offer for Meta)
+    session_response = client.create_session(
+      call_id: "pending_#{SecureRandom.hex(8)}",
+      sdp_offer: nil,
+      ice_servers: [{ urls: 'stun:stun.l.google.com:19302' }],
+      account_id: current_account.id
+    )
+
+    # Step 2: Send the media server's SDP offer to Meta to initiate the call
+    sdp_offer = session_response['meta_sdp_answer'] || session_response['sdp_offer']
+    result = conversation.inbox.channel.provider_service.initiate_call(contact_phone.delete('+'), sdp_offer)
+    provider_call_id = result.dig('calls', 0, 'id') || result['call_id']
+
+    current_account.calls.create!(
+      provider: :whatsapp,
+      inbox: conversation.inbox, conversation: conversation,
+      provider_call_id: provider_call_id, direction: :outgoing, status: 'ringing',
+      media_session_id: session_response['session_id'],
+      meta: { sdp_offer: sdp_offer }
+    )
+  end
+
   def handle_no_call_permission(conversation)
     last_requested = conversation.additional_attributes&.dig('call_permission_requested_at')
 
diff --git a/enterprise/app/jobs/whatsapp/call_cleanup_job.rb b/enterprise/app/jobs/whatsapp/call_cleanup_job.rb
new file mode 100644
index 000000000..47f7e7fa4
--- /dev/null
+++ b/enterprise/app/jobs/whatsapp/call_cleanup_job.rb
@@ -0,0 +1,33 @@
+class Whatsapp::CallCleanupJob < ApplicationJob
+  queue_as :low
+
+  def perform
+    expire_stale_ringing_calls
+    expire_stale_in_progress_calls
+  end
+
+  private
+
+  def expire_stale_ringing_calls
+    Call.whatsapp.ringing.where('created_at < ?', 2.minutes.ago).find_each do |call|
+      call.update!(status: 'no_answer', end_reason: 'timeout')
+      Whatsapp::CallMessageBuilder.update_status!(call: call, status: 'no_answer')
+    end
+  end
+
+  def expire_stale_in_progress_calls
+    Call.whatsapp.where(status: 'in_progress').where('started_at < ?', 3.hours.ago).find_each do |call|
+      terminate_media_session(call)
+      call.update!(status: 'failed', end_reason: 'timeout')
+      Whatsapp::CallMessageBuilder.update_status!(call: call, status: 'failed')
+    end
+  end
+
+  def terminate_media_session(call)
+    return unless call.media_session_id.present?
+
+    Whatsapp::MediaServerClient.new.terminate_session(call.media_session_id)
+  rescue Whatsapp::MediaServerClient::ConnectionError, Whatsapp::MediaServerClient::SessionError => e
+    Rails.logger.error "[WHATSAPP CALL CLEANUP] Failed to terminate media session #{call.media_session_id}: #{e.message}"
+  end
+end
diff --git a/enterprise/app/jobs/whatsapp/call_recording_fetch_job.rb b/enterprise/app/jobs/whatsapp/call_recording_fetch_job.rb
new file mode 100644
index 000000000..91ca8a2a7
--- /dev/null
+++ b/enterprise/app/jobs/whatsapp/call_recording_fetch_job.rb
@@ -0,0 +1,26 @@
+class Whatsapp::CallRecordingFetchJob < ApplicationJob
+  queue_as :default
+
+  retry_on Whatsapp::MediaServerClient::ConnectionError, wait: 5.seconds, attempts: 5
+  discard_on ActiveRecord::RecordNotFound
+
+  def perform(call_id)
+    call = Call.find(call_id)
+    return unless call.media_session_id.present?
+
+    client = Whatsapp::MediaServerClient.new
+    recording_data = client.download_recording(call.media_session_id)
+    return if recording_data.blank?
+
+    call.recording.attach(
+      io: StringIO.new(recording_data.force_encoding('BINARY')),
+      filename: "call_#{call.id}_#{call.provider_call_id}.ogg",
+      content_type: 'audio/ogg'
+    )
+
+    Whatsapp::CallMessageBuilder.update_recording_url!(call: call)
+    Whatsapp::CallTranscriptionJob.perform_later(call.id) if call.recording.attached?
+  rescue Whatsapp::MediaServerClient::SessionError => e
+    Rails.logger.warn "[WHATSAPP CALL] Recording not available for session #{call.media_session_id}: #{e.message}"
+  end
+end
diff --git a/enterprise/app/models/call.rb b/enterprise/app/models/call.rb
index 621314128..cad9e52e6 100644
--- a/enterprise/app/models/call.rb
+++ b/enterprise/app/models/call.rb
@@ -22,6 +22,11 @@ class Call < ApplicationRecord
 
   scope :active, -> { where.not(status: TERMINAL_STATUSES) }
   scope :ringing, -> { where(status: 'ringing') }
+  scope :active_for_agent, ->(agent_id) { active.where(accepted_by_agent_id: agent_id) }
+
+  def self.media_server_enabled?
+    ENV['MEDIA_SERVER_URL'].present?
+  end
 
   def ringing?
     status == 'ringing'
diff --git a/enterprise/app/services/whatsapp/call_service.rb b/enterprise/app/services/whatsapp/call_service.rb
index e6161106b..215771819 100644
--- a/enterprise/app/services/whatsapp/call_service.rb
+++ b/enterprise/app/services/whatsapp/call_service.rb
@@ -1,6 +1,14 @@
 class Whatsapp::CallService
   pattr_initialize [:call!, :agent!]
 
+  def accept(params = {})
+    if media_server_enabled?
+      accept_via_media_server
+    else
+      pre_accept_and_accept(params[:sdp_answer])
+    end
+  end
+
   def pre_accept_and_accept(sdp_answer)
     call.with_lock do
       ensure_ringing!
@@ -48,9 +56,8 @@ class Whatsapp::CallService
   def terminate
     return call if call.terminal?
 
-    provider = call.inbox.channel.provider_service
-    success = provider.terminate_call(call.provider_call_id)
-    Rails.logger.error "[WHATSAPP CALL] terminate_call API returned false for call #{call.provider_call_id}" unless success
+    terminate_media_session if call.media_session_id.present?
+    terminate_on_provider
 
     call.update!(status: 'completed')
     Whatsapp::CallMessageBuilder.update_status!(call: call, status: 'completed')
@@ -59,8 +66,69 @@ class Whatsapp::CallService
     call
   end
 
+  def terminate_on_provider
+    provider = call.inbox.channel.provider_service
+    success = provider.terminate_call(call.provider_call_id)
+    Rails.logger.error "[WHATSAPP CALL] terminate_call API returned false for call #{call.provider_call_id}" unless success
+  end
+
   private
 
+  def accept_via_media_server
+    agent_offer = nil
+
+    call.with_lock do
+      ensure_ringing!
+      ensure_not_already_taken!
+
+      client = Whatsapp::MediaServerClient.new
+
+      # Step 1: Create session on Go server with Meta's SDP
+      session_response = client.create_session(
+        call_id: call.provider_call_id,
+        sdp_offer: call.sdp_offer,
+        ice_servers: call.ice_servers,
+        account_id: call.account_id
+      )
+
+      # Step 2: Send Go-generated SDP answer to Meta
+      provider = call.inbox.channel.provider_service
+      pre_response = provider.pre_accept_call(call.provider_call_id, session_response['meta_sdp_answer'])
+      raise Whatsapp::CallErrors::NotRinging, 'Meta pre_accept failed' unless pre_response
+
+      accept_response = provider.accept_call(call.provider_call_id, session_response['meta_sdp_answer'])
+      raise Whatsapp::CallErrors::NotRinging, 'Meta accept failed' unless accept_response
+
+      # Step 3: Generate agent offer (Peer B)
+      agent_offer = client.generate_agent_offer(session_response['session_id'])
+
+      # Step 4: Update call record
+      call.update!(
+        status: 'in_progress',
+        accepted_by_agent_id: agent.id,
+        started_at: Time.current,
+        media_session_id: session_response['session_id']
+      )
+    end
+
+    # Step 5: Broadcast events (outside lock)
+    Whatsapp::CallMessageBuilder.update_status!(call: call, status: 'in_progress', agent: agent)
+    update_conversation_call_status('in-progress')
+    broadcast_agent_offer(agent_offer)
+    broadcast_accepted
+    call
+  end
+
+  def media_server_enabled?
+    Call.media_server_enabled?
+  end
+
+  def terminate_media_session
+    Whatsapp::MediaServerClient.new.terminate_session(call.media_session_id)
+  rescue Whatsapp::MediaServerClient::ConnectionError, Whatsapp::MediaServerClient::SessionError => e
+    Rails.logger.error "[WHATSAPP CALL] Failed to terminate media session: #{e.message}"
+  end
+
   def ensure_ringing!
     raise Whatsapp::CallErrors::NotRinging, 'Call is not in ringing state' unless call.ringing?
   end
@@ -93,6 +161,22 @@ class Whatsapp::CallService
     ActionCable.server.broadcast("account_#{call.account_id}", payload)
   end
 
+  def broadcast_agent_offer(agent_offer)
+    payload = {
+      event: 'whatsapp_call.agent_offer',
+      data: {
+        account_id: call.account_id,
+        id: call.id,
+        call_id: call.provider_call_id,
+        conversation_id: call.conversation_id,
+        accepted_by_agent_id: agent.id,
+        sdp_offer: agent_offer['sdp_offer'],
+        ice_servers: agent_offer['ice_servers']
+      }
+    }
+    ActionCable.server.broadcast("account_#{call.account_id}", payload)
+  end
+
   def broadcast_call_ended
     payload = {
       event: 'whatsapp_call.ended',
diff --git a/enterprise/app/services/whatsapp/incoming_call_service.rb b/enterprise/app/services/whatsapp/incoming_call_service.rb
index 3f072e621..c290b5984 100644
--- a/enterprise/app/services/whatsapp/incoming_call_service.rb
+++ b/enterprise/app/services/whatsapp/incoming_call_service.rb
@@ -99,6 +99,9 @@ class Whatsapp::IncomingCallService
     mapped = Whatsapp::CallMessageBuilder::CALL_TO_VOICE_STATUS[final_status] || final_status
     update_conversation_call_status(call.conversation, mapped, call.direction_label)
     broadcast_call_ended(call)
+
+    # Fetch recording from media server if a session was active
+    Whatsapp::CallRecordingFetchJob.perform_later(call.id) if call.media_session_id.present?
   end
 
   def find_or_create_contact(phone_number)
@@ -141,26 +144,28 @@ class Whatsapp::IncomingCallService
   end
 
   def broadcast_incoming_call(call, contact, sdp_offer)
-    payload = {
-      event: 'whatsapp_call.incoming',
-      data: {
-        account_id: inbox.account_id,
-        id: call.id,
-        call_id: call.provider_call_id,
-        direction: call.direction_label,
-        inbox_id: call.inbox_id,
-        conversation_id: call.conversation_id,
-        caller: {
-          name: contact.name,
-          phone: contact.phone_number,
-          avatar: contact.avatar_url
-        },
-        sdp_offer: sdp_offer,
-        ice_servers: default_ice_servers
+    data = {
+      account_id: inbox.account_id,
+      id: call.id,
+      call_id: call.provider_call_id,
+      direction: call.direction_label,
+      inbox_id: call.inbox_id,
+      conversation_id: call.conversation_id,
+      caller: {
+        name: contact.name,
+        phone: contact.phone_number,
+        avatar: contact.avatar_url
       }
     }
 
-    ActionCable.server.broadcast("account_#{inbox.account_id}", payload)
+    # When media server is enabled, the browser does not need Meta's SDP since
+    # the Go sidecar handles the Meta-side peer connection directly.
+    unless Call.media_server_enabled?
+      data[:sdp_offer] = sdp_offer
+      data[:ice_servers] = default_ice_servers
+    end
+
+    ActionCable.server.broadcast("account_#{inbox.account_id}", { event: 'whatsapp_call.incoming', data: data })
   end
 
   def broadcast_call_ended(call)
diff --git a/enterprise/app/services/whatsapp/media_server_client.rb b/enterprise/app/services/whatsapp/media_server_client.rb
new file mode 100644
index 000000000..607a8f5a0
--- /dev/null
+++ b/enterprise/app/services/whatsapp/media_server_client.rb
@@ -0,0 +1,109 @@
+class Whatsapp::MediaServerClient
+  class ConnectionError < StandardError; end
+  class SessionError < StandardError; end
+
+  TIMEOUT = 10
+
+  def create_session(call_id:, sdp_offer:, ice_servers:, account_id: nil)
+    body = { call_id: call_id, meta_sdp_offer: sdp_offer, ice_servers: ice_servers, account_id: account_id }.compact
+    post('/sessions', body)
+  end
+
+  def generate_agent_offer(session_id)
+    post("/sessions/#{session_id}/agent-offer")
+  end
+
+  def set_agent_answer(session_id, sdp_answer:)
+    post("/sessions/#{session_id}/agent-answer", { sdp_answer: sdp_answer })
+  end
+
+  def reconnect_agent(session_id)
+    post("/sessions/#{session_id}/agent-reconnect")
+  end
+
+  def terminate_session(session_id)
+    post("/sessions/#{session_id}/terminate")
+  end
+
+  def download_recording(session_id)
+    response = execute_request(:get, "/sessions/#{session_id}/recording")
+    unless response.success?
+      Rails.logger.error "[MEDIA SERVER] Recording download failed: status=#{response.code}"
+      raise SessionError, "Recording download failed (#{response.code})"
+    end
+    response.body
+  end
+
+  def add_peer(session_id, role:, label:)
+    post("/sessions/#{session_id}/peers", { role: role, label: label })
+  end
+
+  def remove_peer(session_id, peer_id:)
+    delete("/sessions/#{session_id}/peers/#{peer_id}")
+  end
+
+  def inject_audio(session_id, file_path:, mode: 'replace', loop: false, target: 'peer_a')
+    post("/sessions/#{session_id}/inject-audio", { file_path: file_path, mode: mode, loop: loop, target: target })
+  end
+
+  def stop_audio_injection(session_id, injection_id:)
+    delete("/sessions/#{session_id}/inject-audio/#{injection_id}")
+  end
+
+  def health_check
+    get('/health')
+  end
+
+  private
+
+  def post(path, body = {})
+    response = execute_request(:post, path, body)
+    parse_response(response)
+  end
+
+  def get(path)
+    response = execute_request(:get, path)
+    parse_response(response)
+  end
+
+  def delete(path)
+    response = execute_request(:delete, path)
+    parse_response(response)
+  end
+
+  def execute_request(method, path, body = nil)
+    url = "#{base_url}#{path}"
+    options = { headers: auth_headers, timeout: TIMEOUT }
+    options[:body] = body.to_json if body.present?
+
+    Rails.logger.info "[MEDIA SERVER] #{method.upcase} #{path}"
+    HTTParty.send(method, url, options)
+  rescue Errno::ECONNREFUSED, Net::OpenTimeout, Net::ReadTimeout, SocketError => e
+    Rails.logger.error "[MEDIA SERVER] Connection failed: #{e.class} #{e.message}"
+    raise ConnectionError, "Media server unavailable: #{e.message}"
+  end
+
+  def parse_response(response)
+    unless response.success?
+      Rails.logger.error "[MEDIA SERVER] Request failed: status=#{response.code} body=#{response.body}"
+      raise SessionError, "Media server error (#{response.code}): #{response.body}"
+    end
+
+    response.parsed_response
+  end
+
+  def base_url
+    ENV.fetch('MEDIA_SERVER_URL', 'http://localhost:4000')
+  end
+
+  def auth_token
+    ENV.fetch('MEDIA_SERVER_AUTH_TOKEN', '')
+  end
+
+  def auth_headers
+    {
+      'Content-Type' => 'application/json',
+      'Authorization' => "Bearer #{auth_token}"
+    }
+  end
+end
diff --git a/enterprise/media-server/Dockerfile b/enterprise/media-server/Dockerfile
new file mode 100644
index 000000000..23b54fb7b
--- /dev/null
+++ b/enterprise/media-server/Dockerfile
@@ -0,0 +1,31 @@
+FROM golang:1.22-alpine AS builder
+
+RUN apk add --no-cache git gcc musl-dev
+
+WORKDIR /build
+
+# Copy module files and download dependencies (layer caching).
+COPY go.mod go.sum* ./
+RUN if [ -f go.sum ]; then go mod download; fi
+
+# Build the binary (go mod tidy ensures go.sum is present).
+COPY . .
+RUN go mod tidy && CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o chatwoot-media-server ./cmd/server/
+
+# ---
+
+FROM alpine:3.19
+
+RUN apk add --no-cache ca-certificates wget
+
+COPY --from=builder /build/chatwoot-media-server /usr/local/bin/
+
+RUN mkdir -p /recordings
+
+EXPOSE 4000
+EXPOSE 10000-12000/udp
+
+HEALTHCHECK --interval=10s --timeout=5s --retries=3 \
+  CMD wget --spider -q http://localhost:4000/health || exit 1
+
+ENTRYPOINT ["chatwoot-media-server"]
diff --git a/enterprise/media-server/README.md b/enterprise/media-server/README.md
new file mode 100644
index 000000000..a191a6c29
--- /dev/null
+++ b/enterprise/media-server/README.md
@@ -0,0 +1,155 @@
+# chatwoot-media-server
+
+A Pion WebRTC media server sidecar for Chatwoot's WhatsApp Calling feature. It acts as a back-to-back user agent (B2BUA) between Meta's media servers and the agent's browser, providing call persistence across page reloads, server-side recording, and centralized call lifecycle management.
+
+## Architecture
+
+The media server maintains two independent WebRTC peer connections per call:
+
+- **Peer A (Meta-side):** Receives the customer's audio from Meta and sends the agent's audio back.
+- **Peer B (Agent-side):** Receives the agent's microphone audio and sends the customer's audio to the browser.
+
+An audio bridge forwards RTP packets between the two peers while simultaneously recording both streams to OGG/Opus files.
+
+## Build
+
+```bash
+# Local build
+go build -o chatwoot-media-server ./cmd/server/
+
+# Docker build
+docker build -t chatwoot-media-server .
+```
+
+## Run
+
+```bash
+# Locally
+AUTH_TOKEN=secret RAILS_CALLBACK_URL=http://localhost:3000 ./chatwoot-media-server
+
+# Docker
+docker run -p 4000:4000 -p 10000-10100:10000-10100/udp \
+  -e AUTH_TOKEN=secret \
+  -e RAILS_CALLBACK_URL=http://rails:3000 \
+  -v media-recordings:/recordings \
+  chatwoot-media-server
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `AUTH_TOKEN` | (empty) | Shared secret for Bearer token auth. Empty disables auth (dev only). |
+| `RAILS_CALLBACK_URL` | `http://localhost:3000` | Base URL for Rails callbacks. |
+| `STUN_SERVERS` | `stun:stun.l.google.com:19302` | Comma-separated STUN server URLs. |
+| `TURN_SERVERS` | (empty) | Comma-separated TURN server URLs. |
+| `TURN_USERNAME` | (empty) | TURN credential username. |
+| `TURN_PASSWORD` | (empty) | TURN credential password. |
+| `PUBLIC_IP` | (empty) | Server's public IP for ICE candidates. |
+| `UDP_PORT_MIN` | `10000` | Lower bound of UDP port range. |
+| `UDP_PORT_MAX` | `12000` | Upper bound of UDP port range. |
+| `RECORDINGS_DIR` | `/recordings` | Directory for recording files. |
+| `HTTP_PORT` | `4000` | HTTP API listen port. |
+| `LOG_LEVEL` | `info` | Log level (debug, info, warn, error). |
+| `MAX_SESSION_DURATION` | `7200` | Max call duration in seconds (2 hours). |
+| `RECONNECT_TIMEOUT` | `30` | Seconds to wait for agent reconnect. |
+| `MAX_CONCURRENT_SESSIONS` | `0` | Max active sessions (0 = unlimited). |
+
+## API
+
+All endpoints except `/health` require a `Authorization: Bearer <token>` header.
+
+### Sessions
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/sessions` | Create session (Meta SDP offer -> Peer A) |
+| `GET` | `/sessions/:id` | Get session status |
+| `POST` | `/sessions/:id/agent-offer` | Generate agent-side SDP offer (Peer B) |
+| `POST` | `/sessions/:id/agent-answer` | Set agent's SDP answer, complete Peer B |
+| `POST` | `/sessions/:id/agent-reconnect` | Tear down old Peer B, create new one |
+| `POST` | `/sessions/:id/terminate` | End call, finalize recording |
+| `GET` | `/sessions/:id/recording` | Download recording (binary OGG) |
+| `DELETE` | `/sessions/:id` | Cleanup session and files |
+
+### Multi-participant
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/sessions/:id/peers` | Add a peer |
+| `DELETE` | `/sessions/:id/peers/:peer_id` | Remove a peer |
+| `PATCH` | `/sessions/:id/peers/:peer_id/role` | Change peer role |
+
+### Audio Injection
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/sessions/:id/inject-audio` | Start audio injection |
+| `DELETE` | `/sessions/:id/inject-audio/:inj_id` | Stop injection |
+
+### System
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/health` | Health check (no auth) |
+| `GET` | `/metrics` | Session metrics |
+
+### Example: Create Session (Incoming Call)
+
+```bash
+curl -X POST http://localhost:4000/sessions \
+  -H "Authorization: Bearer secret" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "call_id": "call_123",
+    "account_id": "1",
+    "direction": "incoming",
+    "meta_sdp_offer": "v=0\r\no=- ...",
+    "ice_servers": [{"urls": ["stun:stun.l.google.com:19302"]}]
+  }'
+```
+
+Response:
+
+```json
+{
+  "session_id": "sess_20240101120000_1",
+  "meta_sdp_answer": "v=0\r\no=- ...",
+  "status": "created"
+}
+```
+
+## Recording
+
+Recordings are written in real time as OGG/Opus files to the configured recordings directory. Three files are produced per call:
+
+- `{session_id}.ogg` -- Combined audio for playback
+- `{session_id}_customer.ogg` -- Customer channel only (for transcription)
+- `{session_id}_agent.ogg` -- Agent channel only (for transcription)
+
+On call termination, a callback is sent to Rails which fetches the recording via `GET /sessions/:id/recording` and stores it in ActiveStorage.
+
+## Deployment
+
+Add to `docker-compose.yml`:
+
+```yaml
+media-server:
+  build:
+    context: ./enterprise/media-server
+  ports:
+    - "4000:4000"
+    - "10000-10100:10000-10100/udp"
+  environment:
+    - AUTH_TOKEN=${MEDIA_SERVER_AUTH_TOKEN}
+    - RAILS_CALLBACK_URL=http://web:3000
+    - STUN_SERVERS=stun:stun.l.google.com:19302
+    - RECORDINGS_DIR=/recordings
+    - UDP_PORT_MIN=10000
+    - UDP_PORT_MAX=10100
+  volumes:
+    - media-recordings:/recordings
+  restart: unless-stopped
+```
+
+UDP ports must be exposed to the internet for WebRTC connectivity. If direct UDP exposure is not possible, configure a TURN server as a relay.
diff --git a/enterprise/media-server/cmd/server/main.go b/enterprise/media-server/cmd/server/main.go
new file mode 100644
index 000000000..d440fad10
--- /dev/null
+++ b/enterprise/media-server/cmd/server/main.go
@@ -0,0 +1,133 @@
+// Package main is the entry point for the chatwoot-media-server binary. It
+// loads configuration, initializes the session manager, sets up HTTP routes,
+// and starts the server with graceful shutdown support.
+package main
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"net/http"
+	"os"
+	"os/signal"
+	"syscall"
+	"time"
+
+	"github.com/chatwoot/chatwoot-media-server/internal/callback"
+	"github.com/chatwoot/chatwoot-media-server/internal/config"
+	"github.com/chatwoot/chatwoot-media-server/internal/server"
+	"github.com/chatwoot/chatwoot-media-server/internal/session"
+)
+
+func main() {
+	if err := run(); err != nil {
+		slog.Error("fatal error", "error", err)
+		os.Exit(1)
+	}
+}
+
+func run() error {
+	// Load configuration from environment variables.
+	cfg, err := config.Load()
+	if err != nil {
+		return fmt.Errorf("load config: %w", err)
+	}
+
+	// Configure structured logging.
+	setupLogging(cfg.LogLevel)
+
+	// Log configuration warnings.
+	for _, w := range cfg.Validate() {
+		slog.Warn("config warning", "message", w)
+	}
+
+	slog.Info("starting chatwoot-media-server",
+		"http_port", cfg.HTTPPort,
+		"udp_port_range", fmt.Sprintf("%d-%d", cfg.UDPPortMin, cfg.UDPPortMax),
+		"recordings_dir", cfg.RecordingsDir,
+	)
+
+	// Ensure recordings directory exists.
+	if err := os.MkdirAll(cfg.RecordingsDir, 0o755); err != nil {
+		return fmt.Errorf("create recordings directory: %w", err)
+	}
+
+	// Initialize the Rails callback client.
+	railsClient := callback.NewRailsClient(cfg.RailsCallbackURL, cfg.AuthToken)
+
+	// Initialize the session manager.
+	mgr := session.NewManager(cfg, railsClient)
+
+	// Recover any orphaned recordings from a previous crash.
+	mgr.RecoverOrphanedRecordings()
+
+	// Build the HTTP router.
+	router := server.NewRouter(cfg, mgr)
+	handler := router.Build()
+
+	// Create the HTTP server.
+	srv := &http.Server{
+		Addr:         fmt.Sprintf(":%d", cfg.HTTPPort),
+		Handler:      handler,
+		ReadTimeout:  15 * time.Second,
+		WriteTimeout: 30 * time.Second,
+		IdleTimeout:  60 * time.Second,
+	}
+
+	// Start the server in a goroutine.
+	errCh := make(chan error, 1)
+	go func() {
+		slog.Info("HTTP server listening", "addr", srv.Addr)
+		if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
+			errCh <- fmt.Errorf("HTTP server error: %w", err)
+		}
+	}()
+
+	// Wait for shutdown signal or server error.
+	sigCh := make(chan os.Signal, 1)
+	signal.Notify(sigCh, syscall.SIGINT, syscall.SIGTERM)
+
+	select {
+	case sig := <-sigCh:
+		slog.Info("received shutdown signal", "signal", sig.String())
+	case err := <-errCh:
+		return err
+	}
+
+	// Graceful shutdown: stop accepting new connections, drain existing ones.
+	slog.Info("initiating graceful shutdown")
+
+	// First, terminate all active sessions so recordings are finalized.
+	mgr.Shutdown()
+
+	// Then shut down the HTTP server with a timeout.
+	shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer shutdownCancel()
+
+	if err := srv.Shutdown(shutdownCtx); err != nil {
+		return fmt.Errorf("HTTP server shutdown error: %w", err)
+	}
+
+	slog.Info("server stopped gracefully")
+	return nil
+}
+
+// setupLogging configures the global slog logger with the given level.
+func setupLogging(level string) {
+	var logLevel slog.Level
+	switch level {
+	case "debug":
+		logLevel = slog.LevelDebug
+	case "warn":
+		logLevel = slog.LevelWarn
+	case "error":
+		logLevel = slog.LevelError
+	default:
+		logLevel = slog.LevelInfo
+	}
+
+	handler := slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
+		Level: logLevel,
+	})
+	slog.SetDefault(slog.New(handler))
+}
diff --git a/enterprise/media-server/go.mod b/enterprise/media-server/go.mod
new file mode 100644
index 000000000..82a697235
--- /dev/null
+++ b/enterprise/media-server/go.mod
@@ -0,0 +1,30 @@
+module github.com/chatwoot/chatwoot-media-server
+
+go 1.22
+
+require (
+	github.com/pion/interceptor v0.1.37
+	github.com/pion/rtp v1.8.9
+	github.com/pion/webrtc/v4 v4.0.5
+)
+
+require (
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/pion/datachannel v1.5.10 // indirect
+	github.com/pion/dtls/v3 v3.0.4 // indirect
+	github.com/pion/ice/v4 v4.0.3 // indirect
+	github.com/pion/logging v0.2.2 // indirect
+	github.com/pion/mdns/v2 v2.0.7 // indirect
+	github.com/pion/randutil v0.1.0 // indirect
+	github.com/pion/rtcp v1.2.14 // indirect
+	github.com/pion/sctp v1.8.34 // indirect
+	github.com/pion/sdp/v3 v3.0.9 // indirect
+	github.com/pion/srtp/v3 v3.0.4 // indirect
+	github.com/pion/stun/v3 v3.0.0 // indirect
+	github.com/pion/transport/v3 v3.0.7 // indirect
+	github.com/pion/turn/v4 v4.0.0 // indirect
+	github.com/wlynxg/anet v0.0.5 // indirect
+	golang.org/x/crypto v0.29.0 // indirect
+	golang.org/x/net v0.31.0 // indirect
+	golang.org/x/sys v0.27.0 // indirect
+)
diff --git a/enterprise/media-server/internal/auth/middleware.go b/enterprise/media-server/internal/auth/middleware.go
new file mode 100644
index 000000000..fde1072b2
--- /dev/null
+++ b/enterprise/media-server/internal/auth/middleware.go
@@ -0,0 +1,65 @@
+// Package auth provides HTTP authentication middleware for the media server API.
+package auth
+
+import (
+	"crypto/subtle"
+	"fmt"
+	"log/slog"
+	"net/http"
+	"strings"
+)
+
+// Middleware returns an HTTP middleware that validates Bearer token authentication.
+// Requests without a valid token receive a 401 Unauthorized response. If the
+// configured token is empty, all requests are allowed (development mode).
+func Middleware(token string) func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			// Skip auth if no token is configured (development mode).
+			if token == "" {
+				next.ServeHTTP(w, r)
+				return
+			}
+
+			authHeader := r.Header.Get("Authorization")
+			if authHeader == "" {
+				slog.Warn("missing Authorization header",
+					"path", r.URL.Path,
+					"remote_addr", r.RemoteAddr,
+				)
+				writeAuthError(w, "missing Authorization header")
+				return
+			}
+
+			// Extract Bearer token.
+			parts := strings.SplitN(authHeader, " ", 2)
+			if len(parts) != 2 || !strings.EqualFold(parts[0], "Bearer") {
+				slog.Warn("invalid Authorization header format",
+					"path", r.URL.Path,
+					"remote_addr", r.RemoteAddr,
+				)
+				writeAuthError(w, "invalid Authorization header format")
+				return
+			}
+
+			// Constant-time comparison to prevent timing attacks.
+			if subtle.ConstantTimeCompare([]byte(parts[1]), []byte(token)) != 1 {
+				slog.Warn("invalid auth token",
+					"path", r.URL.Path,
+					"remote_addr", r.RemoteAddr,
+				)
+				writeAuthError(w, "invalid auth token")
+				return
+			}
+
+			next.ServeHTTP(w, r)
+		})
+	}
+}
+
+// writeAuthError writes a JSON-formatted 401 error response.
+func writeAuthError(w http.ResponseWriter, msg string) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(http.StatusUnauthorized)
+	fmt.Fprintf(w, `{"error":%q}`, msg)
+}
diff --git a/enterprise/media-server/internal/callback/rails_client.go b/enterprise/media-server/internal/callback/rails_client.go
new file mode 100644
index 000000000..cb938d760
--- /dev/null
+++ b/enterprise/media-server/internal/callback/rails_client.go
@@ -0,0 +1,138 @@
+// Package callback provides an HTTP client for sending event notifications
+// back to the Chatwoot Rails application.
+package callback
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"log/slog"
+	"net/http"
+	"time"
+)
+
+// RailsClient sends HTTP callbacks to the Rails application to notify it of
+// media server events such as agent disconnection, recording availability,
+// session termination, and errors.
+type RailsClient struct {
+	baseURL   string
+	authToken string
+	client    *http.Client
+}
+
+// NewRailsClient creates a new callback client configured with the Rails base
+// URL and shared authentication token. The HTTP client uses a 10-second
+// timeout to avoid blocking the media server on slow Rails responses.
+func NewRailsClient(baseURL, authToken string) *RailsClient {
+	return &RailsClient{
+		baseURL:   baseURL,
+		authToken: authToken,
+		client: &http.Client{
+			Timeout: 10 * time.Second,
+		},
+	}
+}
+
+// AgentDisconnectedPayload is the request body sent when an agent's peer
+// connection drops unexpectedly.
+type AgentDisconnectedPayload struct {
+	SessionID string `json:"session_id"`
+	CallID    string `json:"call_id"`
+	Reason    string `json:"reason"`
+}
+
+// RecordingReadyPayload is the request body sent when a call recording has
+// been finalized and is available for download.
+type RecordingReadyPayload struct {
+	SessionID      string `json:"session_id"`
+	CallID         string `json:"call_id"`
+	FilePath       string `json:"file_path"`
+	DurationSec    int    `json:"duration_seconds"`
+	FileSizeBytes  int64  `json:"file_size_bytes"`
+}
+
+// SessionTerminatedPayload is the request body sent when a call session has
+// been fully terminated and cleaned up.
+type SessionTerminatedPayload struct {
+	SessionID   string `json:"session_id"`
+	CallID      string `json:"call_id"`
+	Reason      string `json:"reason"`
+	DurationSec int    `json:"duration_seconds"`
+}
+
+// ErrorPayload is the request body sent when the media server encounters
+// an error that the Rails application should be aware of.
+type ErrorPayload struct {
+	SessionID string `json:"session_id"`
+	CallID    string `json:"call_id"`
+	Error     string `json:"error"`
+	Code      string `json:"code"`
+}
+
+// NotifyAgentDisconnected informs Rails that an agent's WebRTC peer connection
+// has dropped. Rails can then start the reconnection timer and update the call
+// status accordingly.
+func (c *RailsClient) NotifyAgentDisconnected(ctx context.Context, payload AgentDisconnectedPayload) error {
+	return c.post(ctx, "/callbacks/media_server/agent_disconnected", payload)
+}
+
+// NotifyRecordingReady informs Rails that a call recording has been finalized
+// and is available for download via the GET /sessions/:id/recording endpoint.
+// Rails should enqueue a job to fetch and attach the recording to ActiveStorage.
+func (c *RailsClient) NotifyRecordingReady(ctx context.Context, payload RecordingReadyPayload) error {
+	return c.post(ctx, "/callbacks/media_server/recording_ready", payload)
+}
+
+// NotifySessionTerminated informs Rails that a call session has ended. This
+// is sent after both peer connections are closed and the recording is finalized.
+func (c *RailsClient) NotifySessionTerminated(ctx context.Context, payload SessionTerminatedPayload) error {
+	return c.post(ctx, "/callbacks/media_server/session_terminated", payload)
+}
+
+// NotifyError informs Rails of a media server error that may require attention,
+// such as a failed ICE negotiation or recording write failure.
+func (c *RailsClient) NotifyError(ctx context.Context, payload ErrorPayload) error {
+	return c.post(ctx, "/callbacks/media_server/error", payload)
+}
+
+func (c *RailsClient) post(ctx context.Context, path string, payload any) error {
+	body, err := json.Marshal(payload)
+	if err != nil {
+		return fmt.Errorf("marshal callback payload: %w", err)
+	}
+
+	url := c.baseURL + path
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(body))
+	if err != nil {
+		return fmt.Errorf("create callback request: %w", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+	if c.authToken != "" {
+		req.Header.Set("Authorization", "Bearer "+c.authToken)
+	}
+
+	resp, err := c.client.Do(req)
+	if err != nil {
+		slog.Error("callback request failed",
+			"url", url,
+			"error", err,
+		)
+		return fmt.Errorf("callback request to %s: %w", path, err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode >= 400 {
+		slog.Error("callback returned error status",
+			"url", url,
+			"status", resp.StatusCode,
+		)
+		return fmt.Errorf("callback to %s returned status %d", path, resp.StatusCode)
+	}
+
+	slog.Debug("callback sent successfully",
+		"url", url,
+		"status", resp.StatusCode,
+	)
+	return nil
+}
diff --git a/enterprise/media-server/internal/config/config.go b/enterprise/media-server/internal/config/config.go
new file mode 100644
index 000000000..0b779300b
--- /dev/null
+++ b/enterprise/media-server/internal/config/config.go
@@ -0,0 +1,197 @@
+// Package config provides environment-based configuration for the media server.
+package config
+
+import (
+	"fmt"
+	"os"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// Config holds all configuration values for the media server, loaded from
+// environment variables at startup. Sensible defaults are provided for
+// development; production deployments should set AUTH_TOKEN and RAILS_CALLBACK_URL
+// at a minimum.
+type Config struct {
+	// AuthToken is the shared secret used for Bearer token authentication
+	// between Rails and the media server. Required in production.
+	AuthToken string
+
+	// RailsCallbackURL is the base URL for HTTP callbacks to the Rails app
+	// (e.g., "http://rails:3000").
+	RailsCallbackURL string
+
+	// STUNServers is a list of STUN server URLs for ICE candidate gathering.
+	STUNServers []string
+
+	// TURNServers is a list of TURN server URLs for relay candidates.
+	TURNServers []string
+
+	// TURNUsername is the credential username for TURN servers.
+	TURNUsername string
+
+	// TURNPassword is the credential password for TURN servers.
+	TURNPassword string
+
+	// PublicIP is the server's public IP address used for ICE candidate
+	// generation via NAT1To1IPs. Leave empty to rely on STUN discovery.
+	PublicIP string
+
+	// UDPPortMin is the lower bound of the ephemeral UDP port range used
+	// for WebRTC media transport.
+	UDPPortMin uint16
+
+	// UDPPortMax is the upper bound of the ephemeral UDP port range.
+	UDPPortMax uint16
+
+	// RecordingsDir is the filesystem path where call recordings are stored.
+	RecordingsDir string
+
+	// HTTPPort is the port on which the HTTP API listens.
+	HTTPPort int
+
+	// LogLevel controls the verbosity of structured logging.
+	// Valid values: "debug", "info", "warn", "error".
+	LogLevel string
+
+	// MaxSessionDuration is the maximum allowed duration for a single call
+	// session before automatic termination.
+	MaxSessionDuration time.Duration
+
+	// ReconnectTimeout is the duration the server waits for an agent to
+	// reconnect after their peer connection drops before terminating the call.
+	ReconnectTimeout time.Duration
+
+	// MaxConcurrentSessions limits the total number of active sessions across
+	// all accounts. Zero means unlimited.
+	MaxConcurrentSessions int
+}
+
+// Load reads configuration from environment variables and returns a validated
+// Config. It returns an error if any required value is missing or invalid.
+func Load() (*Config, error) {
+	cfg := &Config{
+		AuthToken:        getEnv("AUTH_TOKEN", ""),
+		RailsCallbackURL: getEnv("RAILS_CALLBACK_URL", "http://localhost:3000"),
+		TURNUsername:     getEnv("TURN_USERNAME", ""),
+		TURNPassword:     getEnv("TURN_PASSWORD", ""),
+		PublicIP:         getEnv("PUBLIC_IP", ""),
+		RecordingsDir:    getEnv("RECORDINGS_DIR", "/recordings"),
+		LogLevel:         getEnv("LOG_LEVEL", "info"),
+	}
+
+	// Parse STUN servers (comma-separated).
+	stunStr := getEnv("STUN_SERVERS", "stun:stun.l.google.com:19302")
+	if stunStr != "" {
+		cfg.STUNServers = splitAndTrim(stunStr)
+	}
+
+	// Parse TURN servers (comma-separated).
+	turnStr := getEnv("TURN_SERVERS", "")
+	if turnStr != "" {
+		cfg.TURNServers = splitAndTrim(turnStr)
+	}
+
+	// Parse UDP port range.
+	portMin, err := getEnvUint16("UDP_PORT_MIN", 10000)
+	if err != nil {
+		return nil, fmt.Errorf("invalid UDP_PORT_MIN: %w", err)
+	}
+	cfg.UDPPortMin = portMin
+
+	portMax, err := getEnvUint16("UDP_PORT_MAX", 12000)
+	if err != nil {
+		return nil, fmt.Errorf("invalid UDP_PORT_MAX: %w", err)
+	}
+	cfg.UDPPortMax = portMax
+
+	if cfg.UDPPortMin >= cfg.UDPPortMax {
+		return nil, fmt.Errorf("UDP_PORT_MIN (%d) must be less than UDP_PORT_MAX (%d)", cfg.UDPPortMin, cfg.UDPPortMax)
+	}
+
+	// Parse HTTP port.
+	httpPort, err := getEnvInt("HTTP_PORT", 4000)
+	if err != nil {
+		return nil, fmt.Errorf("invalid HTTP_PORT: %w", err)
+	}
+	cfg.HTTPPort = httpPort
+
+	// Parse max session duration.
+	maxDur, err := getEnvInt("MAX_SESSION_DURATION", 7200)
+	if err != nil {
+		return nil, fmt.Errorf("invalid MAX_SESSION_DURATION: %w", err)
+	}
+	cfg.MaxSessionDuration = time.Duration(maxDur) * time.Second
+
+	// Parse reconnect timeout.
+	reconTimeout, err := getEnvInt("RECONNECT_TIMEOUT", 30)
+	if err != nil {
+		return nil, fmt.Errorf("invalid RECONNECT_TIMEOUT: %w", err)
+	}
+	cfg.ReconnectTimeout = time.Duration(reconTimeout) * time.Second
+
+	// Parse max concurrent sessions.
+	maxSessions, err := getEnvInt("MAX_CONCURRENT_SESSIONS", 0)
+	if err != nil {
+		return nil, fmt.Errorf("invalid MAX_CONCURRENT_SESSIONS: %w", err)
+	}
+	cfg.MaxConcurrentSessions = maxSessions
+
+	return cfg, nil
+}
+
+// Validate checks that required configuration values are set for production
+// use. It returns a list of warnings for missing optional values.
+func (c *Config) Validate() []string {
+	var warnings []string
+	if c.AuthToken == "" {
+		warnings = append(warnings, "AUTH_TOKEN is not set; all API requests will be unauthenticated")
+	}
+	if c.RailsCallbackURL == "" {
+		warnings = append(warnings, "RAILS_CALLBACK_URL is not set; callbacks to Rails will fail")
+	}
+	if len(c.STUNServers) == 0 {
+		warnings = append(warnings, "No STUN servers configured; ICE candidate gathering may fail")
+	}
+	return warnings
+}
+
+func getEnv(key, defaultVal string) string {
+	if val := os.Getenv(key); val != "" {
+		return val
+	}
+	return defaultVal
+}
+
+func getEnvInt(key string, defaultVal int) (int, error) {
+	str := os.Getenv(key)
+	if str == "" {
+		return defaultVal, nil
+	}
+	return strconv.Atoi(str)
+}
+
+func getEnvUint16(key string, defaultVal uint16) (uint16, error) {
+	str := os.Getenv(key)
+	if str == "" {
+		return defaultVal, nil
+	}
+	v, err := strconv.ParseUint(str, 10, 16)
+	if err != nil {
+		return 0, err
+	}
+	return uint16(v), nil
+}
+
+func splitAndTrim(s string) []string {
+	parts := strings.Split(s, ",")
+	result := make([]string, 0, len(parts))
+	for _, p := range parts {
+		trimmed := strings.TrimSpace(p)
+		if trimmed != "" {
+			result = append(result, trimmed)
+		}
+	}
+	return result
+}
diff --git a/enterprise/media-server/internal/media/bridge.go b/enterprise/media-server/internal/media/bridge.go
new file mode 100644
index 000000000..5b6bb19a9
--- /dev/null
+++ b/enterprise/media-server/internal/media/bridge.go
@@ -0,0 +1,323 @@
+package media
+
+import (
+	"context"
+	"log/slog"
+	"sync"
+
+	"github.com/pion/rtp"
+	"github.com/pion/webrtc/v4"
+
+	"github.com/chatwoot/chatwoot-media-server/internal/peer"
+)
+
+// AudioConsumer is an interface for components that want to receive audio
+// frames from the bridge, such as real-time transcription or AI services.
+type AudioConsumer interface {
+	// OnAudioFrame is called for each RTP packet passing through the bridge.
+	// source is either "customer" or "agent".
+	OnAudioFrame(sessionID, source string, packet *rtp.Packet)
+}
+
+// Bridge connects two WebRTC peers (Meta-side and Agent-side) by forwarding
+// RTP audio packets between them. It also taps into both audio streams for
+// recording and external consumers.
+type Bridge struct {
+	sessionID  string
+	metaPeer   *peer.MetaPeer
+	agentPeers map[string]*peer.AgentPeer
+	recorder   *Recorder
+	consumers  []AudioConsumer
+
+	cancel context.CancelFunc
+	mu     sync.RWMutex
+	active bool
+}
+
+// NewBridge creates a new audio bridge for the given session. The bridge does
+// not start forwarding automatically; call Start after both peers are connected.
+func NewBridge(sessionID string, metaPeer *peer.MetaPeer, recorder *Recorder) *Bridge {
+	return &Bridge{
+		sessionID:  sessionID,
+		metaPeer:   metaPeer,
+		agentPeers: make(map[string]*peer.AgentPeer),
+		recorder:   recorder,
+	}
+}
+
+// AddAgentPeer registers an agent peer with the bridge. If the bridge is
+// already running, forwarding to the new peer begins immediately.
+func (b *Bridge) AddAgentPeer(ap *peer.AgentPeer) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+
+	b.agentPeers[ap.ID] = ap
+	slog.Info("bridge: agent peer added",
+		"session_id", b.sessionID,
+		"peer_id", ap.ID,
+		"role", string(ap.Role),
+	)
+}
+
+// RemoveAgentPeer removes an agent peer from the bridge. Its forwarding
+// goroutines will terminate when the peer's tracks are closed.
+func (b *Bridge) RemoveAgentPeer(peerID string) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+
+	delete(b.agentPeers, peerID)
+	slog.Info("bridge: agent peer removed",
+		"session_id", b.sessionID,
+		"peer_id", peerID,
+	)
+}
+
+// AddConsumer registers an AudioConsumer that receives copies of all audio
+// packets passing through the bridge.
+func (b *Bridge) AddConsumer(c AudioConsumer) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	b.consumers = append(b.consumers, c)
+}
+
+// Start begins forwarding audio between the Meta peer and all agent peers.
+// It spawns goroutines for each direction of audio flow. The bridge runs
+// until Stop is called or the provided context is cancelled.
+func (b *Bridge) Start(ctx context.Context) {
+	b.mu.Lock()
+	if b.active {
+		b.mu.Unlock()
+		return
+	}
+	b.active = true
+	ctx, b.cancel = context.WithCancel(ctx)
+	b.mu.Unlock()
+
+	slog.Info("bridge: started", "session_id", b.sessionID)
+
+	// Forward Meta audio (customer) to all agent peers.
+	go b.forwardMetaToAgents(ctx)
+
+	// For each agent peer, forward their audio to Meta.
+	b.mu.RLock()
+	for _, ap := range b.agentPeers {
+		go b.forwardAgentToMeta(ctx, ap)
+	}
+	b.mu.RUnlock()
+}
+
+// StartAgentForwarding begins forwarding a specific agent peer's audio to
+// Meta. This is used when a new agent peer is added after the bridge has
+// already started.
+func (b *Bridge) StartAgentForwarding(ctx context.Context, ap *peer.AgentPeer) {
+	b.mu.RLock()
+	active := b.active
+	b.mu.RUnlock()
+
+	if !active {
+		return
+	}
+
+	go b.forwardAgentToMeta(ctx, ap)
+}
+
+// Stop halts all audio forwarding and finalizes the recording. This method
+// is idempotent.
+func (b *Bridge) Stop() {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+
+	if !b.active {
+		return
+	}
+	b.active = false
+
+	if b.cancel != nil {
+		b.cancel()
+	}
+
+	slog.Info("bridge: stopped", "session_id", b.sessionID)
+}
+
+// IsActive returns whether the bridge is currently forwarding audio.
+func (b *Bridge) IsActive() bool {
+	b.mu.RLock()
+	defer b.mu.RUnlock()
+	return b.active
+}
+
+// forwardMetaToAgents reads RTP packets from the Meta peer's remote audio
+// track (customer audio) and writes them to every connected agent peer's
+// local track. Each packet is also sent to the recorder and any consumers.
+func (b *Bridge) forwardMetaToAgents(ctx context.Context) {
+	metaTrack := b.metaPeer.AudioTrack()
+	if metaTrack == nil {
+		slog.Warn("bridge: Meta audio track not yet available, waiting via OnTrack",
+			"session_id", b.sessionID,
+		)
+		// The track will be set via OnTrack callback. We wait for the track
+		// by polling with a channel. In production, the OnTrack callback
+		// mechanism in the session handles this coordination.
+		return
+	}
+
+	b.readAndForwardMetaTrack(ctx, metaTrack)
+}
+
+// ReadAndForwardMetaTrack is the core loop that reads from a Meta remote
+// track and fans out to agent peers. It is exported so the session layer can
+// call it directly from the OnTrack callback.
+func (b *Bridge) ReadAndForwardMetaTrack(ctx context.Context, track *webrtc.TrackRemote) {
+	b.readAndForwardMetaTrack(ctx, track)
+}
+
+func (b *Bridge) readAndForwardMetaTrack(ctx context.Context, track *webrtc.TrackRemote) {
+	slog.Info("bridge: forwarding Meta audio to agents",
+		"session_id", b.sessionID,
+		"codec", track.Codec().MimeType,
+	)
+
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		default:
+		}
+
+		pkt, _, readErr := track.ReadRTP()
+		if readErr != nil {
+			slog.Debug("bridge: Meta track read ended",
+				"session_id", b.sessionID,
+				"error", readErr,
+			)
+			return
+		}
+
+		// Record customer audio.
+		if b.recorder != nil {
+			if err := b.recorder.WriteCustomerRTP(pkt); err != nil {
+				slog.Warn("bridge: failed to record customer audio",
+					"session_id", b.sessionID,
+					"error", err,
+				)
+			}
+		}
+
+		// Notify consumers.
+		b.mu.RLock()
+		for _, c := range b.consumers {
+			c.OnAudioFrame(b.sessionID, "customer", pkt)
+		}
+		b.mu.RUnlock()
+
+		// Fan-out to all agent peers.
+		b.mu.RLock()
+		for _, ap := range b.agentPeers {
+			if ap.Role == peer.RoleInjectOnly {
+				continue // inject-only peers do not receive audio
+			}
+			raw, marshalErr := pkt.Marshal()
+			if marshalErr != nil {
+				slog.Warn("bridge: failed to marshal RTP packet",
+					"session_id", b.sessionID,
+					"error", marshalErr,
+				)
+				continue
+			}
+			if _, writeErr := ap.LocalTrack().Write(raw); writeErr != nil {
+				slog.Debug("bridge: failed to write to agent peer",
+					"session_id", b.sessionID,
+					"peer_id", ap.ID,
+					"error", writeErr,
+				)
+			}
+		}
+		b.mu.RUnlock()
+	}
+}
+
+// forwardAgentToMeta reads RTP packets from an agent peer's remote audio
+// track (agent microphone) and writes them to the Meta peer's local track.
+func (b *Bridge) forwardAgentToMeta(ctx context.Context, ap *peer.AgentPeer) {
+	agentTrack := ap.AudioTrack()
+	if agentTrack == nil {
+		slog.Debug("bridge: agent audio track not yet available, waiting via OnTrack",
+			"session_id", b.sessionID,
+			"peer_id", ap.ID,
+		)
+		return
+	}
+
+	b.readAndForwardAgentTrack(ctx, ap, agentTrack)
+}
+
+// ReadAndForwardAgentTrack is the core loop that reads from an agent's remote
+// track and forwards to Meta. Exported so the session layer can call it from
+// the OnTrack callback.
+func (b *Bridge) ReadAndForwardAgentTrack(ctx context.Context, ap *peer.AgentPeer, track *webrtc.TrackRemote) {
+	b.readAndForwardAgentTrack(ctx, ap, track)
+}
+
+func (b *Bridge) readAndForwardAgentTrack(ctx context.Context, ap *peer.AgentPeer, track *webrtc.TrackRemote) {
+	slog.Info("bridge: forwarding agent audio to Meta",
+		"session_id", b.sessionID,
+		"peer_id", ap.ID,
+		"codec", track.Codec().MimeType,
+	)
+
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		default:
+		}
+
+		pkt, _, readErr := track.ReadRTP()
+		if readErr != nil {
+			slog.Debug("bridge: agent track read ended",
+				"session_id", b.sessionID,
+				"peer_id", ap.ID,
+				"error", readErr,
+			)
+			return
+		}
+
+		// Only active peers send audio to Meta.
+		if ap.Role != peer.RoleActive {
+			continue
+		}
+
+		// Record agent audio.
+		if b.recorder != nil {
+			if err := b.recorder.WriteAgentRTP(pkt); err != nil {
+				slog.Warn("bridge: failed to record agent audio",
+					"session_id", b.sessionID,
+					"error", err,
+				)
+			}
+		}
+
+		// Notify consumers.
+		b.mu.RLock()
+		for _, c := range b.consumers {
+			c.OnAudioFrame(b.sessionID, "agent", pkt)
+		}
+		b.mu.RUnlock()
+
+		// Forward to Meta.
+		raw, marshalErr := pkt.Marshal()
+		if marshalErr != nil {
+			slog.Warn("bridge: failed to marshal agent RTP packet",
+				"session_id", b.sessionID,
+				"error", marshalErr,
+			)
+			continue
+		}
+		if _, writeErr := b.metaPeer.LocalTrack().Write(raw); writeErr != nil {
+			slog.Debug("bridge: failed to write to Meta peer",
+				"session_id", b.sessionID,
+				"error", writeErr,
+			)
+		}
+	}
+}
diff --git a/enterprise/media-server/internal/media/injector.go b/enterprise/media-server/internal/media/injector.go
new file mode 100644
index 000000000..9ecfd9c42
--- /dev/null
+++ b/enterprise/media-server/internal/media/injector.go
@@ -0,0 +1,189 @@
+package media
+
+import (
+	"fmt"
+	"io"
+	"log/slog"
+	"os"
+	"sync"
+	"time"
+
+	"github.com/pion/rtp"
+	"github.com/pion/webrtc/v4/pkg/media/oggreader"
+)
+
+// Injector reads Opus frames from an OGG file and injects them into an RTP
+// stream at the correct 20ms pacing interval. This is used for hold music,
+// announcements, and other pre-recorded audio injection.
+type Injector struct {
+	ID     string
+	Source string // file path of the OGG/Opus file
+	Mode   string // "replace" or "mix"
+	Loop   bool
+	Target string // "meta", "agents", or "all"
+
+	stopCh chan struct{}
+	mu     sync.Mutex
+	active bool
+}
+
+// InjectorTarget is a writable RTP destination.
+type InjectorTarget interface {
+	Write(b []byte) (n int, err error)
+}
+
+// NewInjector creates a new audio injector configured with the given source
+// file and injection parameters.
+func NewInjector(id, source, mode, target string, loop bool) *Injector {
+	return &Injector{
+		ID:     id,
+		Source: source,
+		Mode:   mode,
+		Loop:   loop,
+		Target: target,
+		stopCh: make(chan struct{}),
+	}
+}
+
+// Start begins reading the OGG file and injecting Opus frames into the target
+// track at 20ms intervals. It runs in its own goroutine and returns immediately.
+// The injection stops when Stop is called, the file ends (if Loop is false),
+// or an error occurs.
+func (inj *Injector) Start(target InjectorTarget) error {
+	inj.mu.Lock()
+	if inj.active {
+		inj.mu.Unlock()
+		return fmt.Errorf("injector %s is already active", inj.ID)
+	}
+	inj.active = true
+	inj.stopCh = make(chan struct{}) // fresh channel for each start cycle
+	inj.mu.Unlock()
+
+	go inj.run(target)
+	return nil
+}
+
+// Stop halts the audio injection. This method is safe to call multiple times.
+func (inj *Injector) Stop() {
+	inj.mu.Lock()
+	defer inj.mu.Unlock()
+
+	if !inj.active {
+		return
+	}
+	inj.active = false
+	close(inj.stopCh)
+
+	slog.Info("injector: stopped", "id", inj.ID)
+}
+
+// IsActive returns whether the injector is currently running.
+func (inj *Injector) IsActive() bool {
+	inj.mu.Lock()
+	defer inj.mu.Unlock()
+	return inj.active
+}
+
+func (inj *Injector) run(target InjectorTarget) {
+	defer func() {
+		inj.mu.Lock()
+		inj.active = false
+		inj.mu.Unlock()
+	}()
+
+	slog.Info("injector: started",
+		"id", inj.ID,
+		"source", inj.Source,
+		"mode", inj.Mode,
+		"loop", inj.Loop,
+	)
+
+	for {
+		if err := inj.playFile(target); err != nil {
+			slog.Error("injector: playback error",
+				"id", inj.ID,
+				"error", err,
+			)
+			return
+		}
+
+		if !inj.Loop {
+			slog.Info("injector: playback complete (no loop)", "id", inj.ID)
+			return
+		}
+
+		// Check stop signal between loops.
+		select {
+		case <-inj.stopCh:
+			return
+		default:
+		}
+	}
+}
+
+func (inj *Injector) playFile(target InjectorTarget) error {
+	f, err := os.Open(inj.Source)
+	if err != nil {
+		return fmt.Errorf("open source file: %w", err)
+	}
+	defer f.Close()
+
+	ogg, _, err := oggreader.NewWith(f)
+	if err != nil {
+		return fmt.Errorf("create OGG reader: %w", err)
+	}
+
+	// Opus frames are 20ms at 48kHz = 960 samples per frame.
+	const opusFrameDuration = 20 * time.Millisecond
+	ticker := time.NewTicker(opusFrameDuration)
+	defer ticker.Stop()
+
+	var sequenceNumber uint16
+	var timestamp uint32
+
+	for {
+		select {
+		case <-inj.stopCh:
+			return nil
+		case <-ticker.C:
+		}
+
+		pageData, _, err := ogg.ParseNextPage()
+		if err != nil {
+			if err == io.EOF {
+				return nil
+			}
+			return fmt.Errorf("parse OGG page: %w", err)
+		}
+
+		// Build an RTP packet with the Opus payload.
+		pkt := &rtp.Packet{
+			Header: rtp.Header{
+				Version:        2,
+				PayloadType:    111, // Opus dynamic payload type
+				SequenceNumber: sequenceNumber,
+				Timestamp:      timestamp,
+				SSRC:           12345678, // fixed SSRC for injected audio
+			},
+			Payload: pageData,
+		}
+		sequenceNumber++
+		timestamp += 960 // 48kHz * 0.02s
+
+		raw, marshalErr := pkt.Marshal()
+		if marshalErr != nil {
+			slog.Warn("injector: failed to marshal RTP packet",
+				"id", inj.ID,
+				"error", marshalErr,
+			)
+			continue
+		}
+
+		if _, writeErr := target.Write(raw); writeErr != nil {
+			slog.Debug("injector: write failed",
+				"id", inj.ID,
+				"error", writeErr,
+			)
+		}
+	}
+}
diff --git a/enterprise/media-server/internal/media/recorder.go b/enterprise/media-server/internal/media/recorder.go
new file mode 100644
index 000000000..f759fc8f3
--- /dev/null
+++ b/enterprise/media-server/internal/media/recorder.go
@@ -0,0 +1,208 @@
+// Package media provides audio bridging, recording, and injection capabilities
+// for the media server's call sessions.
+package media
+
+import (
+	"fmt"
+	"log/slog"
+	"os"
+	"path/filepath"
+	"sync"
+	"time"
+
+	"github.com/pion/rtp"
+	"github.com/pion/webrtc/v4/pkg/media/oggwriter"
+)
+
+// Recorder writes incoming Opus RTP packets to an OGG container file in real
+// time. Two separate OGG files are maintained -- one for each audio channel
+// (customer and agent) -- to enable stereo separation for transcription.
+// A combined mono file is also written for playback convenience.
+type Recorder struct {
+	sessionID string
+	dir       string
+
+	// combinedWriter writes all audio to a single OGG file (for playback).
+	combinedWriter *oggwriter.OggWriter
+	combinedFile   string
+
+	// customerWriter writes only customer audio (for transcription L channel).
+	customerWriter *oggwriter.OggWriter
+	customerFile   string
+
+	// agentWriter writes only agent audio (for transcription R channel).
+	agentWriter *oggwriter.OggWriter
+	agentFile   string
+
+	startedAt time.Time
+	finalized bool
+	mu        sync.Mutex
+}
+
+// NewRecorder creates a new recorder that writes OGG/Opus files to the given
+// directory. Three files are created:
+//   - {sessionID}.ogg (combined audio for playback)
+//   - {sessionID}_customer.ogg (customer channel only)
+//   - {sessionID}_agent.ogg (agent channel only)
+func NewRecorder(sessionID, dir string) (*Recorder, error) {
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		return nil, fmt.Errorf("create recordings directory: %w", err)
+	}
+
+	combinedFile := filepath.Join(dir, sessionID+".ogg")
+	customerFile := filepath.Join(dir, sessionID+"_customer.ogg")
+	agentFile := filepath.Join(dir, sessionID+"_agent.ogg")
+
+	// Opus at 48kHz, mono for each individual channel.
+	combinedWriter, err := oggwriter.New(combinedFile, 48000, 1)
+	if err != nil {
+		return nil, fmt.Errorf("create combined OGG writer: %w", err)
+	}
+
+	customerWriter, err := oggwriter.New(customerFile, 48000, 1)
+	if err != nil {
+		combinedWriter.Close()
+		return nil, fmt.Errorf("create customer OGG writer: %w", err)
+	}
+
+	agentWriter, err := oggwriter.New(agentFile, 48000, 1)
+	if err != nil {
+		combinedWriter.Close()
+		customerWriter.Close()
+		return nil, fmt.Errorf("create agent OGG writer: %w", err)
+	}
+
+	slog.Info("recorder: started",
+		"session_id", sessionID,
+		"combined_file", combinedFile,
+	)
+
+	return &Recorder{
+		sessionID:      sessionID,
+		dir:            dir,
+		combinedWriter: combinedWriter,
+		combinedFile:   combinedFile,
+		customerWriter: customerWriter,
+		customerFile:   customerFile,
+		agentWriter:    agentWriter,
+		agentFile:      agentFile,
+		startedAt:      time.Now(),
+	}, nil
+}
+
+// WriteCustomerRTP writes an RTP packet from the customer's audio stream
+// (Meta-side, Peer A) to the recording. The packet is written to both the
+// combined file and the customer-only channel file.
+func (r *Recorder) WriteCustomerRTP(pkt *rtp.Packet) error {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	if r.finalized {
+		return nil
+	}
+
+	if err := r.combinedWriter.WriteRTP(pkt); err != nil {
+		return fmt.Errorf("write customer RTP to combined: %w", err)
+	}
+	if err := r.customerWriter.WriteRTP(pkt); err != nil {
+		return fmt.Errorf("write customer RTP to channel: %w", err)
+	}
+	return nil
+}
+
+// WriteAgentRTP writes an RTP packet from the agent's audio stream
+// (browser-side, Peer B) to the recording.
+func (r *Recorder) WriteAgentRTP(pkt *rtp.Packet) error {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	if r.finalized {
+		return nil
+	}
+
+	if err := r.combinedWriter.WriteRTP(pkt); err != nil {
+		return fmt.Errorf("write agent RTP to combined: %w", err)
+	}
+	if err := r.agentWriter.WriteRTP(pkt); err != nil {
+		return fmt.Errorf("write agent RTP to channel: %w", err)
+	}
+	return nil
+}
+
+// Finalize closes all OGG writers and flushes data to disk. After finalization,
+// further writes are silently ignored. This method is idempotent.
+func (r *Recorder) Finalize() error {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	if r.finalized {
+		return nil
+	}
+	r.finalized = true
+
+	var errs []error
+	if err := r.combinedWriter.Close(); err != nil {
+		errs = append(errs, fmt.Errorf("close combined writer: %w", err))
+	}
+	if err := r.customerWriter.Close(); err != nil {
+		errs = append(errs, fmt.Errorf("close customer writer: %w", err))
+	}
+	if err := r.agentWriter.Close(); err != nil {
+		errs = append(errs, fmt.Errorf("close agent writer: %w", err))
+	}
+
+	if len(errs) > 0 {
+		return fmt.Errorf("finalize recorder: %v", errs)
+	}
+
+	slog.Info("recorder: finalized",
+		"session_id", r.sessionID,
+		"duration", time.Since(r.startedAt).Round(time.Second),
+	)
+	return nil
+}
+
+// CombinedFilePath returns the filesystem path of the combined recording file.
+func (r *Recorder) CombinedFilePath() string {
+	return r.combinedFile
+}
+
+// CustomerFilePath returns the filesystem path of the customer-only recording.
+func (r *Recorder) CustomerFilePath() string {
+	return r.customerFile
+}
+
+// AgentFilePath returns the filesystem path of the agent-only recording.
+func (r *Recorder) AgentFilePath() string {
+	return r.agentFile
+}
+
+// Duration returns the elapsed recording time since the recorder was started.
+func (r *Recorder) Duration() time.Duration {
+	return time.Since(r.startedAt)
+}
+
+// FileSize returns the size of the combined recording file in bytes, or -1 on
+// error.
+func (r *Recorder) FileSize() int64 {
+	info, err := os.Stat(r.combinedFile)
+	if err != nil {
+		return -1
+	}
+	return info.Size()
+}
+
+// Cleanup removes all recording files for this session from disk.
+func (r *Recorder) Cleanup() {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	for _, f := range []string{r.combinedFile, r.customerFile, r.agentFile} {
+		if err := os.Remove(f); err != nil && !os.IsNotExist(err) {
+			slog.Warn("recorder: failed to remove file",
+				"file", f,
+				"error", err,
+			)
+		}
+	}
+}
diff --git a/enterprise/media-server/internal/peer/agent_peer.go b/enterprise/media-server/internal/peer/agent_peer.go
new file mode 100644
index 000000000..becc21702
--- /dev/null
+++ b/enterprise/media-server/internal/peer/agent_peer.go
@@ -0,0 +1,236 @@
+package peer
+
+import (
+	"fmt"
+	"log/slog"
+	"sync"
+
+	"github.com/pion/interceptor"
+	"github.com/pion/webrtc/v4"
+
+	"github.com/chatwoot/chatwoot-media-server/internal/config"
+)
+
+// PeerRole defines the role of an agent peer in a call session.
+type PeerRole string
+
+const (
+	// RoleActive indicates the peer sends and receives audio (the primary agent).
+	RoleActive PeerRole = "active"
+
+	// RoleListenOnly indicates the peer receives audio but does not send
+	// (supervisory monitoring).
+	RoleListenOnly PeerRole = "listen_only"
+
+	// RoleInjectOnly indicates the peer sends audio but does not receive
+	// (audio injection source).
+	RoleInjectOnly PeerRole = "inject_only"
+)
+
+// AgentPeer represents the WebRTC peer connection to an agent's browser
+// (Peer B). The media server creates an SDP offer for the agent; the browser
+// responds with an SDP answer to complete the handshake.
+type AgentPeer struct {
+	ID   string
+	Role PeerRole
+
+	pc         *webrtc.PeerConnection
+	audioTrack *webrtc.TrackRemote
+	localTrack *webrtc.TrackLocalStaticRTP
+	sender     *webrtc.RTPSender
+
+	// onTrackReady is called when the agent's audio track becomes available.
+	onTrackReady func(track *webrtc.TrackRemote)
+
+	// onICEStateChange is called when the ICE connection state changes.
+	onICEStateChange func(state webrtc.ICEConnectionState)
+
+	mu     sync.Mutex
+	closed bool
+}
+
+// NewAgentPeer creates a new agent-side peer connection and generates an SDP
+// offer to send to the agent's browser. The browser will respond with an SDP
+// answer via SetAnswer. The returned string is the SDP offer.
+func NewAgentPeer(cfg *config.Config, id string, role PeerRole, iceServers []webrtc.ICEServer) (*AgentPeer, string, error) {
+	se := webrtc.SettingEngine{}
+
+	if err := se.SetEphemeralUDPPortRange(cfg.UDPPortMin, cfg.UDPPortMax); err != nil {
+		return nil, "", fmt.Errorf("set UDP port range: %w", err)
+	}
+
+	// NOTE: In pion/webrtc v4.2+, migrate to SetICEAddressRewriteRules.
+	if cfg.PublicIP != "" {
+		se.SetNAT1To1IPs([]string{cfg.PublicIP}, webrtc.ICECandidateTypeSrflx)
+	}
+
+	me := &webrtc.MediaEngine{}
+	if err := me.RegisterDefaultCodecs(); err != nil {
+		return nil, "", fmt.Errorf("register codecs: %w", err)
+	}
+
+	ir := &interceptor.Registry{}
+	if err := webrtc.RegisterDefaultInterceptors(me, ir); err != nil {
+		return nil, "", fmt.Errorf("register interceptors: %w", err)
+	}
+
+	api := webrtc.NewAPI(
+		webrtc.WithMediaEngine(me),
+		webrtc.WithSettingEngine(se),
+		webrtc.WithInterceptorRegistry(ir),
+	)
+
+	pc, err := api.NewPeerConnection(webrtc.Configuration{
+		ICEServers: iceServers,
+	})
+	if err != nil {
+		return nil, "", fmt.Errorf("create peer connection: %w", err)
+	}
+
+	// Create the local audio track that carries customer audio (from Meta)
+	// to the agent's browser.
+	localTrack, err := webrtc.NewTrackLocalStaticRTP(
+		webrtc.RTPCodecCapability{MimeType: webrtc.MimeTypeOpus},
+		"audio-to-agent",
+		"chatwoot-media-server",
+	)
+	if err != nil {
+		pc.Close()
+		return nil, "", fmt.Errorf("create local track: %w", err)
+	}
+
+	sender, err := pc.AddTrack(localTrack)
+	if err != nil {
+		pc.Close()
+		return nil, "", fmt.Errorf("add local track: %w", err)
+	}
+
+	// Consume RTCP packets from the sender to avoid blocking.
+	go func() {
+		buf := make([]byte, 1500)
+		for {
+			if _, _, rtcpErr := sender.Read(buf); rtcpErr != nil {
+				return
+			}
+		}
+	}()
+
+	ap := &AgentPeer{
+		ID:         id,
+		Role:       role,
+		pc:         pc,
+		localTrack: localTrack,
+		sender:     sender,
+	}
+
+	// Register the OnTrack handler to capture the agent's microphone audio.
+	pc.OnTrack(func(track *webrtc.TrackRemote, receiver *webrtc.RTPReceiver) {
+		slog.Info("agent peer: remote track received",
+			"peer_id", id,
+			"codec", track.Codec().MimeType,
+			"ssrc", track.SSRC(),
+		)
+		ap.mu.Lock()
+		ap.audioTrack = track
+		cb := ap.onTrackReady
+		ap.mu.Unlock()
+
+		if cb != nil {
+			cb(track)
+		}
+	})
+
+	// Register ICE connection state handler.
+	pc.OnICEConnectionStateChange(func(state webrtc.ICEConnectionState) {
+		slog.Info("agent peer: ICE state changed",
+			"peer_id", id,
+			"state", state.String(),
+		)
+		ap.mu.Lock()
+		cb := ap.onICEStateChange
+		ap.mu.Unlock()
+
+		if cb != nil {
+			cb(state)
+		}
+	})
+
+	// Create an SDP offer for the agent's browser.
+	offer, err := pc.CreateOffer(nil)
+	if err != nil {
+		pc.Close()
+		return nil, "", fmt.Errorf("create offer: %w", err)
+	}
+
+	gatherComplete := webrtc.GatheringCompletePromise(pc)
+	if err := pc.SetLocalDescription(offer); err != nil {
+		pc.Close()
+		return nil, "", fmt.Errorf("set local description: %w", err)
+	}
+	<-gatherComplete
+
+	sdpOffer := pc.LocalDescription().SDP
+
+	return ap, sdpOffer, nil
+}
+
+// SetAnswer sets the agent browser's SDP answer on the peer connection,
+// completing the WebRTC handshake.
+func (ap *AgentPeer) SetAnswer(sdpAnswer string) error {
+	ap.mu.Lock()
+	defer ap.mu.Unlock()
+
+	answer := webrtc.SessionDescription{
+		Type: webrtc.SDPTypeAnswer,
+		SDP:  sdpAnswer,
+	}
+	return ap.pc.SetRemoteDescription(answer)
+}
+
+// AudioTrack returns the remote audio track from the agent's browser.
+// Returns nil if the track has not been received yet.
+func (ap *AgentPeer) AudioTrack() *webrtc.TrackRemote {
+	ap.mu.Lock()
+	defer ap.mu.Unlock()
+	return ap.audioTrack
+}
+
+// LocalTrack returns the local RTP track used to send audio to the agent.
+func (ap *AgentPeer) LocalTrack() *webrtc.TrackLocalStaticRTP {
+	return ap.localTrack
+}
+
+// OnTrackReady sets a callback that fires when the agent's microphone audio
+// track becomes available.
+func (ap *AgentPeer) OnTrackReady(fn func(track *webrtc.TrackRemote)) {
+	ap.mu.Lock()
+	defer ap.mu.Unlock()
+	ap.onTrackReady = fn
+}
+
+// OnICEStateChange sets a callback that fires when the ICE connection state
+// changes.
+func (ap *AgentPeer) OnICEStateChange(fn func(state webrtc.ICEConnectionState)) {
+	ap.mu.Lock()
+	defer ap.mu.Unlock()
+	ap.onICEStateChange = fn
+}
+
+// ICEConnectionState returns the current ICE connection state.
+func (ap *AgentPeer) ICEConnectionState() webrtc.ICEConnectionState {
+	return ap.pc.ICEConnectionState()
+}
+
+// Close gracefully shuts down the agent-side peer connection.
+func (ap *AgentPeer) Close() error {
+	ap.mu.Lock()
+	defer ap.mu.Unlock()
+
+	if ap.closed {
+		return nil
+	}
+	ap.closed = true
+
+	slog.Info("agent peer: closing peer connection", "peer_id", ap.ID)
+	return ap.pc.Close()
+}
diff --git a/enterprise/media-server/internal/peer/meta_peer.go b/enterprise/media-server/internal/peer/meta_peer.go
new file mode 100644
index 000000000..878a1410b
--- /dev/null
+++ b/enterprise/media-server/internal/peer/meta_peer.go
@@ -0,0 +1,257 @@
+// Package peer provides WebRTC peer connection wrappers for the two sides
+// of a call: the Meta-side peer (Peer A) and the Agent-side peer (Peer B).
+package peer
+
+import (
+	"fmt"
+	"log/slog"
+	"sync"
+
+	"github.com/pion/interceptor"
+	"github.com/pion/webrtc/v4"
+
+	"github.com/chatwoot/chatwoot-media-server/internal/config"
+)
+
+// MetaPeer represents the WebRTC peer connection to Meta's media servers
+// (Peer A). It receives the customer's audio as an incoming remote track and
+// sends the agent's audio via a local static RTP track.
+type MetaPeer struct {
+	pc         *webrtc.PeerConnection
+	audioTrack *webrtc.TrackRemote
+	localTrack *webrtc.TrackLocalStaticRTP
+	sender     *webrtc.RTPSender
+
+	// onTrackReady is called when the remote audio track from Meta is available.
+	onTrackReady func(track *webrtc.TrackRemote)
+
+	// onICEStateChange is called when the ICE connection state changes.
+	onICEStateChange func(state webrtc.ICEConnectionState)
+
+	mu     sync.Mutex
+	closed bool
+}
+
+// NewMetaPeer creates a new Meta-side peer connection configured for the
+// given ICE servers and UDP port range. For incoming calls, sdpOffer contains
+// Meta's SDP offer; the method sets it as the remote description, creates an
+// answer, and returns the SDP answer string. For outgoing calls, sdpOffer is
+// empty; the method creates an SDP offer to send to Meta.
+func NewMetaPeer(cfg *config.Config, sdpOffer string, iceServers []webrtc.ICEServer) (*MetaPeer, string, error) {
+	se := webrtc.SettingEngine{}
+
+	// Configure the UDP port range for media transport.
+	if err := se.SetEphemeralUDPPortRange(cfg.UDPPortMin, cfg.UDPPortMax); err != nil {
+		return nil, "", fmt.Errorf("set UDP port range: %w", err)
+	}
+
+	// If a public IP is configured, use NAT1To1 so ICE candidates advertise
+	// the correct address instead of a private Docker/container IP.
+	// NOTE: In pion/webrtc v4.2+, migrate to SetICEAddressRewriteRules.
+	if cfg.PublicIP != "" {
+		se.SetNAT1To1IPs([]string{cfg.PublicIP}, webrtc.ICECandidateTypeSrflx)
+	}
+
+	// Build the WebRTC API with a media engine that supports Opus audio.
+	me := &webrtc.MediaEngine{}
+	if err := me.RegisterDefaultCodecs(); err != nil {
+		return nil, "", fmt.Errorf("register codecs: %w", err)
+	}
+
+	// Register default interceptors (NACK, RTCP reports, etc.).
+	ir := &interceptor.Registry{}
+	if err := webrtc.RegisterDefaultInterceptors(me, ir); err != nil {
+		return nil, "", fmt.Errorf("register interceptors: %w", err)
+	}
+
+	api := webrtc.NewAPI(
+		webrtc.WithMediaEngine(me),
+		webrtc.WithSettingEngine(se),
+		webrtc.WithInterceptorRegistry(ir),
+	)
+
+	pc, err := api.NewPeerConnection(webrtc.Configuration{
+		ICEServers: iceServers,
+	})
+	if err != nil {
+		return nil, "", fmt.Errorf("create peer connection: %w", err)
+	}
+
+	// Create a local audio track that will carry the agent's audio to Meta.
+	localTrack, err := webrtc.NewTrackLocalStaticRTP(
+		webrtc.RTPCodecCapability{MimeType: webrtc.MimeTypeOpus},
+		"audio-to-meta",
+		"chatwoot-media-server",
+	)
+	if err != nil {
+		pc.Close()
+		return nil, "", fmt.Errorf("create local track: %w", err)
+	}
+
+	sender, err := pc.AddTrack(localTrack)
+	if err != nil {
+		pc.Close()
+		return nil, "", fmt.Errorf("add local track: %w", err)
+	}
+
+	// Consume RTCP packets from the sender to avoid blocking.
+	go func() {
+		buf := make([]byte, 1500)
+		for {
+			if _, _, rtcpErr := sender.Read(buf); rtcpErr != nil {
+				return
+			}
+		}
+	}()
+
+	mp := &MetaPeer{
+		pc:         pc,
+		localTrack: localTrack,
+		sender:     sender,
+	}
+
+	// Register the OnTrack handler to capture the incoming audio from Meta.
+	pc.OnTrack(func(track *webrtc.TrackRemote, receiver *webrtc.RTPReceiver) {
+		slog.Info("meta peer: remote track received",
+			"codec", track.Codec().MimeType,
+			"ssrc", track.SSRC(),
+		)
+		mp.mu.Lock()
+		mp.audioTrack = track
+		cb := mp.onTrackReady
+		mp.mu.Unlock()
+
+		if cb != nil {
+			cb(track)
+		}
+	})
+
+	// Register ICE connection state handler.
+	pc.OnICEConnectionStateChange(func(state webrtc.ICEConnectionState) {
+		slog.Info("meta peer: ICE state changed", "state", state.String())
+		mp.mu.Lock()
+		cb := mp.onICEStateChange
+		mp.mu.Unlock()
+
+		if cb != nil {
+			cb(state)
+		}
+	})
+
+	// Perform SDP negotiation based on call direction.
+	var sdpResult string
+	if sdpOffer != "" {
+		// Incoming call: Meta sent an offer, we generate an answer.
+		offer := webrtc.SessionDescription{
+			Type: webrtc.SDPTypeOffer,
+			SDP:  sdpOffer,
+		}
+		if err := pc.SetRemoteDescription(offer); err != nil {
+			pc.Close()
+			return nil, "", fmt.Errorf("set remote description (Meta offer): %w", err)
+		}
+
+		answer, err := pc.CreateAnswer(nil)
+		if err != nil {
+			pc.Close()
+			return nil, "", fmt.Errorf("create answer: %w", err)
+		}
+
+		// Wait for ICE gathering to complete before returning the answer.
+		gatherComplete := webrtc.GatheringCompletePromise(pc)
+		if err := pc.SetLocalDescription(answer); err != nil {
+			pc.Close()
+			return nil, "", fmt.Errorf("set local description: %w", err)
+		}
+		<-gatherComplete
+
+		sdpResult = pc.LocalDescription().SDP
+	} else {
+		// Outgoing call: we generate an offer to send to Meta.
+		// Add a recvonly transceiver so Meta knows we expect audio.
+		if _, err := pc.AddTransceiverFromKind(webrtc.RTPCodecTypeAudio, webrtc.RTPTransceiverInit{
+			Direction: webrtc.RTPTransceiverDirectionRecvonly,
+		}); err != nil {
+			pc.Close()
+			return nil, "", fmt.Errorf("add audio transceiver: %w", err)
+		}
+
+		offer, err := pc.CreateOffer(nil)
+		if err != nil {
+			pc.Close()
+			return nil, "", fmt.Errorf("create offer: %w", err)
+		}
+
+		gatherComplete := webrtc.GatheringCompletePromise(pc)
+		if err := pc.SetLocalDescription(offer); err != nil {
+			pc.Close()
+			return nil, "", fmt.Errorf("set local description: %w", err)
+		}
+		<-gatherComplete
+
+		sdpResult = pc.LocalDescription().SDP
+	}
+
+	return mp, sdpResult, nil
+}
+
+// SetRemoteAnswer sets Meta's SDP answer on the peer connection, used for
+// outbound calls when Meta responds with an answer.
+func (mp *MetaPeer) SetRemoteAnswer(sdpAnswer string) error {
+	mp.mu.Lock()
+	defer mp.mu.Unlock()
+
+	answer := webrtc.SessionDescription{
+		Type: webrtc.SDPTypeAnswer,
+		SDP:  sdpAnswer,
+	}
+	return mp.pc.SetRemoteDescription(answer)
+}
+
+// AudioTrack returns the remote audio track from Meta (customer audio).
+// Returns nil if the track has not been received yet.
+func (mp *MetaPeer) AudioTrack() *webrtc.TrackRemote {
+	mp.mu.Lock()
+	defer mp.mu.Unlock()
+	return mp.audioTrack
+}
+
+// LocalTrack returns the local RTP track used to send audio to Meta.
+func (mp *MetaPeer) LocalTrack() *webrtc.TrackLocalStaticRTP {
+	return mp.localTrack
+}
+
+// OnTrackReady sets a callback that fires when the remote audio track from
+// Meta becomes available.
+func (mp *MetaPeer) OnTrackReady(fn func(track *webrtc.TrackRemote)) {
+	mp.mu.Lock()
+	defer mp.mu.Unlock()
+	mp.onTrackReady = fn
+}
+
+// OnICEStateChange sets a callback that fires when the ICE connection state
+// changes.
+func (mp *MetaPeer) OnICEStateChange(fn func(state webrtc.ICEConnectionState)) {
+	mp.mu.Lock()
+	defer mp.mu.Unlock()
+	mp.onICEStateChange = fn
+}
+
+// ICEConnectionState returns the current ICE connection state.
+func (mp *MetaPeer) ICEConnectionState() webrtc.ICEConnectionState {
+	return mp.pc.ICEConnectionState()
+}
+
+// Close gracefully shuts down the Meta-side peer connection.
+func (mp *MetaPeer) Close() error {
+	mp.mu.Lock()
+	defer mp.mu.Unlock()
+
+	if mp.closed {
+		return nil
+	}
+	mp.closed = true
+
+	slog.Info("meta peer: closing peer connection")
+	return mp.pc.Close()
+}
diff --git a/enterprise/media-server/internal/server/handlers.go b/enterprise/media-server/internal/server/handlers.go
new file mode 100644
index 000000000..2b2f23dec
--- /dev/null
+++ b/enterprise/media-server/internal/server/handlers.go
@@ -0,0 +1,662 @@
+package server
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"log/slog"
+	"net/http"
+	"os"
+	"strings"
+	"time"
+
+	"github.com/pion/webrtc/v4"
+
+	"github.com/chatwoot/chatwoot-media-server/internal/config"
+	"github.com/chatwoot/chatwoot-media-server/internal/media"
+	"github.com/chatwoot/chatwoot-media-server/internal/peer"
+	"github.com/chatwoot/chatwoot-media-server/internal/session"
+)
+
+// maxRequestBodySize limits JSON request bodies to 1MB to prevent memory exhaustion.
+const maxRequestBodySize = 1 << 20
+
+// startTime is set at server startup for uptime calculations.
+var startTime = time.Now()
+
+// Handlers implements all HTTP API endpoint handlers for the media server.
+type Handlers struct {
+	cfg     *config.Config
+	manager *session.Manager
+}
+
+// NewHandlers creates a new Handlers instance backed by the given session
+// manager and configuration.
+func NewHandlers(cfg *config.Config, mgr *session.Manager) *Handlers {
+	return &Handlers{cfg: cfg, manager: mgr}
+}
+
+// --- Request/Response types ---
+
+// CreateSessionRequest is the JSON body for POST /sessions.
+type CreateSessionRequest struct {
+	CallID       string              `json:"call_id"`
+	AccountID    string              `json:"account_id"`
+	Direction    string              `json:"direction"`
+	MetaSDPOffer string              `json:"meta_sdp_offer"`
+	ICEServers   []ICEServerConfig   `json:"ice_servers"`
+}
+
+// ICEServerConfig mirrors webrtc.ICEServer for JSON deserialization.
+type ICEServerConfig struct {
+	URLs       []string `json:"urls"`
+	Username   string   `json:"username,omitempty"`
+	Credential string   `json:"credential,omitempty"`
+}
+
+// CreateSessionResponse is the JSON response for POST /sessions.
+type CreateSessionResponse struct {
+	SessionID    string `json:"session_id"`
+	MetaSDPAnswer string `json:"meta_sdp_answer,omitempty"`
+	MetaSDPOffer  string `json:"meta_sdp_offer,omitempty"`
+	Status       string `json:"status"`
+}
+
+// AgentOfferRequest is the JSON body for POST /sessions/:id/agent-offer.
+type AgentOfferRequest struct {
+	PeerID     string            `json:"peer_id"`
+	Role       string            `json:"role"`
+	ICEServers []ICEServerConfig `json:"ice_servers"`
+}
+
+// AgentOfferResponse is the JSON response for POST /sessions/:id/agent-offer.
+type AgentOfferResponse struct {
+	SDPOffer   string            `json:"sdp_offer"`
+	PeerID     string            `json:"peer_id"`
+	ICEServers []ICEServerConfig `json:"ice_servers"`
+}
+
+// AgentAnswerRequest is the JSON body for POST /sessions/:id/agent-answer.
+type AgentAnswerRequest struct {
+	PeerID    string `json:"peer_id"`
+	SDPAnswer string `json:"sdp_answer"`
+}
+
+// AgentAnswerResponse is the JSON response for POST /sessions/:id/agent-answer.
+type AgentAnswerResponse struct {
+	Status    string `json:"status"`
+	Recording bool   `json:"recording"`
+}
+
+// AgentReconnectRequest is the JSON body for POST /sessions/:id/agent-reconnect.
+type AgentReconnectRequest struct {
+	OldPeerID  string            `json:"old_peer_id"`
+	NewPeerID  string            `json:"new_peer_id"`
+	Role       string            `json:"role"`
+	ICEServers []ICEServerConfig `json:"ice_servers"`
+}
+
+// AgentReconnectResponse is the JSON response for POST /sessions/:id/agent-reconnect.
+type AgentReconnectResponse struct {
+	SDPOffer   string            `json:"sdp_offer"`
+	PeerID     string            `json:"peer_id"`
+	ICEServers []ICEServerConfig `json:"ice_servers"`
+}
+
+// TerminateResponse is the JSON response for POST /sessions/:id/terminate.
+type TerminateResponse struct {
+	Status            string `json:"status"`
+	RecordingFile     string `json:"recording_file,omitempty"`
+	RecordingSizeBytes int64 `json:"recording_size_bytes,omitempty"`
+	DurationSeconds   int    `json:"duration_seconds"`
+}
+
+// AddPeerRequest is the JSON body for POST /sessions/:id/peers.
+type AddPeerRequest struct {
+	PeerID     string            `json:"peer_id"`
+	Role       string            `json:"role"`
+	ICEServers []ICEServerConfig `json:"ice_servers"`
+}
+
+// ChangePeerRoleRequest is the JSON body for PATCH /sessions/:id/peers/:peer_id/role.
+type ChangePeerRoleRequest struct {
+	Role string `json:"role"`
+}
+
+// InjectAudioRequest is the JSON body for POST /sessions/:id/inject-audio.
+type InjectAudioRequest struct {
+	ID     string `json:"id"`
+	Source string `json:"source"`
+	Mode   string `json:"mode"`
+	Target string `json:"target"`
+	Loop   bool   `json:"loop"`
+}
+
+// HealthResponse is the JSON response for GET /health.
+type HealthResponse struct {
+	Status         string `json:"status"`
+	ActiveSessions int    `json:"active_sessions"`
+	UptimeSeconds  int    `json:"uptime_seconds"`
+}
+
+// --- Handlers ---
+
+// Health returns the server's health status. This endpoint does not require
+// authentication and is used by container orchestrators for liveness checks.
+func (h *Handlers) Health(w http.ResponseWriter, r *http.Request) {
+	metrics := h.manager.GetMetrics()
+	writeJSON(w, http.StatusOK, HealthResponse{
+		Status:         "ok",
+		ActiveSessions: metrics.ActiveSessions,
+		UptimeSeconds:  int(time.Since(startTime).Seconds()),
+	})
+}
+
+// Metrics returns Prometheus-compatible metrics about the media server.
+func (h *Handlers) Metrics(w http.ResponseWriter, r *http.Request) {
+	writeJSON(w, http.StatusOK, h.manager.GetMetrics())
+}
+
+// CreateSession handles POST /sessions. It creates a new call session with a
+// Meta-side peer connection and returns the SDP answer (for incoming calls)
+// or SDP offer (for outgoing calls).
+func (h *Handlers) CreateSession(w http.ResponseWriter, r *http.Request) {
+	var req CreateSessionRequest
+	if err := readJSON(r, &req); err != nil {
+		writeError(w, http.StatusBadRequest, "invalid request body: "+err.Error())
+		return
+	}
+
+	if req.CallID == "" {
+		writeError(w, http.StatusBadRequest, "call_id is required")
+		return
+	}
+	if req.Direction != "incoming" && req.Direction != "outgoing" {
+		writeError(w, http.StatusBadRequest, "direction must be 'incoming' or 'outgoing'")
+		return
+	}
+
+	iceServers := toWebRTCICEServers(req.ICEServers, h.cfg)
+
+	sess, sdpResult, err := h.manager.CreateSession(req.CallID, req.AccountID, req.Direction, req.MetaSDPOffer, iceServers)
+	if err != nil {
+		slog.Error("handler: failed to create session",
+			"call_id", req.CallID,
+			"error", err,
+		)
+		writeError(w, http.StatusInternalServerError, "failed to create session: "+err.Error())
+		return
+	}
+
+	resp := CreateSessionResponse{
+		SessionID: sess.ID,
+		Status:    string(sess.Status),
+	}
+	if req.Direction == "incoming" {
+		resp.MetaSDPAnswer = sdpResult
+	} else {
+		resp.MetaSDPOffer = sdpResult
+	}
+
+	slog.Info("handler: session created",
+		"session_id", sess.ID,
+		"call_id", req.CallID,
+		"direction", req.Direction,
+	)
+
+	writeJSON(w, http.StatusCreated, resp)
+}
+
+// GetSession handles GET /sessions/{id}. It returns the current status of
+// a call session.
+func (h *Handlers) GetSession(w http.ResponseWriter, r *http.Request) {
+	sessionID := r.PathValue("id")
+	sess := h.manager.GetSession(sessionID)
+	if sess == nil {
+		writeError(w, http.StatusNotFound, "session not found")
+		return
+	}
+	writeJSON(w, http.StatusOK, sess.GetInfo())
+}
+
+// AgentOffer handles POST /sessions/{id}/agent-offer. It creates a new
+// agent-side peer connection and returns the SDP offer to send to the
+// agent's browser.
+func (h *Handlers) AgentOffer(w http.ResponseWriter, r *http.Request) {
+	sessionID := r.PathValue("id")
+	sess := h.manager.GetSession(sessionID)
+	if sess == nil {
+		writeError(w, http.StatusNotFound, "session not found")
+		return
+	}
+
+	var req AgentOfferRequest
+	if err := readJSON(r, &req); err != nil {
+		writeError(w, http.StatusBadRequest, "invalid request body: "+err.Error())
+		return
+	}
+
+	if req.PeerID == "" {
+		req.PeerID = fmt.Sprintf("agent_%d", time.Now().UnixNano())
+	}
+
+	role := peer.RoleActive
+	if req.Role != "" {
+		role = peer.PeerRole(req.Role)
+	}
+
+	iceServers := toWebRTCICEServers(req.ICEServers, h.cfg)
+
+	sdpOffer, err := sess.CreateAgentPeer(req.PeerID, role, iceServers)
+	if err != nil {
+		slog.Error("handler: failed to create agent peer",
+			"session_id", sessionID,
+			"error", err,
+		)
+		writeError(w, http.StatusInternalServerError, "failed to create agent peer: "+err.Error())
+		return
+	}
+
+	slog.Info("handler: agent offer created",
+		"session_id", sessionID,
+		"peer_id", req.PeerID,
+	)
+
+	writeJSON(w, http.StatusOK, AgentOfferResponse{
+		SDPOffer:   sdpOffer,
+		PeerID:     req.PeerID,
+		ICEServers: req.ICEServers,
+	})
+}
+
+// AgentAnswer handles POST /sessions/{id}/agent-answer. It sets the agent's
+// SDP answer on the peer connection, completing the WebRTC handshake and
+// enabling audio bridging.
+func (h *Handlers) AgentAnswer(w http.ResponseWriter, r *http.Request) {
+	sessionID := r.PathValue("id")
+	sess := h.manager.GetSession(sessionID)
+	if sess == nil {
+		writeError(w, http.StatusNotFound, "session not found")
+		return
+	}
+
+	var req AgentAnswerRequest
+	if err := readJSON(r, &req); err != nil {
+		writeError(w, http.StatusBadRequest, "invalid request body: "+err.Error())
+		return
+	}
+
+	if req.SDPAnswer == "" {
+		writeError(w, http.StatusBadRequest, "sdp_answer is required")
+		return
+	}
+	if req.PeerID == "" {
+		writeError(w, http.StatusBadRequest, "peer_id is required")
+		return
+	}
+
+	if err := sess.SetAgentAnswer(req.PeerID, req.SDPAnswer); err != nil {
+		slog.Error("handler: failed to set agent answer",
+			"session_id", sessionID,
+			"peer_id", req.PeerID,
+			"error", err,
+		)
+		writeError(w, http.StatusInternalServerError, "failed to set agent answer: "+err.Error())
+		return
+	}
+
+	slog.Info("handler: agent answer set",
+		"session_id", sessionID,
+		"peer_id", req.PeerID,
+	)
+
+	writeJSON(w, http.StatusOK, AgentAnswerResponse{
+		Status:    "bridged",
+		Recording: true,
+	})
+}
+
+// AgentReconnect handles POST /sessions/{id}/agent-reconnect. It tears down
+// the old agent peer and creates a new one, returning a fresh SDP offer.
+func (h *Handlers) AgentReconnect(w http.ResponseWriter, r *http.Request) {
+	sessionID := r.PathValue("id")
+	sess := h.manager.GetSession(sessionID)
+	if sess == nil {
+		writeError(w, http.StatusNotFound, "session not found")
+		return
+	}
+
+	var req AgentReconnectRequest
+	if err := readJSON(r, &req); err != nil {
+		writeError(w, http.StatusBadRequest, "invalid request body: "+err.Error())
+		return
+	}
+
+	if req.NewPeerID == "" {
+		req.NewPeerID = fmt.Sprintf("agent_%d", time.Now().UnixNano())
+	}
+
+	role := peer.RoleActive
+	if req.Role != "" {
+		role = peer.PeerRole(req.Role)
+	}
+
+	iceServers := toWebRTCICEServers(req.ICEServers, h.cfg)
+
+	sdpOffer, err := sess.ReconnectAgent(req.OldPeerID, req.NewPeerID, role, iceServers)
+	if err != nil {
+		slog.Error("handler: failed to reconnect agent",
+			"session_id", sessionID,
+			"error", err,
+		)
+		writeError(w, http.StatusInternalServerError, "failed to reconnect agent: "+err.Error())
+		return
+	}
+
+	slog.Info("handler: agent reconnect complete",
+		"session_id", sessionID,
+		"old_peer_id", req.OldPeerID,
+		"new_peer_id", req.NewPeerID,
+	)
+
+	writeJSON(w, http.StatusOK, AgentReconnectResponse{
+		SDPOffer:   sdpOffer,
+		PeerID:     req.NewPeerID,
+		ICEServers: req.ICEServers,
+	})
+}
+
+// TerminateSession handles POST /sessions/{id}/terminate. It ends the call,
+// closes all peer connections, and finalizes the recording.
+func (h *Handlers) TerminateSession(w http.ResponseWriter, r *http.Request) {
+	sessionID := r.PathValue("id")
+	sess := h.manager.GetSession(sessionID)
+	if sess == nil {
+		writeError(w, http.StatusNotFound, "session not found")
+		return
+	}
+
+	info := sess.GetInfo()
+	sess.Terminate("api_request")
+
+	resp := TerminateResponse{
+		Status:          "terminated",
+		DurationSeconds: info.DurationSeconds,
+	}
+
+	if sess.Recorder != nil {
+		resp.RecordingFile = sess.RecordingFilePath()
+		resp.RecordingSizeBytes = sess.Recorder.FileSize()
+	}
+
+	slog.Info("handler: session terminated",
+		"session_id", sessionID,
+		"duration", info.DurationSeconds,
+	)
+
+	writeJSON(w, http.StatusOK, resp)
+}
+
+// GetRecording handles GET /sessions/{id}/recording. It serves the combined
+// recording file as a binary OGG download.
+func (h *Handlers) GetRecording(w http.ResponseWriter, r *http.Request) {
+	sessionID := r.PathValue("id")
+	sess := h.manager.GetSession(sessionID)
+	if sess == nil {
+		writeError(w, http.StatusNotFound, "session not found")
+		return
+	}
+
+	filePath := sess.RecordingFilePath()
+	if filePath == "" {
+		writeError(w, http.StatusNotFound, "no recording available")
+		return
+	}
+
+	f, err := os.Open(filePath)
+	if err != nil {
+		writeError(w, http.StatusNotFound, "recording file not found")
+		return
+	}
+	defer f.Close()
+
+	stat, err := f.Stat()
+	if err != nil {
+		writeError(w, http.StatusInternalServerError, "failed to stat recording file")
+		return
+	}
+
+	w.Header().Set("Content-Type", "audio/ogg")
+	w.Header().Set("Content-Disposition", fmt.Sprintf(`attachment; filename="%s.ogg"`, sessionID))
+	http.ServeContent(w, r, filePath, stat.ModTime(), f)
+}
+
+// DeleteSession handles DELETE /sessions/{id}. It terminates the session and
+// removes all associated recording files.
+func (h *Handlers) DeleteSession(w http.ResponseWriter, r *http.Request) {
+	sessionID := r.PathValue("id")
+	if err := h.manager.DeleteSession(sessionID); err != nil {
+		writeError(w, http.StatusNotFound, err.Error())
+		return
+	}
+
+	slog.Info("handler: session deleted", "session_id", sessionID)
+	writeJSON(w, http.StatusOK, map[string]string{"status": "deleted"})
+}
+
+// AddPeer handles POST /sessions/{id}/peers. It adds a new participant peer
+// to an existing session (multi-participant support).
+func (h *Handlers) AddPeer(w http.ResponseWriter, r *http.Request) {
+	sessionID := r.PathValue("id")
+	sess := h.manager.GetSession(sessionID)
+	if sess == nil {
+		writeError(w, http.StatusNotFound, "session not found")
+		return
+	}
+
+	var req AddPeerRequest
+	if err := readJSON(r, &req); err != nil {
+		writeError(w, http.StatusBadRequest, "invalid request body: "+err.Error())
+		return
+	}
+
+	if req.PeerID == "" {
+		req.PeerID = fmt.Sprintf("peer_%d", time.Now().UnixNano())
+	}
+
+	role := peer.RoleActive
+	if req.Role != "" {
+		role = peer.PeerRole(req.Role)
+	}
+
+	iceServers := toWebRTCICEServers(req.ICEServers, h.cfg)
+
+	sdpOffer, err := sess.CreateAgentPeer(req.PeerID, role, iceServers)
+	if err != nil {
+		writeError(w, http.StatusInternalServerError, "failed to add peer: "+err.Error())
+		return
+	}
+
+	writeJSON(w, http.StatusCreated, AgentOfferResponse{
+		SDPOffer:   sdpOffer,
+		PeerID:     req.PeerID,
+		ICEServers: req.ICEServers,
+	})
+}
+
+// RemovePeer handles DELETE /sessions/{id}/peers/{peer_id}. It removes a
+// specific participant from the session.
+func (h *Handlers) RemovePeer(w http.ResponseWriter, r *http.Request) {
+	sessionID := r.PathValue("id")
+	peerID := r.PathValue("peer_id")
+
+	sess := h.manager.GetSession(sessionID)
+	if sess == nil {
+		writeError(w, http.StatusNotFound, "session not found")
+		return
+	}
+
+	if err := sess.RemoveAgentPeer(peerID); err != nil {
+		writeError(w, http.StatusNotFound, err.Error())
+		return
+	}
+
+	writeJSON(w, http.StatusOK, map[string]string{"status": "removed"})
+}
+
+// ChangePeerRole handles PATCH /sessions/{id}/peers/{peer_id}/role. It
+// changes the role of a connected participant.
+func (h *Handlers) ChangePeerRole(w http.ResponseWriter, r *http.Request) {
+	sessionID := r.PathValue("id")
+	peerID := r.PathValue("peer_id")
+
+	sess := h.manager.GetSession(sessionID)
+	if sess == nil {
+		writeError(w, http.StatusNotFound, "session not found")
+		return
+	}
+
+	var req ChangePeerRoleRequest
+	if err := readJSON(r, &req); err != nil {
+		writeError(w, http.StatusBadRequest, "invalid request body: "+err.Error())
+		return
+	}
+
+	if err := sess.ChangeAgentRole(peerID, peer.PeerRole(req.Role)); err != nil {
+		writeError(w, http.StatusNotFound, err.Error())
+		return
+	}
+
+	writeJSON(w, http.StatusOK, map[string]string{"status": "updated", "role": req.Role})
+}
+
+// InjectAudio handles POST /sessions/{id}/inject-audio. It starts playing
+// an audio file into the call's RTP stream.
+func (h *Handlers) InjectAudio(w http.ResponseWriter, r *http.Request) {
+	sessionID := r.PathValue("id")
+	sess := h.manager.GetSession(sessionID)
+	if sess == nil {
+		writeError(w, http.StatusNotFound, "session not found")
+		return
+	}
+
+	var req InjectAudioRequest
+	if err := readJSON(r, &req); err != nil {
+		writeError(w, http.StatusBadRequest, "invalid request body: "+err.Error())
+		return
+	}
+
+	if req.ID == "" {
+		req.ID = fmt.Sprintf("inj_%d", time.Now().UnixNano())
+	}
+	if req.Mode == "" {
+		req.Mode = "replace"
+	}
+	if req.Target == "" {
+		req.Target = "meta"
+	}
+
+	injector := media.NewInjector(req.ID, req.Source, req.Mode, req.Target, req.Loop)
+
+	// Determine the target track based on the target parameter.
+	target := sess.GetInjectorTarget(req.Target)
+	if target == nil {
+		writeError(w, http.StatusBadRequest, "target track not available")
+		return
+	}
+
+	if err := injector.Start(target); err != nil {
+		writeError(w, http.StatusInternalServerError, "failed to start injection: "+err.Error())
+		return
+	}
+
+	sess.AddInjector(req.ID, injector)
+
+	writeJSON(w, http.StatusCreated, map[string]string{
+		"id":     req.ID,
+		"status": "started",
+	})
+}
+
+// StopInjectAudio handles DELETE /sessions/{id}/inject-audio/{inj_id}. It
+// stops an active audio injection.
+func (h *Handlers) StopInjectAudio(w http.ResponseWriter, r *http.Request) {
+	sessionID := r.PathValue("id")
+	injID := r.PathValue("inj_id")
+
+	sess := h.manager.GetSession(sessionID)
+	if sess == nil {
+		writeError(w, http.StatusNotFound, "session not found")
+		return
+	}
+
+	if err := sess.StopInjector(injID); err != nil {
+		writeError(w, http.StatusNotFound, err.Error())
+		return
+	}
+
+	writeJSON(w, http.StatusOK, map[string]string{"status": "stopped"})
+}
+
+// --- Helpers ---
+
+func readJSON(r *http.Request, v any) error {
+	defer r.Body.Close()
+	limited := io.LimitReader(r.Body, maxRequestBodySize)
+	return json.NewDecoder(limited).Decode(v)
+}
+
+func writeJSON(w http.ResponseWriter, status int, v any) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	json.NewEncoder(w).Encode(v)
+}
+
+func writeError(w http.ResponseWriter, status int, msg string) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	json.NewEncoder(w).Encode(map[string]string{"error": msg})
+}
+
+// toWebRTCICEServers converts the request ICE server configs to Pion's
+// ICEServer type, merging with any STUN/TURN servers from the global config.
+func toWebRTCICEServers(reqServers []ICEServerConfig, cfg *config.Config) []webrtc.ICEServer {
+	servers := make([]webrtc.ICEServer, 0, len(reqServers)+2)
+
+	// Add request-provided servers.
+	for _, s := range reqServers {
+		server := webrtc.ICEServer{URLs: s.URLs}
+		if s.Username != "" {
+			server.Username = s.Username
+			server.Credential = s.Credential
+			server.CredentialType = webrtc.ICECredentialTypePassword
+		}
+		servers = append(servers, server)
+	}
+
+	// Add global STUN servers if no STUN was provided in the request.
+	hasSTUN := false
+	for _, s := range reqServers {
+		for _, u := range s.URLs {
+			if strings.HasPrefix(u, "stun:") {
+				hasSTUN = true
+				break
+			}
+		}
+	}
+	if !hasSTUN && len(cfg.STUNServers) > 0 {
+		servers = append(servers, webrtc.ICEServer{URLs: cfg.STUNServers})
+	}
+
+	// Add global TURN servers.
+	if len(cfg.TURNServers) > 0 && cfg.TURNUsername != "" {
+		servers = append(servers, webrtc.ICEServer{
+			URLs:           cfg.TURNServers,
+			Username:       cfg.TURNUsername,
+			Credential:     cfg.TURNPassword,
+			CredentialType: webrtc.ICECredentialTypePassword,
+		})
+	}
+
+	return servers
+}
diff --git a/enterprise/media-server/internal/server/router.go b/enterprise/media-server/internal/server/router.go
new file mode 100644
index 000000000..2ce9a886e
--- /dev/null
+++ b/enterprise/media-server/internal/server/router.go
@@ -0,0 +1,116 @@
+// Package server provides the HTTP API router and handlers for the media server.
+package server
+
+import (
+	"log/slog"
+	"net/http"
+	"strings"
+
+	"github.com/chatwoot/chatwoot-media-server/internal/auth"
+	"github.com/chatwoot/chatwoot-media-server/internal/config"
+	"github.com/chatwoot/chatwoot-media-server/internal/session"
+)
+
+// Router builds the HTTP handler tree with authentication middleware and
+// route matching. It uses the standard library's http.ServeMux for routing.
+type Router struct {
+	handler  *Handlers
+	authToken string
+}
+
+// NewRouter creates a new Router with the given configuration, session
+// manager, and authentication token.
+func NewRouter(cfg *config.Config, mgr *session.Manager) *Router {
+	return &Router{
+		handler:  NewHandlers(cfg, mgr),
+		authToken: cfg.AuthToken,
+	}
+}
+
+// Build constructs and returns the root http.Handler with all routes and
+// middleware applied.
+func (rt *Router) Build() http.Handler {
+	mux := http.NewServeMux()
+
+	// Public endpoints (no auth required).
+	mux.HandleFunc("GET /health", rt.handler.Health)
+
+	// Protected endpoints.
+	authMw := auth.Middleware(rt.authToken)
+
+	// Session CRUD.
+	mux.Handle("POST /sessions", authMw(http.HandlerFunc(rt.handler.CreateSession)))
+	mux.Handle("GET /metrics", authMw(http.HandlerFunc(rt.handler.Metrics)))
+
+	// All session-scoped routes go through a path-parsing handler because
+	// Go 1.22's ServeMux supports {param} patterns.
+	mux.Handle("GET /sessions/{id}", authMw(http.HandlerFunc(rt.handler.GetSession)))
+	mux.Handle("POST /sessions/{id}/agent-offer", authMw(http.HandlerFunc(rt.handler.AgentOffer)))
+	mux.Handle("POST /sessions/{id}/agent-answer", authMw(http.HandlerFunc(rt.handler.AgentAnswer)))
+	mux.Handle("POST /sessions/{id}/agent-reconnect", authMw(http.HandlerFunc(rt.handler.AgentReconnect)))
+	mux.Handle("POST /sessions/{id}/terminate", authMw(http.HandlerFunc(rt.handler.TerminateSession)))
+	mux.Handle("GET /sessions/{id}/recording", authMw(http.HandlerFunc(rt.handler.GetRecording)))
+	mux.Handle("DELETE /sessions/{id}", authMw(http.HandlerFunc(rt.handler.DeleteSession)))
+
+	// Multi-participant peer management.
+	mux.Handle("POST /sessions/{id}/peers", authMw(http.HandlerFunc(rt.handler.AddPeer)))
+	mux.Handle("DELETE /sessions/{id}/peers/{peer_id}", authMw(http.HandlerFunc(rt.handler.RemovePeer)))
+	mux.Handle("PATCH /sessions/{id}/peers/{peer_id}/role", authMw(http.HandlerFunc(rt.handler.ChangePeerRole)))
+
+	// Audio injection.
+	mux.Handle("POST /sessions/{id}/inject-audio", authMw(http.HandlerFunc(rt.handler.InjectAudio)))
+	mux.Handle("DELETE /sessions/{id}/inject-audio/{inj_id}", authMw(http.HandlerFunc(rt.handler.StopInjectAudio)))
+
+	// Wrap the mux with global middleware.
+	var handler http.Handler = mux
+	handler = requestLogger(handler)
+	handler = recoverer(handler)
+
+	return handler
+}
+
+// requestLogger is middleware that logs each HTTP request.
+func requestLogger(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// Skip logging for health checks to reduce noise.
+		if strings.HasPrefix(r.URL.Path, "/health") {
+			next.ServeHTTP(w, r)
+			return
+		}
+
+		rw := &responseWriter{ResponseWriter: w, statusCode: http.StatusOK}
+		next.ServeHTTP(rw, r)
+
+		// Logging is handled inside handlers for better context; this is
+		// a safety net for unlogged requests.
+	})
+}
+
+// recoverer is middleware that catches panics and returns a 500 response
+// instead of crashing the server.
+func recoverer(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		defer func() {
+			if rec := recover(); rec != nil {
+				slog.Error("panic recovered",
+					"panic", rec,
+					"path", r.URL.Path,
+					"method", r.Method,
+				)
+				http.Error(w, `{"error":"internal server error"}`, http.StatusInternalServerError)
+			}
+		}()
+		next.ServeHTTP(w, r)
+	})
+}
+
+// responseWriter wraps http.ResponseWriter to capture the status code.
+type responseWriter struct {
+	http.ResponseWriter
+	statusCode int
+}
+
+func (rw *responseWriter) WriteHeader(code int) {
+	rw.statusCode = code
+	rw.ResponseWriter.WriteHeader(code)
+}
diff --git a/enterprise/media-server/internal/session/manager.go b/enterprise/media-server/internal/session/manager.go
new file mode 100644
index 000000000..d2e66ae73
--- /dev/null
+++ b/enterprise/media-server/internal/session/manager.go
@@ -0,0 +1,292 @@
+package session
+
+import (
+	"fmt"
+	"log/slog"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"time"
+
+	"github.com/pion/webrtc/v4"
+
+	"github.com/chatwoot/chatwoot-media-server/internal/callback"
+	"github.com/chatwoot/chatwoot-media-server/internal/config"
+	"github.com/chatwoot/chatwoot-media-server/internal/peer"
+)
+
+// Manager handles the lifecycle of all call sessions, providing thread-safe
+// creation, lookup, termination, and periodic cleanup of expired sessions.
+type Manager struct {
+	sessions    map[string]*Session
+	config      *config.Config
+	railsClient *callback.RailsClient
+
+	mu              sync.RWMutex
+	sessionCounter  atomic.Int64
+	cleanupTicker   *time.Ticker
+	cleanupStopCh   chan struct{}
+}
+
+// Metrics holds observable counters for the session manager, used by the
+// /metrics endpoint.
+type Metrics struct {
+	ActiveSessions    int   `json:"active_sessions"`
+	TotalCreated      int64 `json:"total_created"`
+	TerminatedCount   int   `json:"terminated_count"`
+	MetaConnected     int   `json:"meta_connected"`
+	AgentConnected    int   `json:"agent_connected"`
+	AgentDisconnected int   `json:"agent_disconnected"`
+}
+
+// NewManager creates a new session manager and starts a background goroutine
+// that periodically cleans up expired sessions.
+func NewManager(cfg *config.Config, railsClient *callback.RailsClient) *Manager {
+	m := &Manager{
+		sessions:      make(map[string]*Session),
+		config:        cfg,
+		railsClient:   railsClient,
+		cleanupTicker: time.NewTicker(60 * time.Second),
+		cleanupStopCh: make(chan struct{}),
+	}
+
+	go m.cleanupLoop()
+	return m
+}
+
+// CreateSession creates a new call session with the given parameters. For
+// incoming calls, metaSDPOffer contains Meta's SDP offer and the returned
+// string is the SDP answer. For outgoing calls, metaSDPOffer is empty and
+// the returned string is the SDP offer to send to Meta.
+func (m *Manager) CreateSession(callID, accountID, direction, metaSDPOffer string, iceServers []webrtc.ICEServer) (*Session, string, error) {
+	// Check capacity limit.
+	if m.config.MaxConcurrentSessions > 0 {
+		m.mu.RLock()
+		activeCount := len(m.sessions)
+		m.mu.RUnlock()
+
+		if activeCount >= m.config.MaxConcurrentSessions {
+			return nil, "", fmt.Errorf("max concurrent sessions (%d) reached", m.config.MaxConcurrentSessions)
+		}
+	}
+
+	// Generate a unique session ID.
+	counter := m.sessionCounter.Add(1)
+	sessionID := fmt.Sprintf("sess_%s_%d", time.Now().Format("20060102150405"), counter)
+
+	sess, sdpResult, err := NewSession(m.config, m.railsClient, sessionID, callID, accountID, direction, metaSDPOffer, iceServers)
+	if err != nil {
+		return nil, "", fmt.Errorf("create session: %w", err)
+	}
+
+	m.mu.Lock()
+	m.sessions[sessionID] = sess
+	m.mu.Unlock()
+
+	slog.Info("manager: session created",
+		"session_id", sessionID,
+		"call_id", callID,
+		"direction", direction,
+	)
+
+	return sess, sdpResult, nil
+}
+
+// GetSession returns the session with the given ID, or nil if not found.
+func (m *Manager) GetSession(sessionID string) *Session {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	return m.sessions[sessionID]
+}
+
+// TerminateSession terminates the session with the given ID and removes it
+// from the active sessions map.
+func (m *Manager) TerminateSession(sessionID, reason string) error {
+	m.mu.Lock()
+	sess, ok := m.sessions[sessionID]
+	if !ok {
+		m.mu.Unlock()
+		return fmt.Errorf("session %s not found", sessionID)
+	}
+	delete(m.sessions, sessionID)
+	m.mu.Unlock()
+
+	sess.Terminate(reason)
+	return nil
+}
+
+// DeleteSession removes a session and cleans up its recording files.
+func (m *Manager) DeleteSession(sessionID string) error {
+	m.mu.Lock()
+	sess, ok := m.sessions[sessionID]
+	if ok {
+		delete(m.sessions, sessionID)
+	}
+	m.mu.Unlock()
+
+	if !ok {
+		return fmt.Errorf("session %s not found", sessionID)
+	}
+
+	sess.Terminate("deleted")
+
+	// Clean up recording files.
+	if sess.Recorder != nil {
+		sess.Recorder.Cleanup()
+	}
+
+	return nil
+}
+
+// CreateAgentPeer creates a new agent-side peer for the specified session.
+func (m *Manager) CreateAgentPeer(sessionID, peerID string, role peer.PeerRole, iceServers []webrtc.ICEServer) (string, error) {
+	sess := m.GetSession(sessionID)
+	if sess == nil {
+		return "", fmt.Errorf("session %s not found", sessionID)
+	}
+	return sess.CreateAgentPeer(peerID, role, iceServers)
+}
+
+// SetAgentAnswer sets the agent's SDP answer for the specified peer.
+func (m *Manager) SetAgentAnswer(sessionID, peerID, sdpAnswer string) error {
+	sess := m.GetSession(sessionID)
+	if sess == nil {
+		return fmt.Errorf("session %s not found", sessionID)
+	}
+	return sess.SetAgentAnswer(peerID, sdpAnswer)
+}
+
+// ReconnectAgent creates a new agent peer after tearing down the old one.
+func (m *Manager) ReconnectAgent(sessionID, oldPeerID, newPeerID string, role peer.PeerRole, iceServers []webrtc.ICEServer) (string, error) {
+	sess := m.GetSession(sessionID)
+	if sess == nil {
+		return "", fmt.Errorf("session %s not found", sessionID)
+	}
+	return sess.ReconnectAgent(oldPeerID, newPeerID, role, iceServers)
+}
+
+// GetMetrics returns current observable metrics about the session manager.
+func (m *Manager) GetMetrics() Metrics {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+
+	metrics := Metrics{
+		ActiveSessions: len(m.sessions),
+		TotalCreated:   m.sessionCounter.Load(),
+	}
+
+	for _, sess := range m.sessions {
+		switch sess.Status {
+		case StatusTerminated:
+			metrics.TerminatedCount++
+		case StatusMetaConnected:
+			metrics.MetaConnected++
+		case StatusAgentConnected, StatusActive:
+			metrics.AgentConnected++
+		case StatusAgentDisconnected:
+			metrics.AgentDisconnected++
+		}
+	}
+
+	return metrics
+}
+
+// RecoverOrphanedRecordings scans the recordings directory for files that
+// do not belong to any active session, reporting them to Rails. This handles
+// the case where the media server crashed mid-call and recordings were left
+// on disk.
+func (m *Manager) RecoverOrphanedRecordings() {
+	dir := m.config.RecordingsDir
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return
+		}
+		slog.Error("manager: failed to scan recordings directory",
+			"dir", dir,
+			"error", err,
+		)
+		return
+	}
+
+	m.mu.RLock()
+	activeIDs := make(map[string]bool, len(m.sessions))
+	for id := range m.sessions {
+		activeIDs[id] = true
+	}
+	m.mu.RUnlock()
+
+	orphanCount := 0
+	for _, entry := range entries {
+		if entry.IsDir() || !strings.HasSuffix(entry.Name(), ".ogg") {
+			continue
+		}
+
+		// Extract session ID from filename (e.g., "sess_20240101_1.ogg" -> "sess_20240101_1").
+		name := strings.TrimSuffix(entry.Name(), ".ogg")
+		// Remove channel suffixes.
+		name = strings.TrimSuffix(name, "_customer")
+		name = strings.TrimSuffix(name, "_agent")
+
+		if !activeIDs[name] {
+			orphanCount++
+			slog.Warn("manager: found orphaned recording",
+				"file", filepath.Join(dir, entry.Name()),
+				"session_id", name,
+			)
+		}
+	}
+
+	if orphanCount > 0 {
+		slog.Info("manager: orphaned recording scan complete",
+			"orphan_count", orphanCount,
+		)
+	}
+}
+
+// Shutdown gracefully terminates all active sessions and stops the cleanup
+// goroutine. It should be called during server shutdown.
+func (m *Manager) Shutdown() {
+	close(m.cleanupStopCh)
+	m.cleanupTicker.Stop()
+
+	m.mu.Lock()
+	sessions := make([]*Session, 0, len(m.sessions))
+	for _, sess := range m.sessions {
+		sessions = append(sessions, sess)
+	}
+	m.sessions = make(map[string]*Session)
+	m.mu.Unlock()
+
+	for _, sess := range sessions {
+		sess.Terminate("server_shutdown")
+	}
+
+	slog.Info("manager: all sessions terminated", "count", len(sessions))
+}
+
+// cleanupLoop runs periodically to remove terminated sessions from the map.
+func (m *Manager) cleanupLoop() {
+	for {
+		select {
+		case <-m.cleanupStopCh:
+			return
+		case <-m.cleanupTicker.C:
+			m.cleanup()
+		}
+	}
+}
+
+func (m *Manager) cleanup() {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	for id, sess := range m.sessions {
+		if sess.Status == StatusTerminated {
+			delete(m.sessions, id)
+			slog.Debug("manager: cleaned up terminated session", "session_id", id)
+		}
+	}
+}
diff --git a/enterprise/media-server/internal/session/session.go b/enterprise/media-server/internal/session/session.go
new file mode 100644
index 000000000..5b6222d66
--- /dev/null
+++ b/enterprise/media-server/internal/session/session.go
@@ -0,0 +1,563 @@
+// Package session manages call session lifecycles, coordinating between the
+// Meta-side peer, agent-side peers, audio bridge, and recording.
+package session
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"sync"
+	"time"
+
+	"github.com/pion/webrtc/v4"
+
+	"github.com/chatwoot/chatwoot-media-server/internal/callback"
+	"github.com/chatwoot/chatwoot-media-server/internal/config"
+	"github.com/chatwoot/chatwoot-media-server/internal/media"
+	"github.com/chatwoot/chatwoot-media-server/internal/peer"
+)
+
+// Status represents the current state of a call session.
+type Status string
+
+const (
+	StatusCreated           Status = "created"
+	StatusMetaConnected     Status = "meta_connected"
+	StatusAgentConnected    Status = "agent_connected"
+	StatusActive            Status = "active"
+	StatusAgentDisconnected Status = "agent_disconnected"
+	StatusTerminated        Status = "terminated"
+)
+
+// Session represents a single active call, holding the Meta-side peer
+// connection (Peer A), one or more agent-side peer connections (Peer B),
+// the audio bridge, and the recording engine.
+type Session struct {
+	ID        string
+	CallID    string
+	AccountID string
+	Direction string // "incoming" or "outgoing"
+
+	MetaPeer   *peer.MetaPeer
+	AgentPeers map[string]*peer.AgentPeer
+	Bridge     *media.Bridge
+	Recorder   *media.Recorder
+	Injectors  map[string]*media.Injector
+
+	Status    Status
+	StartedAt time.Time
+	CreatedAt time.Time
+
+	config         *config.Config
+	railsClient    *callback.RailsClient
+	reconnectTimer *time.Timer
+	cancel         context.CancelFunc
+	ctx            context.Context
+
+	mu sync.Mutex
+}
+
+// Info is the JSON-serializable representation of a session's current state,
+// returned by the GET /sessions/:id endpoint.
+type Info struct {
+	ID              string `json:"id"`
+	CallID          string `json:"call_id"`
+	AccountID       string `json:"account_id"`
+	Direction       string `json:"direction"`
+	Status          string `json:"status"`
+	MetaICEState    string `json:"meta_ice_state"`
+	AgentPeerCount  int    `json:"agent_peer_count"`
+	DurationSeconds int    `json:"duration_seconds"`
+	HasRecording    bool   `json:"has_recording"`
+	CreatedAt       string `json:"created_at"`
+}
+
+// NewSession creates a new call session. For incoming calls, the Meta SDP
+// offer is provided and the method returns the SDP answer. For outgoing calls,
+// the Meta SDP offer is empty and the method returns an SDP offer to send to
+// Meta.
+func NewSession(
+	cfg *config.Config,
+	railsClient *callback.RailsClient,
+	id, callID, accountID, direction, metaSDPOffer string,
+	iceServers []webrtc.ICEServer,
+) (*Session, string, error) {
+	ctx, cancel := context.WithTimeout(context.Background(), cfg.MaxSessionDuration)
+
+	sess := &Session{
+		ID:         id,
+		CallID:     callID,
+		AccountID:  accountID,
+		Direction:  direction,
+		AgentPeers: make(map[string]*peer.AgentPeer),
+		Injectors:  make(map[string]*media.Injector),
+		Status:     StatusCreated,
+		CreatedAt:  time.Now(),
+		config:     cfg,
+		railsClient: railsClient,
+		ctx:        ctx,
+		cancel:     cancel,
+	}
+
+	// Create the Meta-side peer connection (Peer A).
+	metaPeer, sdpResult, err := peer.NewMetaPeer(cfg, metaSDPOffer, iceServers)
+	if err != nil {
+		cancel()
+		return nil, "", fmt.Errorf("create meta peer: %w", err)
+	}
+	sess.MetaPeer = metaPeer
+
+	// Create the recorder.
+	recorder, err := media.NewRecorder(id, cfg.RecordingsDir)
+	if err != nil {
+		metaPeer.Close()
+		cancel()
+		return nil, "", fmt.Errorf("create recorder: %w", err)
+	}
+	sess.Recorder = recorder
+
+	// Create the audio bridge.
+	sess.Bridge = media.NewBridge(id, metaPeer, recorder)
+
+	// Wire up Meta peer event handlers.
+	metaPeer.OnICEStateChange(func(state webrtc.ICEConnectionState) {
+		sess.handleMetaICEStateChange(state)
+	})
+
+	metaPeer.OnTrackReady(func(track *webrtc.TrackRemote) {
+		slog.Info("session: Meta audio track ready, starting bridge forwarding",
+			"session_id", id,
+		)
+		// Start forwarding Meta audio to agents in its own goroutine.
+		go sess.Bridge.ReadAndForwardMetaTrack(sess.ctx, track)
+	})
+
+	// Start the max duration timer.
+	go func() {
+		<-ctx.Done()
+		sess.mu.Lock()
+		if sess.Status != StatusTerminated {
+			sess.mu.Unlock()
+			slog.Info("session: max duration reached, terminating",
+				"session_id", id,
+			)
+			sess.Terminate("max_duration_exceeded")
+		} else {
+			sess.mu.Unlock()
+		}
+	}()
+
+	return sess, sdpResult, nil
+}
+
+// SetMetaAnswer sets Meta's SDP answer on the Meta peer connection. This is
+// used for outbound calls when Meta responds to the server's SDP offer.
+func (s *Session) SetMetaAnswer(sdpAnswer string) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	if err := s.MetaPeer.SetRemoteAnswer(sdpAnswer); err != nil {
+		return fmt.Errorf("set meta answer: %w", err)
+	}
+	return nil
+}
+
+// CreateAgentPeer creates a new agent-side peer connection (Peer B) and
+// returns the SDP offer to send to the agent's browser.
+func (s *Session) CreateAgentPeer(peerID string, role peer.PeerRole, iceServers []webrtc.ICEServer) (string, error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	agentPeer, sdpOffer, err := peer.NewAgentPeer(s.config, peerID, role, iceServers)
+	if err != nil {
+		return "", fmt.Errorf("create agent peer: %w", err)
+	}
+
+	// Wire up agent peer event handlers.
+	agentPeer.OnICEStateChange(func(state webrtc.ICEConnectionState) {
+		s.handleAgentICEStateChange(peerID, state)
+	})
+
+	agentPeer.OnTrackReady(func(track *webrtc.TrackRemote) {
+		slog.Info("session: agent audio track ready, starting bridge forwarding",
+			"session_id", s.ID,
+			"peer_id", peerID,
+		)
+		go s.Bridge.ReadAndForwardAgentTrack(s.ctx, agentPeer, track)
+	})
+
+	s.AgentPeers[peerID] = agentPeer
+	s.Bridge.AddAgentPeer(agentPeer)
+
+	// Start the bridge if Meta is already connected.
+	if s.Status == StatusMetaConnected || s.Status == StatusAgentDisconnected {
+		s.Bridge.Start(s.ctx)
+		s.Status = StatusAgentConnected
+	}
+
+	// Cancel any active reconnect timer.
+	if s.reconnectTimer != nil {
+		s.reconnectTimer.Stop()
+		s.reconnectTimer = nil
+	}
+
+	return sdpOffer, nil
+}
+
+// SetAgentAnswer sets the agent browser's SDP answer on the specified agent
+// peer, completing the WebRTC handshake.
+func (s *Session) SetAgentAnswer(peerID, sdpAnswer string) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	ap, ok := s.AgentPeers[peerID]
+	if !ok {
+		return fmt.Errorf("agent peer %s not found", peerID)
+	}
+
+	if err := ap.SetAnswer(sdpAnswer); err != nil {
+		return fmt.Errorf("set agent answer: %w", err)
+	}
+
+	return nil
+}
+
+// ReconnectAgent tears down the old agent peer connection and creates a new
+// one, returning a fresh SDP offer. This is used when the agent reloads the
+// page and needs to re-establish their peer connection while the Meta-side
+// connection stays alive.
+func (s *Session) ReconnectAgent(oldPeerID, newPeerID string, role peer.PeerRole, iceServers []webrtc.ICEServer) (string, error) {
+	s.mu.Lock()
+	// Remove the old agent peer from the session if it exists.
+	var oldPeer *peer.AgentPeer
+	if ap, ok := s.AgentPeers[oldPeerID]; ok {
+		oldPeer = ap
+		s.Bridge.RemoveAgentPeer(oldPeerID)
+		delete(s.AgentPeers, oldPeerID)
+	}
+	s.mu.Unlock()
+
+	// Close outside the lock to avoid deadlock from ICE state callbacks.
+	if oldPeer != nil {
+		oldPeer.Close()
+	}
+
+	// Create a new agent peer.
+	return s.CreateAgentPeer(newPeerID, role, iceServers)
+}
+
+// Terminate gracefully ends the call session. It closes all peer connections,
+// finalizes the recording, and sends callbacks to Rails.
+func (s *Session) Terminate(reason string) {
+	s.mu.Lock()
+	if s.Status == StatusTerminated {
+		s.mu.Unlock()
+		return
+	}
+	s.Status = StatusTerminated
+
+	// Collect injectors and agent peers while holding the lock, then release
+	// before calling Close(). PeerConnection.Close() may fire ICE state
+	// callbacks synchronously, which would deadlock if we held s.mu.
+	injectors := make([]*media.Injector, 0, len(s.Injectors))
+	for _, inj := range s.Injectors {
+		injectors = append(injectors, inj)
+	}
+
+	agentPeers := make([]*peer.AgentPeer, 0, len(s.AgentPeers))
+	for id, ap := range s.AgentPeers {
+		agentPeers = append(agentPeers, ap)
+		delete(s.AgentPeers, id)
+	}
+
+	metaPeer := s.MetaPeer
+	s.mu.Unlock()
+
+	slog.Info("session: terminating",
+		"session_id", s.ID,
+		"reason", reason,
+	)
+
+	// Stop the bridge.
+	s.Bridge.Stop()
+
+	// Stop any active injectors.
+	for _, inj := range injectors {
+		inj.Stop()
+	}
+
+	// Close all agent peers (may trigger ICE state callbacks).
+	for _, ap := range agentPeers {
+		ap.Close()
+	}
+
+	// Close Meta peer.
+	if metaPeer != nil {
+		metaPeer.Close()
+	}
+
+	// Finalize recording.
+	if s.Recorder != nil {
+		if err := s.Recorder.Finalize(); err != nil {
+			slog.Error("session: failed to finalize recording",
+				"session_id", s.ID,
+				"error", err,
+			)
+		}
+	}
+
+	// Cancel the session context.
+	if s.cancel != nil {
+		s.cancel()
+	}
+
+	// Notify Rails.
+	s.sendTerminationCallbacks(reason)
+}
+
+// RemoveAgentPeer removes a specific agent peer from the session.
+func (s *Session) RemoveAgentPeer(peerID string) error {
+	s.mu.Lock()
+	ap, ok := s.AgentPeers[peerID]
+	if !ok {
+		s.mu.Unlock()
+		return fmt.Errorf("agent peer %s not found", peerID)
+	}
+
+	s.Bridge.RemoveAgentPeer(peerID)
+	delete(s.AgentPeers, peerID)
+	s.mu.Unlock()
+
+	// Close outside the lock to avoid deadlock from ICE state callbacks.
+	ap.Close()
+	return nil
+}
+
+// ChangeAgentRole changes the role of a connected agent peer.
+func (s *Session) ChangeAgentRole(peerID string, newRole peer.PeerRole) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	ap, ok := s.AgentPeers[peerID]
+	if !ok {
+		return fmt.Errorf("agent peer %s not found", peerID)
+	}
+
+	ap.Role = newRole
+	return nil
+}
+
+// GetInfo returns a snapshot of the session's current state.
+func (s *Session) GetInfo() Info {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	info := Info{
+		ID:             s.ID,
+		CallID:         s.CallID,
+		AccountID:      s.AccountID,
+		Direction:      s.Direction,
+		Status:         string(s.Status),
+		AgentPeerCount: len(s.AgentPeers),
+		HasRecording:   s.Recorder != nil,
+		CreatedAt:      s.CreatedAt.UTC().Format(time.RFC3339),
+	}
+
+	if s.MetaPeer != nil {
+		info.MetaICEState = s.MetaPeer.ICEConnectionState().String()
+	}
+
+	if !s.StartedAt.IsZero() {
+		info.DurationSeconds = int(time.Since(s.StartedAt).Seconds())
+	}
+
+	return info
+}
+
+// RecordingFilePath returns the path to the combined recording file.
+func (s *Session) RecordingFilePath() string {
+	if s.Recorder == nil {
+		return ""
+	}
+	return s.Recorder.CombinedFilePath()
+}
+
+// GetInjectorTarget returns the appropriate write target for audio injection
+// based on the target parameter. Returns nil if the target is unavailable.
+func (s *Session) GetInjectorTarget(target string) media.InjectorTarget {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	if s.MetaPeer == nil {
+		return nil
+	}
+	// All injection targets currently route to the Meta peer's local track.
+	return s.MetaPeer.LocalTrack()
+}
+
+// AddInjector registers an active injector with the session in a thread-safe manner.
+func (s *Session) AddInjector(id string, inj *media.Injector) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.Injectors[id] = inj
+}
+
+// StopInjector stops and removes an injector by ID. Returns an error if not found.
+func (s *Session) StopInjector(id string) error {
+	s.mu.Lock()
+	inj, ok := s.Injectors[id]
+	if !ok {
+		s.mu.Unlock()
+		return fmt.Errorf("injector %s not found", id)
+	}
+	delete(s.Injectors, id)
+	s.mu.Unlock()
+
+	inj.Stop()
+	return nil
+}
+
+func (s *Session) handleMetaICEStateChange(state webrtc.ICEConnectionState) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	if s.Status == StatusTerminated {
+		return
+	}
+
+	switch state {
+	case webrtc.ICEConnectionStateConnected:
+		if s.Status == StatusCreated {
+			s.Status = StatusMetaConnected
+			s.StartedAt = time.Now()
+			slog.Info("session: Meta peer connected",
+				"session_id", s.ID,
+			)
+		}
+
+	case webrtc.ICEConnectionStateFailed, webrtc.ICEConnectionStateDisconnected:
+		slog.Warn("session: Meta peer disconnected/failed",
+			"session_id", s.ID,
+			"state", state.String(),
+		)
+		// Meta disconnecting means the call is over.
+		go s.Terminate("meta_disconnected")
+
+	case webrtc.ICEConnectionStateClosed:
+		slog.Info("session: Meta peer closed", "session_id", s.ID)
+	}
+}
+
+func (s *Session) handleAgentICEStateChange(peerID string, state webrtc.ICEConnectionState) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	if s.Status == StatusTerminated {
+		return
+	}
+
+	switch state {
+	case webrtc.ICEConnectionStateConnected:
+		slog.Info("session: agent peer connected",
+			"session_id", s.ID,
+			"peer_id", peerID,
+		)
+		if s.Status == StatusMetaConnected || s.Status == StatusAgentDisconnected {
+			s.Status = StatusActive
+			// Start bridge if not already running.
+			s.Bridge.Start(s.ctx)
+		}
+
+	case webrtc.ICEConnectionStateFailed, webrtc.ICEConnectionStateDisconnected:
+		slog.Warn("session: agent peer disconnected/failed",
+			"session_id", s.ID,
+			"peer_id", peerID,
+			"state", state.String(),
+		)
+
+		// Check if any other agent peers are still connected.
+		hasConnected := false
+		for id, ap := range s.AgentPeers {
+			if id != peerID && ap.ICEConnectionState() == webrtc.ICEConnectionStateConnected {
+				hasConnected = true
+				break
+			}
+		}
+
+		if !hasConnected && s.Status != StatusTerminated {
+			s.Status = StatusAgentDisconnected
+
+			// Start reconnect timer.
+			s.reconnectTimer = time.AfterFunc(s.config.ReconnectTimeout, func() {
+				slog.Info("session: reconnect timeout expired, terminating",
+					"session_id", s.ID,
+				)
+				s.Terminate("agent_reconnect_timeout")
+			})
+
+			// Notify Rails of agent disconnect.
+			go func() {
+				if s.railsClient != nil {
+					err := s.railsClient.NotifyAgentDisconnected(context.Background(), callback.AgentDisconnectedPayload{
+						SessionID: s.ID,
+						CallID:    s.CallID,
+						Reason:    state.String(),
+					})
+					if err != nil {
+						slog.Error("session: failed to notify Rails of agent disconnect",
+							"session_id", s.ID,
+							"error", err,
+						)
+					}
+				}
+			}()
+		}
+
+	case webrtc.ICEConnectionStateClosed:
+		slog.Info("session: agent peer closed",
+			"session_id", s.ID,
+			"peer_id", peerID,
+		)
+	}
+}
+
+func (s *Session) sendTerminationCallbacks(reason string) {
+	if s.railsClient == nil {
+		return
+	}
+
+	ctx := context.Background()
+	durationSec := 0
+	if !s.StartedAt.IsZero() {
+		durationSec = int(time.Since(s.StartedAt).Seconds())
+	}
+
+	// Notify session terminated.
+	if err := s.railsClient.NotifySessionTerminated(ctx, callback.SessionTerminatedPayload{
+		SessionID:   s.ID,
+		CallID:      s.CallID,
+		Reason:      reason,
+		DurationSec: durationSec,
+	}); err != nil {
+		slog.Error("session: failed to notify Rails of termination",
+			"session_id", s.ID,
+			"error", err,
+		)
+	}
+
+	// Notify recording ready if we have one.
+	if s.Recorder != nil && s.Recorder.FileSize() > 0 {
+		if err := s.railsClient.NotifyRecordingReady(ctx, callback.RecordingReadyPayload{
+			SessionID:     s.ID,
+			CallID:        s.CallID,
+			FilePath:      s.Recorder.CombinedFilePath(),
+			DurationSec:   durationSec,
+			FileSizeBytes: s.Recorder.FileSize(),
+		}); err != nil {
+			slog.Error("session: failed to notify Rails of recording",
+				"session_id", s.ID,
+				"error", err,
+			)
+		}
+	}
+}