dvgateway-sdk 1.4.9 → 1.5.1

package/README.md

@@ -789,6 +789,19 @@ SDK는 429 응답 시 자동으로 지수 백오프 재시도합니다.
 
 ---
 
+## 고급 통화 제어
+
+| 메서드 | 설명 |
+|--------|------|
+| `await gw.collectDtmf({ linkedId, ... })` | DTMF 키 수집 (타임아웃, 종료 키, STT 자동 뮤트 포함) |
+| `await gw.muteStt(linkedId)` | STT 입력 뮤트 (DTMF 입력 중 음성 인식 차단) |
+| `await gw.unmuteStt(linkedId)` | STT 뮤트 해제 |
+| `await gw.playAudio({ linkedId, audioUrl: ..., ... })` | 통화 채널에 오디오 파일 재생 |
+| `await gw.stopAudio(linkedId)` | 재생 중인 오디오 중단 |
+| `await gw.warmTransfer({ linkedId, ... })` | 상담원 이관 (whisper 안내 포함; whisper는 이관 대상에게만 들림) |
+
+자세한 옵션 및 예제는 [docs/sdk-guide/13-voice-flow-controls.md](../../docs/sdk-guide/13-voice-flow-controls.md) 참조.
+
 ## 보안
 
 - **API Key → JWT 자동 교환**: SDK가 내부적으로 처리, 사용자 코드에서 토큰 관리 불필요

package/dist/client.d.ts

@@ -23,7 +23,7 @@ import { type AudioStreamHandle, type PipelineType } from './streams/audio-strea
 import { PipelineBuilder } from './pipeline/builder.js';
 import { PipelineMetrics } from './observability/metrics.js';
 import { type SimulateOptions, type SimulatedCall } from './simulator/simulator.js';
