@fonoster/apiserver 0.16.10 → 0.17.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Fonoster Inc
+Copyright (c) 2026 Fonoster Inc
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

package/dist/core/buildWelcomeDemoService.js

@@ -33,48 +33,48 @@ function buildWelcomeDemoService() {
         definition: SERVICE_DEFINITION,
         handlers: {
             createSession: (voice) => {
-                let sessionRef;
+                let mediaSessionRef;
                 voice.on(common_1.StreamEvent.DATA, (params) => {
                     try {
                         const { request, sayResponse } = params;
                         if (request) {
                             const { callerNumber } = request;
-                            sessionRef = request.sessionRef;
+                            mediaSessionRef = request.mediaSessionRef;
                             logger.verbose("welcome demo session started", {
-                                sessionRef,
+                                mediaSessionRef,
                                 callerNumber
                             });
                             voice.write({
                                 answerRequest: {
-                                    sessionRef: request.sessionRef
+                                    mediaSessionRef: request.mediaSessionRef
                                 }
                             });
                             voice.write({
                                 sayRequest: {
                                     text: "Welcome to Fonoster! Your system is configured correctly and ready for voice application development. Goodbye!",
-                                    sessionRef: request.sessionRef
+                                    mediaSessionRef: request.mediaSessionRef
                                 }
                             });
                         }
-                        if (sayResponse && sessionRef) {
+                        if (sayResponse && mediaSessionRef) {
                             logger.verbose("hanging up welcome demo session", {
-                                sessionRef
+                                mediaSessionRef
                             });
                             voice.write({
                                 hangupRequest: {
-                                    sessionRef
+                                    mediaSessionRef
                                 }
                             });
                         }
                     }
                     catch (error) {
                         logger.error("error in welcome demo session", {
-                            sessionRef,
+                            mediaSessionRef,
                             error
                         });
-                        if (sessionRef) {
+                        if (mediaSessionRef) {
                             voice.write({
-                                hangupRequest: { sessionRef }
+                                hangupRequest: { mediaSessionRef }
                             });
                         }
                         voice.end();
@@ -82,11 +82,11 @@ function buildWelcomeDemoService() {
                 });
                 voice.once(common_1.StreamEvent.END, () => {
                     voice.end();
-                    logger.verbose("welcome demo session ended", { sessionRef });
+                    logger.verbose("welcome demo session ended", { mediaSessionRef });
                 });
                 voice.on(common_1.StreamEvent.ERROR, (error) => {
                     logger.error("stream error in welcome demo session", {
-                        sessionRef,
+                        mediaSessionRef,
                         error
                     });
                     voice.end();

package/dist/voice/client/AudioSocketHandler.js

@@ -27,18 +27,18 @@ class AudioSocketHandler {
                 this.audioSocket.onConnection((req, res) => __awaiter(this, void 0, void 0, function* () {
                     logger.verbose("audio socket connection received", {
                         ref: req.ref,
-                        sessionRef: this.config.sessionRef
+                        mediaSessionRef: this.config.mediaSessionRef
                     });
                     (0, transcribeOnConnection_1.transcribeOnConnection)(this.transcriptionsStream)(req, res);
                     res.onClose(() => {
                         logger.verbose("session audio stream closed", {
-                            sessionRef: this.config.sessionRef
+                            mediaSessionRef: this.config.mediaSessionRef
                         });
                     });
                     res.onError((err) => {
                         logger.error("session audio stream error", {
                             error: err,
-                            sessionRef: this.config.sessionRef
+                            mediaSessionRef: this.config.mediaSessionRef
                         });
                     });
                     this.audioStream = res;

package/dist/voice/client/AuthorizationHandler.js

@@ -42,7 +42,7 @@ class AuthorizationHandler {
             if (!envs_1.AUTHZ_SERVICE_ENABLED) {
                 return true;
             }
-            const { sessionRef: channelId, accessKeyId } = this.config;
+            const { mediaSessionRef: channelId, accessKeyId } = this.config;
             try {
                 const authz = new authz_1.AuthzClient(`${envs_1.AUTHZ_SERVICE_HOST}:${envs_1.AUTHZ_SERVICE_PORT}`);
                 const authorized = yield authz.checkSessionAuthorized({ accessKeyId });
@@ -62,7 +62,7 @@ class AuthorizationHandler {
     }
     handleUnauthorizedSession() {
         return __awaiter(this, void 0, void 0, function* () {
-            const { sessionRef: channelId } = this.config;
+            const { mediaSessionRef: channelId } = this.config;
             try {
                 yield this.ari.channels.answer({ channelId });
                 yield this.ari.channels.play({ channelId, media: "sound:unavailable" });

package/dist/voice/client/ExternalMediaHandler.js

@@ -26,20 +26,20 @@ class ExternalMediaHandler {
             yield bridge.create({ type: "mixing" });
             logger.verbose("creating external media config", {
                 port,
-                sessionRef: this.config.sessionRef,
+                mediaSessionRef: this.config.mediaSessionRef,
                 bridgeId: bridge.id
             });
             channel.externalMedia((0, createExternalMediaConfig_1.createExternalMediaConfig)(port));
             channel.once(types_1.AriEvent.STASIS_START, (_, channel) => __awaiter(this, void 0, void 0, function* () {
-                bridge.addChannel({ channel: [this.config.sessionRef, channel.id] });
+                bridge.addChannel({ channel: [this.config.mediaSessionRef, channel.id] });
                 logger.verbose("added channel to bridge", {
-                    sessionRef: this.config.sessionRef,
+                    mediaSessionRef: this.config.mediaSessionRef,
                     channelId: channel.id
                 });
             }));
             channel.once("ChannelLeftBridge", () => __awaiter(this, void 0, void 0, function* () {
                 logger.verbose("channel left bridge", {
-                    sessionRef: this.config.sessionRef,
+                    mediaSessionRef: this.config.mediaSessionRef,
                     bridgeId: bridge.id
                 });
                 try {

package/dist/voice/client/SpeechHandler.d.ts

@@ -28,14 +28,14 @@ declare class SpeechHandler {
     private ari;
     private transcriptionsStream;
     private audioStream;
-    private sessionRef;
+    private mediaSessionRef;
     constructor(params: {
         tts: TextToSpeech;
         stt: SpeechToText;
         ari: Client;
         transcriptionsStream: Stream;
         audioStream: AudioStream;
-        sessionRef: string;
+        mediaSessionRef: string;
     });
     synthesize(text: string, options: SayOptions): Promise<string>;
     stopSynthesis(): Promise<void>;

package/dist/voice/client/SpeechHandler.js

@@ -20,7 +20,7 @@ class SpeechHandler {
         this.ari = params.ari;
         this.transcriptionsStream = params.transcriptionsStream;
         this.audioStream = params.audioStream;
-        this.sessionRef = params.sessionRef;
+        this.mediaSessionRef = params.mediaSessionRef;
     }
     synthesize(text, options) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -60,12 +60,14 @@ class SpeechHandler {
         out.on("data", callback);
         out.on("error", (error) => __awaiter(this, void 0, void 0, function* () {
             logger.error("speech recognition error", { error });
-            yield this.ari.channels.hangup({ channelId: this.sessionRef });
+            yield this.ari.channels.hangup({ channelId: this.mediaSessionRef });
         }));
     }
     startDtmfGather(callback) {
         return __awaiter(this, void 0, void 0, function* () {
-            const channel = yield this.ari.channels.get({ channelId: this.sessionRef });
+            const channel = yield this.ari.channels.get({
+                channelId: this.mediaSessionRef
+            });
             channel.on(types_1.AriEvent.CHANNEL_DTMF_RECEIVED, (event) => {
                 const { digit } = event;
                 callback({ digit });
@@ -78,7 +80,9 @@ class SpeechHandler {
             const { onDigitReceived, finishOnKey, maxDigits, timeout } = params;
             let result = "";
             let timeoutId = null;
-            const channel = yield this.ari.channels.get({ channelId: this.sessionRef });
+            const channel = yield this.ari.channels.get({
+                channelId: this.mediaSessionRef
+            });
             return new Promise((resolve) => {
                 const resetTimer = () => {
                     if (timeoutId) {

package/dist/voice/client/VoiceClientImpl.d.ts

@@ -50,11 +50,11 @@ declare class VoiceClientImpl implements VoiceClient {
         speech: string;
         responseTime: number;
     }) => void): void;
-    startDtmfGather(sessionRef: string, callback: (event: {
+    startDtmfGather(mediaSessionRef: string, callback: (event: {
         digit: string;
     }) => void): Promise<void>;
     waitForDtmf(params: {
-        sessionRef: string;
+        mediaSessionRef: string;
         finishOnKey: string;
         maxDigits: number;
         timeout: number;

package/dist/voice/client/VoiceClientImpl.js

@@ -90,7 +90,7 @@ class VoiceClientImpl {
                 ari: this.ari,
                 transcriptionsStream: this.transcriptionsStream,
                 audioStream: this.audioSocketHandler.getAudioStream(),
-                sessionRef: this.config.sessionRef
+                mediaSessionRef: this.config.mediaSessionRef
             });
             logger.verbose("voice client setup completed");
         });
@@ -122,7 +122,7 @@ class VoiceClientImpl {
     startSpeechGather(callback) {
         this.speechHandler.startSpeechGather(callback);
     }
-    startDtmfGather(sessionRef, callback) {
+    startDtmfGather(mediaSessionRef, callback) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.speechHandler.startDtmfGather(callback);
         });

package/dist/voice/createCreateVoiceClient.js

@@ -30,6 +30,7 @@ exports.createCreateVoiceClient = createCreateVoiceClient;
  */
 const identity_1 = require("@fonoster/identity");
 const logger_1 = require("@fonoster/logger");
+const uuid_1 = require("uuid");
 const identityConfig_1 = require("../core/identityConfig");
 const mapCallDirectionToEnum_1 = require("../events/mapCallDirectionToEnum");
 const client_1 = require("./client");
@@ -41,21 +42,26 @@ const generateCallAccessToken = (0, identity_1.createGenerateCallAccessToken)(id
 function createCreateVoiceClient(createContainer) {
     return function createVoiceClient(params) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d, _e;
+            var _a, _b, _c, _d, _e, _f;
             const { ari, event, channel } = params;
-            const { id: sessionRef, caller } = event.channel;
+            const { id: mediaSessionRef, caller } = event.channel;
             const { name: callerName, number: callerNumber } = caller;
             const getChannelVar = (0, createGetChannelVarWithoutThrow_1.createGetChannelVarWithoutThrow)(channel);
             // Variables set by Asterisk's dialplan
             const callDirection = (_a = (yield getChannelVar(types_1.ChannelVar.CALL_DIRECTION))) === null || _a === void 0 ? void 0 : _a.value;
             const appRef = (_b = (yield getChannelVar(types_1.ChannelVar.APP_REF))) === null || _b === void 0 ? void 0 : _b.value;
             const ingressNumber = ((_c = (yield getChannelVar(types_1.ChannelVar.INGRESS_NUMBER))) === null || _c === void 0 ? void 0 : _c.value) || "";
+            // Try to get callRef from channel variable (set by dialplan from X-Call-Ref header for API-originated calls)
+            // If not found, generate a new UUID (for PSTN-terminated calls)
+            const callRefFromChannel = (_d = (yield getChannelVar(types_1.ChannelVar.CALL_REF))) === null || _d === void 0 ? void 0 : _d.value;
+            const callRef = callRefFromChannel || (0, uuid_1.v4)();
             const { accessKeyId, endpoint, tts, stt } = yield createContainer(appRef);
             const sessionToken = yield generateCallAccessToken({ accessKeyId, appRef });
-            const metadataStr = (_e = (_d = (yield getChannelVar(types_1.ChannelVar.METADATA))) === null || _d === void 0 ? void 0 : _d.value) !== null && _e !== void 0 ? _e : "{}";
+            const metadataStr = (_f = (_e = (yield getChannelVar(types_1.ChannelVar.METADATA))) === null || _e === void 0 ? void 0 : _e.value) !== null && _f !== void 0 ? _f : "{}";
             const config = {
                 appRef,
-                sessionRef,
+                mediaSessionRef,
+                callRef,
                 accessKeyId,
                 endpoint,
                 callerName,

package/dist/voice/handlers/createAnswerHandler.js

@@ -13,11 +13,11 @@ exports.createAnswerHandler = createAnswerHandler;
 const withErrorHandling_1 = require("./utils/withErrorHandling");
 function createAnswerHandler(ari, voiceClient) {
     return (0, withErrorHandling_1.withErrorHandling)((request) => __awaiter(this, void 0, void 0, function* () {
-        const { sessionRef } = request;
-        yield ari.channels.answer({ channelId: sessionRef });
+        const { mediaSessionRef } = request;
+        yield ari.channels.answer({ channelId: mediaSessionRef });
         voiceClient.sendResponse({
             answerResponse: {
-                sessionRef
+                mediaSessionRef
             }
         });
     }));

package/dist/voice/handlers/createHangupHandler.js

@@ -13,13 +13,13 @@ exports.createHangupHandler = createHangupHandler;
 const withErrorHandling_1 = require("./utils/withErrorHandling");
 function createHangupHandler(ari, voiceClient) {
     return (0, withErrorHandling_1.withErrorHandling)((request) => __awaiter(this, void 0, void 0, function* () {
-        const { sessionRef } = request;
+        const { mediaSessionRef } = request;
         // Give some time for the last sound to play
         setTimeout(() => {
-            ari.channels.hangup({ channelId: sessionRef });
+            ari.channels.hangup({ channelId: mediaSessionRef });
             voiceClient.sendResponse({
                 hangupResponse: {
-                    sessionRef
+                    mediaSessionRef
                 }
             });
             voiceClient.close();

package/dist/voice/handlers/createMuteHandler.js

@@ -13,14 +13,14 @@ exports.createMuteHandler = createMuteHandler;
 const withErrorHandling_1 = require("./utils/withErrorHandling");
 function createMuteHandler(ari, voiceClient) {
     return (0, withErrorHandling_1.withErrorHandling)((request) => __awaiter(this, void 0, void 0, function* () {
-        const { sessionRef, direction } = request;
+        const { mediaSessionRef, direction } = request;
         yield ari.channels.mute({
-            channelId: sessionRef,
+            channelId: mediaSessionRef,
             direction
         });
         voiceClient.sendResponse({
             muteResponse: {
-                sessionRef
+                mediaSessionRef
             }
         });
     }));

package/dist/voice/handlers/createPlayDtmfHandler.js

@@ -13,14 +13,14 @@ exports.createPlayDtmfHandler = createPlayDtmfHandler;
 const withErrorHandling_1 = require("./utils/withErrorHandling");
 function createPlayDtmfHandler(ari, voiceClient) {
     return (0, withErrorHandling_1.withErrorHandling)((request) => __awaiter(this, void 0, void 0, function* () {
-        const { sessionRef, digits } = request;
+        const { mediaSessionRef, digits } = request;
         yield ari.channels.sendDTMF({
-            channelId: sessionRef,
+            channelId: mediaSessionRef,
             dtmf: digits
         });
         voiceClient.sendResponse({
             playDtmfResponse: {
-                sessionRef
+                mediaSessionRef
             }
         });
     }));

package/dist/voice/handlers/createPlayHandler.js

@@ -15,17 +15,17 @@ const awaitForPlaybackFinished_1 = require("./utils/awaitForPlaybackFinished");
 const withErrorHandling_1 = require("./utils/withErrorHandling");
 function createPlayHandler(ari, voiceClient) {
     return (0, withErrorHandling_1.withErrorHandling)((request) => __awaiter(this, void 0, void 0, function* () {
-        const { sessionRef } = request;
+        const { mediaSessionRef } = request;
         const playbackRef = request.playbackRef || (0, nanoid_1.nanoid)(10);
         yield ari.channels.play({
-            channelId: sessionRef,
+            channelId: mediaSessionRef,
             media: `sound:${request.url}`,
             playbackId: playbackRef
         });
         yield (0, awaitForPlaybackFinished_1.awaitForPlaybackFinished)(ari, playbackRef);
         voiceClient.sendResponse({
             playResponse: {
-                sessionRef,
+                mediaSessionRef,
                 playbackRef
             }
         });

package/dist/voice/handlers/createPlaybackControlHandler.js

@@ -32,7 +32,7 @@ const common_1 = require("@fonoster/common");
 const zod_1 = require("zod");
 const withErrorHandling_1 = require("./utils/withErrorHandling");
 const requestSchema = zod_1.z.object({
-    sessionRef: zod_1.z.string(),
+    mediaSessionRef: zod_1.z.string(),
     playbackRef: zod_1.z.string().optional(),
     action: zod_1.z.nativeEnum(common_1.PlaybackControlAction, {
         message: "Invalid playback control action."
@@ -41,7 +41,7 @@ const requestSchema = zod_1.z.object({
 function createPlaybackControlHandler(ari, voiceClient) {
     return (0, withErrorHandling_1.withErrorHandling)((playbackControlReq) => __awaiter(this, void 0, void 0, function* () {
         requestSchema.parse(playbackControlReq);
-        const { sessionRef, playbackRef: playbackId, action } = playbackControlReq;
+        const { mediaSessionRef, playbackRef: playbackId, action } = playbackControlReq;
         try {
             if (action === common_1.PlaybackControlAction.STOP) {
                 yield ari.playbacks.stop({ playbackId });
@@ -55,7 +55,7 @@ function createPlaybackControlHandler(ari, voiceClient) {
         }
         voiceClient.sendResponse({
             playbackControlResponse: {
-                sessionRef
+                mediaSessionRef
             }
         });
     }));

package/dist/voice/handlers/createRecordHandler.js

@@ -34,10 +34,10 @@ const awaitForRecordingFinished_1 = require("./utils/awaitForRecordingFinished")
 const withErrorHandling_1 = require("./utils/withErrorHandling");
 function createRecordHandler(ari, voiceClient) {
     return (0, withErrorHandling_1.withErrorHandling)((request) => __awaiter(this, void 0, void 0, function* () {
-        const { sessionRef, maxDuration, maxSilence, beep, finishOnKey } = request;
+        const { mediaSessionRef, maxDuration, maxSilence, beep, finishOnKey } = request;
         const name = (0, nanoid_1.nanoid)(10);
         yield ari.channels.record({
-            channelId: sessionRef,
+            channelId: mediaSessionRef,
             format: common_1.RecordFormat.WAV,
             name,
             beep,
@@ -48,7 +48,7 @@ function createRecordHandler(ari, voiceClient) {
         const { duration } = yield (0, awaitForRecordingFinished_1.awaitForRecordingFinished)(ari, name);
         voiceClient.sendResponse({
             recordResponse: {
-                sessionRef,
+                mediaSessionRef,
                 name,
                 format: common_1.RecordFormat.WAV,
                 duration

package/dist/voice/handlers/createSayHandler.js

@@ -15,7 +15,7 @@ const zod_1 = require("zod");
 const withErrorHandling_1 = require("./utils/withErrorHandling");
 const sayRequestSchema = zod_1.z.object({
     text: zod_1.z.string(),
-    sessionRef: zod_1.z.string(),
+    mediaSessionRef: zod_1.z.string(),
     options: zod_1.z.record(zod_1.z.unknown()).optional()
 });
 function createSayHandler(ari, voiceClient) {
@@ -24,7 +24,7 @@ function createSayHandler(ari, voiceClient) {
         yield voiceClient.synthesize(request.text, request.options ? pb_util_1.struct.decode(request.options) : {});
         voiceClient.sendResponse({
             sayResponse: {
-                sessionRef: request.sessionRef
+                mediaSessionRef: request.mediaSessionRef
             }
         });
     }));

package/dist/voice/handlers/createStopSayHandler.js

@@ -13,12 +13,12 @@ exports.createStopSayHandler = createStopSayHandler;
 const zod_1 = require("zod");
 const withErrorHandling_1 = require("./utils/withErrorHandling");
 const requestSchema = zod_1.z.object({
-    sessionRef: zod_1.z.string()
+    mediaSessionRef: zod_1.z.string()
 });
 function createStopSayHandler(voiceClient) {
     return (0, withErrorHandling_1.withErrorHandling)((stopSayReq) => __awaiter(this, void 0, void 0, function* () {
         requestSchema.parse(stopSayReq);
-        const { sessionRef } = stopSayReq;
+        const { mediaSessionRef } = stopSayReq;
         try {
             voiceClient.stopSynthesis();
         }
@@ -27,7 +27,7 @@ function createStopSayHandler(voiceClient) {
         }
         voiceClient.sendResponse({
             stopSayResponse: {
-                sessionRef
+                mediaSessionRef
             }
         });
     }));

package/dist/voice/handlers/createStreamGatherHandler.js

@@ -38,15 +38,15 @@ const gatherRequestSchema = zod_1.z.object({
 });
 function createStreamGatherHandler(voiceClient) {
     return (0, withErrorHandling_1.withErrorHandling)((request) => __awaiter(this, void 0, void 0, function* () {
-        const { sessionRef, source } = request;
+        const { mediaSessionRef, source } = request;
         gatherRequestSchema.parse(request);
         const effectiveSource = source || common_1.StreamGatherSource.SPEECH_AND_DTMF;
         if (effectiveSource.includes(common_1.StreamGatherSource.DTMF)) {
-            voiceClient.startDtmfGather(sessionRef, (event) => {
+            voiceClient.startDtmfGather(mediaSessionRef, (event) => {
                 const { digit } = event;
                 voiceClient.sendResponse({
                     streamGatherPayload: {
-                        sessionRef,
+                        mediaSessionRef,
                         digit,
                         responseTime: 0
                     }
@@ -58,7 +58,7 @@ function createStreamGatherHandler(voiceClient) {
                 const { speech, responseTime } = event;
                 voiceClient.sendResponse({
                     streamGatherPayload: {
-                        sessionRef,
+                        mediaSessionRef,
                         speech,
                         responseTime
                     }
@@ -67,7 +67,7 @@ function createStreamGatherHandler(voiceClient) {
         }
         voiceClient.sendResponse({
             startStreamGatherResponse: {
-                sessionRef
+                mediaSessionRef
             }
         });
     }));

package/dist/voice/handlers/createStreamHandler.js

@@ -41,7 +41,7 @@ const streamRequestSchema = zod_1.z.object({
 });
 function createStreamHandler(voiceClient) {
     return (0, withErrorHandling_1.withErrorHandling)((request) => __awaiter(this, void 0, void 0, function* () {
-        const { sessionRef, direction, format } = request;
+        const { mediaSessionRef, direction, format } = request;
         streamRequestSchema.parse(request);
         const effectiveDirection = direction || common_1.StreamDirection.BOTH;
         const effectiveFormat = format || common_1.StreamAudioFormat.WAV;
@@ -51,7 +51,7 @@ function createStreamHandler(voiceClient) {
             voiceClient.getTranscriptionsStream().on("data", (data) => {
                 voiceClient.sendResponse({
                     streamPayload: {
-                        sessionRef,
+                        mediaSessionRef,
                         type: common_1.StreamMessageType.AUDIO_OUT,
                         data,
                         streamRef: "fixme",
@@ -62,7 +62,7 @@ function createStreamHandler(voiceClient) {
         }
         voiceClient.sendResponse({
             startStreamResponse: {
-                sessionRef,
+                mediaSessionRef,
                 streamRef: "fixme"
             }
         });

package/dist/voice/handlers/createUnmuteHandler.js

@@ -13,14 +13,14 @@ exports.createUnmuteHandler = createUnmuteHandler;
 const withErrorHandling_1 = require("./utils/withErrorHandling");
 function createUnmuteHandler(ari, voiceClient) {
     return (0, withErrorHandling_1.withErrorHandling)((request) => __awaiter(this, void 0, void 0, function* () {
-        const { sessionRef, direction } = request;
+        const { mediaSessionRef, direction } = request;
         yield ari.channels.unmute({
-            channelId: sessionRef,
+            channelId: mediaSessionRef,
             direction
         });
         voiceClient.sendResponse({
             muteResponse: {
-                sessionRef
+                mediaSessionRef
             }
         });
     }));

package/dist/voice/handlers/dial/createDialHandler.js

@@ -41,7 +41,7 @@ const handleStasisStart_1 = require("./handleStasisStart");
 function createDialHandler(ari, voiceClient) {
     return function dial(request) {
         return __awaiter(this, void 0, void 0, function* () {
-            const { sessionRef: channelId, destination, timeout } = request;
+            const { mediaSessionRef: channelId, destination, timeout } = request;
             const bridge = yield ari.bridges.create({
                 type: "mixing"
             });

package/dist/voice/handlers/dial/recordChannel.d.ts

@@ -18,5 +18,5 @@
  */
 import { DialRecordDirection } from "@fonoster/common";
 import { Client } from "ari-client";
-declare function recordChannel(ari: Client, direction: DialRecordDirection.IN | DialRecordDirection.OUT, sessionRef: string): Promise<import("ari-client").LiveRecording>;
+declare function recordChannel(ari: Client, direction: DialRecordDirection.IN | DialRecordDirection.OUT, mediaSessionRef: string): Promise<import("ari-client").LiveRecording>;
 export { recordChannel };

package/dist/voice/handlers/dial/recordChannel.js

@@ -29,18 +29,18 @@ exports.recordChannel = recordChannel;
  * limitations under the License.
  */
 const common_1 = require("@fonoster/common");
-function recordChannel(ari, direction, sessionRef) {
+function recordChannel(ari, direction, mediaSessionRef) {
     return __awaiter(this, void 0, void 0, function* () {
         const spy = direction.toLowerCase();
         const channel = yield ari.channels.snoopChannel({
             app: common_1.STASIS_APP_NAME,
-            channelId: sessionRef,
+            channelId: mediaSessionRef,
             spy
         });
         return ari.channels.record({
             channelId: channel.id,
             format: common_1.RecordFormat.WAV,
-            name: `${sessionRef}_${spy}`
+            name: `${mediaSessionRef}_${spy}`
         });
     });
 }

package/dist/voice/handlers/gather/createGatherHandler.js

@@ -54,7 +54,7 @@ const gatherRequestSchema = zod_1.z.object({
 });
 function createGatherHandler(voiceClient) {
     return (0, withErrorHandling_1.withErrorHandling)((request) => __awaiter(this, void 0, void 0, function* () {
-        const { sessionRef, source, timeout, finishOnKey, maxDigits } = request;
+        const { mediaSessionRef, source, timeout, finishOnKey, maxDigits } = request;
         gatherRequestSchema.parse(request);
         const { timeoutPromise, effectiveTimeout } = (0, getTimeoutPromise_1.getTimeoutPromise)(timeout);
         const effectiveSource = source || common_1.GatherSource.SPEECH_AND_DTMF;
@@ -65,7 +65,7 @@ function createGatherHandler(voiceClient) {
         if (effectiveSource.includes(common_1.GatherSource.DTMF)) {
             promises.push(voiceClient
                 .waitForDtmf({
-                sessionRef,
+                mediaSessionRef,
                 finishOnKey,
                 maxDigits,
                 timeout: effectiveTimeout,
@@ -76,7 +76,7 @@ function createGatherHandler(voiceClient) {
         const result = (yield Promise.race(promises));
         voiceClient.sendResponse({
             gatherResponse: {
-                sessionRef,
+                mediaSessionRef,
                 responseTime: result.responseTime,
                 speech: (0, utils_1.isDtmf)(result.digits) ? undefined : result.speech,
                 digits: (0, utils_1.isDtmf)(result.digits) ? result.digits : undefined

package/dist/voice/stt/Deepgram.js

@@ -83,6 +83,16 @@ class Deepgram extends AbstractSpeechToText_1.AbstractSpeechToText {
     streamTranscribe(stream) {
         const connection = this.client.listen.live(buildTranscribeConfig(this.engineConfig.config));
         const out = new stream_1.Stream();
+        // Track last transcript for UtteranceEnd fallback
+        // According to Deepgram docs: "If you receive an UtteranceEnd event without a
+        // preceding speech_final: true, it's advisable to process the last-received
+        // transcript as a complete utterance."
+        // UtteranceEnd fires after finalized words, so we store the last finalized transcript
+        // but also keep any transcript as a fallback
+        let lastFinalizedTranscript = null;
+        let lastFinalizedTranscriptTime = 0;
+        let lastAnyTranscript = null;
+        let lastAnyTranscriptTime = 0;
         // Add error handler immediately to catch any connection errors
         connection.on(LiveTranscriptionEvents.Error, (err) => {
             logger.error("error on Deepgram connection", { err });
@@ -106,8 +116,23 @@ class Deepgram extends AbstractSpeechToText_1.AbstractSpeechToText {
             });
             connection.on(LiveTranscriptionEvents.Transcript, (data) => {
                 var _a, _b, _c;
-                if (!((_c = (_b = (_a = data.channel) === null || _a === void 0 ? void 0 : _a.alternatives) === null || _b === void 0 ? void 0 : _b[0]) === null || _c === void 0 ? void 0 : _c.transcript) ||
-                    !data.speech_final) {
+                const transcript = (_c = (_b = (_a = data.channel) === null || _a === void 0 ? void 0 : _a.alternatives) === null || _b === void 0 ? void 0 : _b[0]) === null || _c === void 0 ? void 0 : _c.transcript;
+                const hasTranscript = !!transcript;
+                const isFinal = data.is_final === true;
+                const speechFinal = data.speech_final === true;
+                // Store any transcript for UtteranceEnd fallback
+                if (hasTranscript) {
+                    lastAnyTranscript = transcript;
+                    lastAnyTranscriptTime = Date.now();
+                    // Store finalized transcripts separately (preferred for UtteranceEnd)
+                    if (isFinal || speechFinal) {
+                        lastFinalizedTranscript = transcript;
+                        lastFinalizedTranscriptTime = Date.now();
+                    }
+                }
+                // Process transcript if it has content and is final
+                // Check both speech_final (primary) and is_final (backup)
+                if (!hasTranscript || (!speechFinal && !isFinal)) {
                     return;
                 }
                 const words = data.channel.alternatives[0].words || [];
@@ -117,13 +142,55 @@ class Deepgram extends AbstractSpeechToText_1.AbstractSpeechToText {
                         words.length
                     : 0;
                 logger.verbose("transcribe result", {
-                    speech: data.channel.alternatives[0].transcript,
-                    responseTime
+                    speech: transcript,
+                    responseTime,
+                    isFinal,
+                    speechFinal
                 });
                 out.emit("data", {
-                    speech: data.channel.alternatives[0].transcript,
+                    speech: transcript,
                     responseTime
                 });
+                // Clear transcripts after processing (they've been emitted)
+                lastFinalizedTranscript = null;
+                lastAnyTranscript = null;
+            });
+            // CRITICAL: Handle UtteranceEnd events (fallback when speech_final never becomes true)
+            // This is Deepgram's recommended fallback mechanism for noisy environments
+            // UtteranceEnd requires: interim_results=true and utterance_end_ms parameter
+            // UtteranceEnd fires after finalized words, so prefer lastFinalizedTranscript
+            connection.on(LiveTranscriptionEvents.UtteranceEnd, (data) => {
+                // Prefer finalized transcript, fall back to any transcript
+                const transcriptToUse = lastFinalizedTranscript || lastAnyTranscript;
+                const transcriptTime = lastFinalizedTranscript
+                    ? lastFinalizedTranscriptTime
+                    : lastAnyTranscriptTime;
+                if (transcriptToUse) {
+                    // Use last_word_end from UtteranceEnd event if available for more accurate timing
+                    // Otherwise fall back to time since last transcript
+                    const lastWordEnd = data === null || data === void 0 ? void 0 : data.last_word_end;
+                    const responseTime = lastWordEnd
+                        ? lastWordEnd * 1000 // Convert seconds to milliseconds
+                        : transcriptTime
+                            ? Date.now() - transcriptTime
+                            : 0;
+                    logger.info("Deepgram UtteranceEnd - processing last transcript", {
+                        speech: transcriptToUse,
+                        responseTime,
+                        lastWordEnd: lastWordEnd,
+                        wasFinalized: !!lastFinalizedTranscript
+                    });
+                    out.emit("data", {
+                        speech: transcriptToUse,
+                        responseTime
+                    });
+                    // Clear transcripts after processing
+                    lastFinalizedTranscript = null;
+                    lastAnyTranscript = null;
+                }
+                else {
+                    logger.warn("Deepgram UtteranceEnd received but no last transcript available");
+                }
             });
         });
         // Handle stream errors and cleanup
@@ -212,7 +279,9 @@ class Deepgram extends AbstractSpeechToText_1.AbstractSpeechToText {
                 .optional(),
             model: z
                 .nativeEnum(types_1.DeepgramModel, { message: "Invalid Deepgram model" })
-                .optional()
+                .optional(),
+            interimResults: z.boolean().optional(),
+            utteranceEndMs: z.number().int().min(1000).max(5000).optional()
         });
     }
     static getCredentialsValidationSchema() {
@@ -223,7 +292,17 @@ class Deepgram extends AbstractSpeechToText_1.AbstractSpeechToText {
 }
 exports.Deepgram = Deepgram;
 function buildTranscribeConfig(config) {
-    return Object.assign(Object.assign({}, config), { model: config.model || types_1.DeepgramModel.NOVA_2_PHONECALL, language: config.languageCode || common_1.VoiceLanguage.EN_US, encoding: "linear16", sample_rate: 16000, channels: 1, smart_format: config.smartFormat || true, 
+    // UtteranceEnd requires interim_results to be enabled
+    // Default to true to enable UtteranceEnd fallback mechanism
+    const interimResults = config.interimResults !== false;
+    // Default utterance_end_ms to 1000ms (minimum required value)
+    // This enables UtteranceEnd events as a fallback when speech_final never becomes true
+    const utteranceEndMs = config.utteranceEndMs || 1000;
+    return Object.assign(Object.assign({}, config), { model: config.model || types_1.DeepgramModel.NOVA_2_PHONECALL, language: config.languageCode || common_1.VoiceLanguage.EN_US, encoding: "linear16", sample_rate: 16000, channels: 1, smart_format: config.smartFormat !== false, 
         // This needs to be set to true to avoid delays while using smart_format
-        no_delay: config.noDelay || true });
+        no_delay: config.noDelay !== false, 
+        // REQUIRED for UtteranceEnd: interim_results must be true
+        interim_results: interimResults, 
+        // REQUIRED for UtteranceEnd: utterance_end_ms parameter
+        utterance_end_ms: utteranceEndMs });
 }

package/dist/voice/stt/types.d.ts

@@ -51,6 +51,8 @@ type DeepgramSttConfig = {
         model: DeepgramModel;
         smartFormat: boolean;
         noDelay: boolean;
+        interimResults?: boolean;
+        utteranceEndMs?: number;
     };
     credentials: {
         apiKey: string;

package/dist/voice/types/ari.d.ts

@@ -35,6 +35,7 @@ declare enum ChannelVar {
     APP_REF = "APP_REF",
     APP_ENDPOINT = "APP_ENDPOINT",
     METADATA = "METADATA",
-    FROM_EXTERNAL_MEDIA = "FROM_EXTERNAL_MEDIA"
+    FROM_EXTERNAL_MEDIA = "FROM_EXTERNAL_MEDIA",
+    CALL_REF = "CALL_REF"
 }
 export { AriEvent, ChannelVar };

package/dist/voice/types/ari.js

@@ -41,4 +41,5 @@ var ChannelVar;
     ChannelVar["APP_ENDPOINT"] = "APP_ENDPOINT";
     ChannelVar["METADATA"] = "METADATA";
     ChannelVar["FROM_EXTERNAL_MEDIA"] = "FROM_EXTERNAL_MEDIA";
+    ChannelVar["CALL_REF"] = "CALL_REF";
 })(ChannelVar || (exports.ChannelVar = ChannelVar = {}));

package/dist/voice/types/voice.d.ts

@@ -32,12 +32,12 @@ type VoiceClient = {
         speech: string;
         responseTime: number;
     }) => void) => void;
-    startDtmfGather: (sessionRef: string, callback: (event: {
+    startDtmfGather: (mediaSessionRef: string, callback: (event: {
         digit: string;
     }) => void) => void;
     stopStreamGather: () => void;
     waitForDtmf: (params: {
-        sessionRef: string;
+        mediaSessionRef: string;
         finishOnKey: string;
         maxDigits: number;
         timeout: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fonoster/apiserver",
-  "version": "0.16.10",
+  "version": "0.17.0",
   "description": "APIServer for Fonoster",
   "author": "Pedro Sanders <psanders@fonoster.com>",
   "homepage": "https://github.com/fonoster/fonoster#readme",
@@ -22,14 +22,14 @@
   },
   "dependencies": {
     "@deepgram/sdk": "^3.5.1",
-    "@fonoster/authz": "^0.16.10",
-    "@fonoster/autopilot": "^0.16.10",
-    "@fonoster/common": "^0.16.8",
-    "@fonoster/identity": "^0.16.10",
-    "@fonoster/logger": "^0.16.7",
-    "@fonoster/sipnet": "^0.16.10",
-    "@fonoster/streams": "^0.16.7",
-    "@fonoster/types": "^0.16.7",
+    "@fonoster/authz": "^0.17.0",
+    "@fonoster/autopilot": "^0.17.0",
+    "@fonoster/common": "^0.17.0",
+    "@fonoster/identity": "^0.17.0",
+    "@fonoster/logger": "^0.17.0",
+    "@fonoster/sipnet": "^0.17.0",
+    "@fonoster/streams": "^0.17.0",
+    "@fonoster/types": "^0.17.0",
     "@google-cloud/speech": "^6.6.0",
     "@google-cloud/text-to-speech": "^5.3.0",
     "@grpc/grpc-js": "~1.10.11",
@@ -76,5 +76,5 @@
     "@types/uuid": "^10.0.0",
     "@types/validator": "^13.15.10"
   },
-  "gitHead": "01b11ee98556983fa4dae5aabc0daa66bcbe9e82"
+  "gitHead": "4d1a9afaec6f294184386e009d1a4e292fb3583b"
 }