-import type { DVGatewayOptions, CallSession, CallEvent, TTSCompleteEvent, TranscriptResult, StreamDir, TtsAdapter, Unsubscribe } from './types/index.js';
+import type { DVGatewayOptions, CallSession, CallEvent, TTSCompleteEvent, TranscriptResult, StreamDir, TtsAdapter, Unsubscribe, DTMFResult, PlayAudioResult, WarmTransferResult } from './types/index.js';
 export declare class DVGatewayClient {
     private readonly auth;
     private readonly wsPool;
@@ -34,6 +34,14 @@ export declare class DVGatewayClient {
     private readonly minutes;
     readonly metrics: PipelineMetrics;
     private readonly logger;
+    /**
+     * Per-linkedID STT mute reference counter used by collectDtmf to
+     * coordinate concurrent collectors within this process. Only the first
+     * acquire actually sends the mute REST call; only the last release sends
+     * the unmute REST call. JS is single-threaded so synchronous increment
+     * / decrement on this map is race-free across `await` boundaries.
+     */
+    private readonly sttMuteRefs;
     constructor(opts: DVGatewayOptions);
     /**
      * Create a fluent AI voice pipeline.
@@ -213,6 +221,118 @@ export declare class DVGatewayClient {
      * ```
      */
     broadcastSay(confId: string, text: string, tts: TtsAdapter): Promise<void>;
+    /**
+     * Mute the gateway's STT audio pipeline for a call.
+     *
+     * While muted, inbound audio frames for `linkedId` are dropped before
+     * reaching the STT provider. Used by {@link collectDtmf} so DTMF button
+     * tones are not transcribed as spurious text, but also callable directly
+     * for custom flows.
+     *
+     * @param linkedId  Call session identifier.
+     * @param durationMs  Auto-expiry in milliseconds. Omit (or pass 0) to
+     *   keep the mute open until an explicit {@link unmuteStt}.
+     */
+    muteStt(linkedId: string, durationMs?: number): Promise<void>;
+    /**
+     * Explicitly unmute the STT pipeline for a call.
+     *
+     * Forces the mute state to off — even if other callers still hold mutes
+     * on the gateway. Use {@link collectDtmf} for reference-counted
+     * semantics; this is the escape hatch.
+     */
+    unmuteStt(linkedId: string): Promise<void>;
+    /**
+     * Collect DTMF digits from the caller over the callinfo stream.
+     *
+     * Completes when any of the following fires first:
+     *  - `maxDigits` digits have been accumulated
+     *  - the `terminator` key is pressed
+     *  - the first-key `timeoutMs` elapses before any digit
+     *  - `interDigitTimeoutMs` elapses after at least one digit
+     *
+     * Gateway prerequisites:
+     *  - `GW_DTMF_ENABLED=true` (default) — AMI DTMF forwarding on.
+     *  - `GW_DTMF_PHASE_FILTER` should include `"end"` (default). Only
+     *    `phase === "end"` events are counted, mirroring IVR semantics
+     *    where a digit is "entered" when released.
+     *
+     * Only events matching `linkedId` are accumulated. Concurrent calls to
+     * `collectDtmf` on the same `linkedId` are independent collections; STT
+     * mute is reference-counted so the STT only resumes when the final
+     * concurrent collector releases.
+     *
+     * @example
+     * ```typescript
+     * const result = await gw.collectDtmf({
+     *   linkedId,
+     *   maxDigits: 4,
+     *   timeoutMs: 8_000,
+     *   interDigitTimeoutMs: 3_000,
+     *   terminator: '#',
+     * });
+     * if (result.timedOut) {
+     *   await gw.say(linkedId, '입력 시간이 초과되었습니다.', tts);
+     * } else {
+     *   await processPin(result.digits);
+     * }
+     * ```
+     */
+    collectDtmf(options: {
+        linkedId: string;
+        maxDigits?: number;
+        timeoutMs?: number;
+        interDigitTimeoutMs?: number;
+        terminator?: string;
+        muteStt?: boolean;
+    }): Promise<DTMFResult>;
+    /**
+     * Play an audio file from a URL into an active call.
+     *
+     * The gateway downloads the audio asset (auto-converting to 16kHz mono
+     * PCM via FFmpeg when needed) and injects it into the call's channel.
+     * Typical uses: IVR prompts, legal disclosures, on-hold music,
+     * pre-recorded announcements.
+     *
+     * Return-value semantics:
+     *  - `waitForCompletion=true` (default): the promise resolves only after
+     *    the gateway reports playback finished (or was interrupted / stopped).
+     *  - `waitForCompletion=false`: the gateway returns 202 as soon as
+     *    playback starts, so the promise resolves immediately with
+     *    `completed=false`, `durationMs=0`, `interruptedByDtmf=null`.
+     *
+     * Empty-string `interruptedByDtmf` from the gateway is normalized to
+     * `null` for parity with the Python SDK.
+     *
+     * @throws {Error} when `options.url` is an empty string.
+     *
+     * @example Legal notice with DTMF consent
+     * ```typescript
+     * const res = await gw.playAudio({
+     *   linkedId,
+     *   url: 'https://cdn.example.com/legal-notice.mp3',
+     *   interruptOnDtmf: true,
+     * });
+     * if (res.interruptedByDtmf === '1') {
+     *   await processConsent(linkedId);
+     * }
+     * ```
+     */
+    playAudio(options: {
+        linkedId: string;
+        url: string;
+        loop?: boolean;
+        interruptOnDtmf?: boolean;
+        waitForCompletion?: boolean;
+    }): Promise<PlayAudioResult>;
+    /**
+     * Stop any active audio playback on a call.
+     *
+     * No-op when nothing is playing. Safe to call concurrently with
+     * {@link playAudio} — the outstanding `playAudio` promise will resolve
+     * with `completed=false`.
+     */
+    stopAudio(linkedId: string): Promise<void>;
     /**
      * Terminate an active call by linkedId.
      * Sends AMI Hangup action to Asterisk via the gateway.
@@ -223,6 +343,50 @@ export declare class DVGatewayClient {
      * Sends AMI Redirect action to Asterisk via the gateway.
      */
     redirect(linkedId: string, destination: string, context?: string): Promise<void>;
+    /**
+     * Warm-transfer an active call to an agent extension.
+     *
+     * The gateway originates a new leg to `destination` (in `context`),
+     * optionally plays a whisper prompt to the agent, optionally plays
+     * hold audio to the caller, and bridges the two legs once the agent
+     * answers. If the agent does not answer before `timeoutMs` elapses
+     * the transfer is reported as timed out and the original call is
+     * left untouched.
+     *
+     * **Note:** the gateway does not yet synthesize the `whisperText`
+     * prompt; the response's `whisperPlayed` flag will therefore typically
+     * be `false` in this SDK release. When gateway-side whisper
+     * synthesis lands, no SDK changes are required.
+     *
+     * Server-side empty strings for `error` / `agentChannel` / `bridgeId`
+     * are normalized to `null` for parity with the Python SDK.
+     *
+     * @throws {Error} when `destination` is empty or `timeoutMs <= 0`.
+     *
+     * @example
+     * ```typescript
+     * const res = await gw.warmTransfer({
+     *   linkedId,
+     *   destination: '1001',
+     *   whisperText: 'VIP 고객입니다',
+     *   holdAudioUrl: 'https://cdn.example.com/hold.mp3',
+     *   timeoutMs: 30_000,
+     * });
+     * if (res.connected) {
+     *   console.log('agent', res.agentChannel, 'bridged', res.bridgeId);
+     * } else if (res.timedOut) {
+     *   await gw.say(linkedId, '담당자 연결에 실패했습니다.', tts);
+     * }
+     * ```
+     */
+    warmTransfer(options: {
+        linkedId: string;
+        destination: string;
+        whisperText?: string;
+        holdAudioUrl?: string;
+        context?: string;
+        timeoutMs?: number;
+    }): Promise<WarmTransferResult>;
     /** Apply PBX configuration changes (required after callerID/extension changes) */
     applyChanges(): Promise<unknown>;
     /** Click-to-call: initiate an outbound call via PBX */

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/client.js

@@ -41,6 +41,14 @@ export class DVGatewayClient {
     minutes;
     metrics;
     logger;
+    /**
+     * Per-linkedID STT mute reference counter used by collectDtmf to
+     * coordinate concurrent collectors within this process. Only the first
+     * acquire actually sends the mute REST call; only the last release sends
+     * the unmute REST call. JS is single-threaded so synchronous increment
+     * / decrement on this map is race-free across `await` boundaries.
+     */
+    sttMuteRefs = new Map();
     constructor(opts) {
         // Enforce TLS in production
         const baseUrl = this.normalizeBaseUrl(opts);
@@ -260,6 +268,320 @@ export class DVGatewayClient {
     async broadcastSay(confId, text, tts) {
         return this.ttsInjector.broadcastToConference(confId, tts.synthesize(text));
     }
+    // ─── DTMF Collection ──────────────────────────────────────────────────
+    /**
+     * Mute the gateway's STT audio pipeline for a call.
+     *
+     * While muted, inbound audio frames for `linkedId` are dropped before
+     * reaching the STT provider. Used by {@link collectDtmf} so DTMF button
+     * tones are not transcribed as spurious text, but also callable directly
+     * for custom flows.
+     *
+     * @param linkedId  Call session identifier.
+     * @param durationMs  Auto-expiry in milliseconds. Omit (or pass 0) to
+     *   keep the mute open until an explicit {@link unmuteStt}.
+     */
+    async muteStt(linkedId, durationMs) {
+        const query = durationMs !== undefined && durationMs > 0
+            ? `?duration_ms=${Math.floor(durationMs)}`
+            : '';
+        await this.http.post(`/api/v1/stt/${encodeURIComponent(linkedId)}/mute${query}`, {});
+        this.logger.debug({ linkedId, durationMs }, 'STT muted');
+    }
+    /**
+     * Explicitly unmute the STT pipeline for a call.
+     *
+     * Forces the mute state to off — even if other callers still hold mutes
+     * on the gateway. Use {@link collectDtmf} for reference-counted
+     * semantics; this is the escape hatch.
+     */
+    async unmuteStt(linkedId) {
+        await this.http.delete(`/api/v1/stt/${encodeURIComponent(linkedId)}/mute`);
+        this.logger.debug({ linkedId }, 'STT unmuted');
+    }
+    /**
+     * Collect DTMF digits from the caller over the callinfo stream.
+     *
+     * Completes when any of the following fires first:
+     *  - `maxDigits` digits have been accumulated
+     *  - the `terminator` key is pressed
+     *  - the first-key `timeoutMs` elapses before any digit
+     *  - `interDigitTimeoutMs` elapses after at least one digit
+     *
+     * Gateway prerequisites:
+     *  - `GW_DTMF_ENABLED=true` (default) — AMI DTMF forwarding on.
+     *  - `GW_DTMF_PHASE_FILTER` should include `"end"` (default). Only
+     *    `phase === "end"` events are counted, mirroring IVR semantics
+     *    where a digit is "entered" when released.
+     *
+     * Only events matching `linkedId` are accumulated. Concurrent calls to
+     * `collectDtmf` on the same `linkedId` are independent collections; STT
+     * mute is reference-counted so the STT only resumes when the final
+     * concurrent collector releases.
+     *
+     * @example
+     * ```typescript
+     * const result = await gw.collectDtmf({
+     *   linkedId,
+     *   maxDigits: 4,
+     *   timeoutMs: 8_000,
+     *   interDigitTimeoutMs: 3_000,
+     *   terminator: '#',
+     * });
+     * if (result.timedOut) {
+     *   await gw.say(linkedId, '입력 시간이 초과되었습니다.', tts);
+     * } else {
+     *   await processPin(result.digits);
+     * }
+     * ```
+     */
+    async collectDtmf(options) {
+        const linkedId = options.linkedId;
+        const maxDigits = options.maxDigits ?? 1;
+        const timeoutMs = options.timeoutMs ?? 5_000;
+        const interDigitTimeoutMs = options.interDigitTimeoutMs ?? 2_000;
+        const terminator = options.terminator ?? '#';
+        const muteStt = options.muteStt ?? true;
+        if (maxDigits < 1) {
+            throw new Error('maxDigits must be >= 1');
+        }
+        const digitsBuf = [];
+        let terminated = false;
+        // Promise-based "next digit" signal, reset each wait cycle.
+        let resolveNext = null;
+        let nextPromise = new Promise((resolve) => {
+            resolveNext = resolve;
+        });
+        const resetSignal = () => {
+            nextPromise = new Promise((resolve) => {
+                resolveNext = resolve;
+            });
+        };
+        const fireSignal = () => {
+            if (resolveNext) {
+                const r = resolveNext;
+                resolveNext = null;
+                r();
+            }
+        };
+        const onDtmf = (event) => {
+            if (event.linkedId !== linkedId)
+                return;
+            if (event.phase !== 'end')
+                return;
+            const digit = event.digit;
+            if (!digit)
+                return;
+            if (terminator && digit === terminator) {
+                terminated = true;
+                fireSignal();
+                return;
+            }
+            digitsBuf.push(digit);
+            fireSignal();
+        };
+        const unsub = this.on('call:dtmf', onDtmf);
+        // Reference-counted STT mute (see collectDtmf in Python SDK).
+        let muteEngaged = false;
+        if (muteStt) {
+            const prev = this.sttMuteRefs.get(linkedId) ?? 0;
+            this.sttMuteRefs.set(linkedId, prev + 1);
+            if (prev === 0) {
+                try {
+                    await this.muteStt(linkedId);
+                    muteEngaged = true;
+                }
+                catch (err) {
+                    this.logger.warn({ linkedId, err: err instanceof Error ? err.message : String(err) }, 'collectDtmf: muteStt failed, continuing without mute');
+                    // Rollback ref so we don't leak; disable mute side of finally.
+                    const cur = this.sttMuteRefs.get(linkedId) ?? 1;
+                    if (cur <= 1) {
+                        this.sttMuteRefs.delete(linkedId);
+                    }
+                    else {
+                        this.sttMuteRefs.set(linkedId, cur - 1);
+                    }
+                }
+            }
+            else {
+                // Another collector already engaged the gateway mute; we only
+                // participate in ref counting.
+                muteEngaged = true;
+            }
+        }
+        // Timeout helper: race signal promise against a timeout.
+        const waitWithTimeout = async (ms) => {
+            if (ms <= 0) {
+                // Zero/negative timeout: check synchronously; if nothing queued,
+                // treat as immediate timeout.
+                return Promise.race([
+                    nextPromise.then(() => 'signal'),
+                    Promise.resolve('timeout'),
+                ]);
+            }
+            let timer = null;
+            const timeoutPromise = new Promise((resolve) => {
+                timer = setTimeout(() => resolve('timeout'), ms);
+            });
+            const sigPromise = nextPromise.then(() => 'signal');
+            try {
+                return await Promise.race([sigPromise, timeoutPromise]);
+            }
+            finally {
+                if (timer)
+                    clearTimeout(timer);
+            }
+        };
+        try {
+            // First-key wait.
+            const firstOutcome = await waitWithTimeout(timeoutMs);
+            if (firstOutcome === 'timeout') {
+                return { digits: '', timedOut: true, terminatedByKey: false };
+            }
+            if (terminated) {
+                return {
+                    digits: digitsBuf.join(''),
+                    timedOut: false,
+                    terminatedByKey: true,
+                };
+            }
+            if (digitsBuf.length >= maxDigits) {
+                return {
+                    digits: digitsBuf.slice(0, maxDigits).join(''),
+                    timedOut: false,
+                    terminatedByKey: false,
+                };
+            }
+            // Subsequent digits: inter-digit timeout governs.
+            // Loop until completion.
+            // eslint-disable-next-line no-constant-condition
+            while (true) {
+                resetSignal();
+                const outcome = await waitWithTimeout(interDigitTimeoutMs);
+                if (outcome === 'timeout') {
+                    return {
+                        digits: digitsBuf.join(''),
+                        timedOut: true,
+                        terminatedByKey: false,
+                    };
+                }
+                if (terminated) {
+                    return {
+                        digits: digitsBuf.join(''),
+                        timedOut: false,
+                        terminatedByKey: true,
+                    };
+                }
+                if (digitsBuf.length >= maxDigits) {
+                    return {
+                        digits: digitsBuf.slice(0, maxDigits).join(''),
+                        timedOut: false,
+                        terminatedByKey: false,
+                    };
+                }
+            }
+        }
+        finally {
+            try {
+                unsub();
+            }
+            catch {
+                // defensive — unsubscribe should never throw.
+            }
+            if (muteStt && muteEngaged) {
+                const remaining = (this.sttMuteRefs.get(linkedId) ?? 1) - 1;
+                if (remaining <= 0) {
+                    this.sttMuteRefs.delete(linkedId);
+                    try {
+                        await this.unmuteStt(linkedId);
+                    }
+                    catch (err) {
+                        this.logger.warn({
+                            linkedId,
+                            err: err instanceof Error ? err.message : String(err),
+                        }, 'collectDtmf: unmuteStt failed');
+                    }
+                }
+                else {
+                    this.sttMuteRefs.set(linkedId, remaining);
+                }
+            }
+        }
+    }
+    // ─── Audio Playback ────────────────────────────────────────────────────
+    /**
+     * Play an audio file from a URL into an active call.
+     *
+     * The gateway downloads the audio asset (auto-converting to 16kHz mono
+     * PCM via FFmpeg when needed) and injects it into the call's channel.
+     * Typical uses: IVR prompts, legal disclosures, on-hold music,
+     * pre-recorded announcements.
+     *
+     * Return-value semantics:
+     *  - `waitForCompletion=true` (default): the promise resolves only after
+     *    the gateway reports playback finished (or was interrupted / stopped).
+     *  - `waitForCompletion=false`: the gateway returns 202 as soon as
+     *    playback starts, so the promise resolves immediately with
+     *    `completed=false`, `durationMs=0`, `interruptedByDtmf=null`.
+     *
+     * Empty-string `interruptedByDtmf` from the gateway is normalized to
+     * `null` for parity with the Python SDK.
+     *
+     * @throws {Error} when `options.url` is an empty string.
+     *
+     * @example Legal notice with DTMF consent
+     * ```typescript
+     * const res = await gw.playAudio({
+     *   linkedId,
+     *   url: 'https://cdn.example.com/legal-notice.mp3',
+     *   interruptOnDtmf: true,
+     * });
+     * if (res.interruptedByDtmf === '1') {
+     *   await processConsent(linkedId);
+     * }
+     * ```
+     */
+    async playAudio(options) {
+        const { linkedId, url } = options;
+        if (!url) {
+            throw new Error('url is required');
+        }
+        const loop = options.loop ?? false;
+        const interruptOnDtmf = options.interruptOnDtmf ?? false;
+        const waitForCompletion = options.waitForCompletion ?? true;
+        const body = {
+            url,
+            loop,
+            interruptOnDtmf,
+            waitForCompletion,
+        };
+        const res = await this.http.post(`/api/v1/play/${encodeURIComponent(linkedId)}`, body);
+        const data = (res.data ?? {});
+        if (!waitForCompletion) {
+            // 202 — gateway accepted the request; playback proceeds async.
+            return { completed: false, interruptedByDtmf: null, durationMs: 0 };
+        }
+        const rawDtmf = data['interruptedByDtmf'];
+        const interruptedByDtmf = typeof rawDtmf === 'string' && rawDtmf !== '' ? rawDtmf : null;
+        const durationMsRaw = data['durationMs'];
+        const durationMs = typeof durationMsRaw === 'number' ? Math.floor(durationMsRaw) : 0;
+        return {
+            completed: Boolean(data['completed']),
+            interruptedByDtmf,
+            durationMs,
+        };
+    }
+    /**
+     * Stop any active audio playback on a call.
+     *
+     * No-op when nothing is playing. Safe to call concurrently with
+     * {@link playAudio} — the outstanding `playAudio` promise will resolve
+     * with `completed=false`.
+     */
+    async stopAudio(linkedId) {
+        await this.http.delete(`/api/v1/play/${encodeURIComponent(linkedId)}`);
+        this.logger.debug({ linkedId }, 'Audio playback stopped');
+    }
     // ─── Call Control ──────────────────────────────────────────────────────
     /**
      * Terminate an active call by linkedId.
@@ -281,6 +603,77 @@ export class DVGatewayClient {
         });
         this.logger.debug({ linkedId, destination, context }, 'Call redirect requested');
     }
+    /**
+     * Warm-transfer an active call to an agent extension.
+     *
+     * The gateway originates a new leg to `destination` (in `context`),
+     * optionally plays a whisper prompt to the agent, optionally plays
+     * hold audio to the caller, and bridges the two legs once the agent
+     * answers. If the agent does not answer before `timeoutMs` elapses
+     * the transfer is reported as timed out and the original call is
+     * left untouched.
+     *
+     * **Note:** the gateway does not yet synthesize the `whisperText`
+     * prompt; the response's `whisperPlayed` flag will therefore typically
+     * be `false` in this SDK release. When gateway-side whisper
+     * synthesis lands, no SDK changes are required.
+     *
+     * Server-side empty strings for `error` / `agentChannel` / `bridgeId`
+     * are normalized to `null` for parity with the Python SDK.
+     *
+     * @throws {Error} when `destination` is empty or `timeoutMs <= 0`.
+     *
+     * @example
+     * ```typescript
+     * const res = await gw.warmTransfer({
+     *   linkedId,
+     *   destination: '1001',
+     *   whisperText: 'VIP 고객입니다',
+     *   holdAudioUrl: 'https://cdn.example.com/hold.mp3',
+     *   timeoutMs: 30_000,
+     * });
+     * if (res.connected) {
+     *   console.log('agent', res.agentChannel, 'bridged', res.bridgeId);
+     * } else if (res.timedOut) {
+     *   await gw.say(linkedId, '담당자 연결에 실패했습니다.', tts);
+     * }
+     * ```
+     */
+    async warmTransfer(options) {
+        const linkedId = options.linkedId;
+        const destination = options.destination;
+        const timeoutMs = options.timeoutMs ?? 30_000;
+        const context = options.context ?? 'from-internal';
+        const whisperText = options.whisperText ?? '';
+        const holdAudioUrl = options.holdAudioUrl ?? '';
+        if (!destination) {
+            throw new Error('destination is required');
+        }
+        if (timeoutMs <= 0) {
+            throw new Error('timeoutMs must be > 0');
+        }
+        const body = {
+            destination,
+            timeoutMs: Math.floor(timeoutMs),
+        };
+        if (context)
+            body['context'] = context;
+        if (whisperText)
+            body['whisperText'] = whisperText;
+        if (holdAudioUrl)
+            body['holdAudioUrl'] = holdAudioUrl;
+        const res = await this.http.post(`/api/v1/transfer/warm/${encodeURIComponent(linkedId)}`, body);
+        const data = (res.data ?? {});
+        const toNullable = (v) => typeof v === 'string' && v !== '' ? v : null;
+        return {
+            connected: Boolean(data['connected']),
+            timedOut: Boolean(data['timedOut']),
+            error: toNullable(data['error']),
+            agentChannel: toNullable(data['agentChannel']),
+            bridgeId: toNullable(data['bridgeId']),
+            whisperPlayed: Boolean(data['whisperPlayed']),
+        };
+    }
     // ─── PBX Management ─────────────────────────────────────────────────
     /** Apply PBX configuration changes (required after callerID/extension changes) */
     async applyChanges() {