botium-connector-voip 0.0.21 → 0.0.23

package/src/connector.js

@@ -6,6 +6,23 @@ const https = require('https')
 const debug = require('debug')('botium-connector-voip')
 const mm = require('music-metadata')
 
+// Logging policy: info = rare, business-relevant lifecycle events (always visible).
+// debug = high-frequency diagnostics (DEBUG=botium-connector-voip). warn = degraded but continuing.
+// error = abort/failure. No secrets in info; STT text only as length or truncated in info.
+
+const _info = (event, data) => {
+  const parts = Object.entries({ event, ...data })
+    .filter(([, v]) => v != null && v !== '')
+    .map(([k, v]) => `${k}=${typeof v === 'string' && v.length > 80 ? `"${v.substring(0, 77)}..."` : JSON.stringify(v)}`)
+  console.info(`[botium-connector-voip] ${parts.join(' ')}`)
+}
+
+/** DTMF for RTP/PJSIP: 0–9, *, #, A–D. Strips spaces and other separators so the worker gets one compact string. */
+const sanitizeDtmfDigits = (raw) => {
+  if (raw == null) return ''
+  return String(raw).replace(/[^0-9*#ABCDabcd]/g, '').toUpperCase()
+}
+
 const Capabilities = {
   VOIP_STT_URL_STREAM: 'VOIP_STT_URL_STREAM',
   VOIP_STT_PARAMS_STREAM: 'VOIP_STT_PARAMS_STREAM',
@@ -53,7 +70,8 @@ const Capabilities = {
   VOIP_SILENCE_DURATION_TIMEOUT_START_ENABLE: 'VOIP_SILENCE_DURATION_TIMEOUT_START_ENABLE',
   VOIP_SILENCE_DURATION_TIMEOUT_START: 'VOIP_SILENCE_DURATION_TIMEOUT_START',
   VOIP_STT_CONFIDENCE_THRESHOLD: 'VOIP_STT_CONFIDENCE_THRESHOLD',
-  VOIP_USE_GLOBAL_VOIP_WORKER: 'VOIP_USE_GLOBAL_VOIP_WORKER'
+  VOIP_USE_GLOBAL_VOIP_WORKER: 'VOIP_USE_GLOBAL_VOIP_WORKER',
+  VOIP_USER_INPUT_PREFER_VOICE: 'VOIP_USER_INPUT_PREFER_VOICE'
 }
 
 const Defaults = {
@@ -76,7 +94,8 @@ const Defaults = {
   VOIP_SILENCE_DURATION_TIMEOUT_START_ENABLE: false,
   VOIP_STT_CONFIDENCE_THRESHOLD: 0.5,
   VOIP_USE_GLOBAL_VOIP_WORKER: false,
-  VOIP_SIP_PROTOCOL: 'TCP'
+  VOIP_SIP_PROTOCOL: 'TCP',
+  VOIP_USER_INPUT_PREFER_VOICE: true
 }
 
 const TTS_HTTP_AGENT = new http.Agent({ keepAlive: true })
@@ -200,7 +219,8 @@ class BotiumConnectorVoip {
 
     let data = null
     let headers = null
-    const connect = async (retryIndex) => {
+    let httpInitRetries = 0
+    const connectHttp = async (retryIndex) => {
       retryIndex = retryIndex || 0
       try {
         const workerUrl = this.caps[Capabilities.VOIP_USE_GLOBAL_VOIP_WORKER]
@@ -223,18 +243,22 @@ class BotiumConnectorVoip {
         if (retryIndex === this.caps[Capabilities.VOIP_WEBSOCKET_CONNECT_MAXRETRIES]) {
           throw new Error(`Connecting to VOIP Worker failed: ${err.message || 'Not reachable'}`)
         }
+        httpInitRetries = retryIndex + 1
         // Retry after the defined timeout
         await new Promise(resolve => setTimeout(resolve, this.caps[Capabilities.VOIP_WEBSOCKET_CONNECT_TIMEOUT]))
 
         // Retry the connection
-        await connect(retryIndex + 1)
+        await connectHttp(retryIndex + 1)
       }
     }
-    await connect()
+    await connectHttp()
+    if (httpInitRetries > 0) {
+      _info('connected_after_retries', { phase: 'initCall', retries: httpInitRetries })
+    }
 
     return new Promise((resolve, reject) => {
       const wsEndpoint = `${this.caps[Capabilities.VOIP_USE_GLOBAL_VOIP_WORKER] ? process.env.BOTIUM_VOIP_WORKER_URL : this.caps[Capabilities.VOIP_WORKER_URL]}/ws/${data.port}`
-      const connect = (retryIndex) => {
+      const connectWs = (retryIndex) => {
         retryIndex = retryIndex || 0
         return new Promise((resolve, reject) => {
           if ('set-cookie' in headers) {
@@ -247,17 +271,20 @@ class BotiumConnectorVoip {
             this.ws = new WebSocket(wsEndpoint)
           }
           this.ws.on('open', () => {
-            resolve()
+            resolve(retryIndex)
           })
           this.ws.on('error', () => {
             if (retryIndex === this.caps[Capabilities.VOIP_WEBSOCKET_CONNECT_MAXRETRIES]) {
               reject(new Error(`Websocket connection failed to ${wsEndpoint}`))
             }
-            setTimeout(() => connect(retryIndex + 1).then(resolve).catch(reject), this.caps[Capabilities.VOIP_WEBSOCKET_CONNECT_TIMEOUT])
+            setTimeout(() => connectWs(retryIndex + 1).then(resolve).catch(reject), this.caps[Capabilities.VOIP_WEBSOCKET_CONNECT_TIMEOUT])
           })
         })
       }
-      connect().then(() => {
+      connectWs().then((wsRetries) => {
+        if (wsRetries > 0) {
+          _info('connected_after_retries', { phase: 'websocket', retries: wsRetries })
+        }
         if (!_.isArray(this.caps[Capabilities.VOIP_ICE_STUN_SERVERS])) {
           if (_.isEmpty(this.caps[Capabilities.VOIP_ICE_STUN_SERVERS])) {
             this.caps[Capabilities.VOIP_ICE_STUN_SERVERS] = []
@@ -301,6 +328,7 @@ class BotiumConnectorVoip {
 
         this.silence = null
         this.msgCount = 0
+        this.sttPartialCount = 0
         this.firstMsg = true
         this.firstSttInfoReceived = false
         this.silenceTimeout = null
@@ -468,6 +496,10 @@ class BotiumConnectorVoip {
 
           if (parsedData && parsedData.type === 'callinfo' && parsedData.status === 'initialized') {
             this.sessionId = parsedData.voipConfig.sessionId
+            _info('callinfo_initialized', {
+              sessionId: this.sessionId,
+              sttHandling: this.caps[Capabilities.VOIP_STT_MESSAGE_HANDLING]
+            })
           }
 
           // if sessionId is not the same as the one in the callinfo, return
@@ -485,10 +517,16 @@ class BotiumConnectorVoip {
           }
 
           if (parsedData && parsedData.type === 'callinfo' && parsedData.status === 'connected') {
+            _info('callinfo_connected', { sessionId: this.sessionId })
             resolve()
           }
 
           if (parsedData && parsedData.type === 'callinfo' && parsedData.status === 'disconnected') {
+            _info('callinfo_disconnected', {
+              sessionId: this.sessionId,
+              connectDurationSec: parsedData.connectDuration || null,
+              sttPartialCount: this.sttPartialCount
+            })
             const apiKey = this._extractApiKey(this._getBody(Capabilities.VOIP_STT_BODY))
             if (parsedData.connectDuration && parsedData.connectDuration > 0) {
               this.eventEmitter.emit('CONSUMPTION_METADATA', this, {
@@ -519,7 +557,9 @@ class BotiumConnectorVoip {
           if (parsedData && parsedData.type === 'fullRecordEnd') {
             const tail = _extractFullRecordBase64(parsedData)
             if (tail) this.fullRecord = (this.fullRecord || '') + tail
+            const base64Len = (this.fullRecord || tail || '').length
             emitFullRecordAttachment(this.fullRecord || tail)
+            _info('recording_attached', { sessionId: this.sessionId, source: 'fullRecordEnd', base64Len })
             this.end = true
           }
 
@@ -534,11 +574,14 @@ class BotiumConnectorVoip {
 
           if (parsedData && parsedData.type === 'fullRecord') {
             // Non-chunked full record
-            emitFullRecordAttachment(_extractFullRecordBase64(parsedData))
+            const base64 = _extractFullRecordBase64(parsedData)
+            emitFullRecordAttachment(base64)
+            _info('recording_attached', { sessionId: this.sessionId, source: 'fullRecord', base64Len: (base64 || '').length })
             this.end = true
           }
 
           if (parsedData && parsedData.data && parsedData.data.final === false) {
+            this.sttPartialCount++
             if (this.silenceTimeout) {
               clearTimeout(this.silenceTimeout)
             }
@@ -586,7 +629,18 @@ class BotiumConnectorVoip {
           if (parsedData && parsedData.data && parsedData.data.type === 'stt' && parsedData.data.final) {
             const confidenceThreshold = ((this._getConfidenceScoreLogicHook(this.convoStep) && this._getConfidenceScoreLogicHook(this.convoStep).args[0]) || this.caps[Capabilities.VOIP_STT_CONFIDENCE_THRESHOLD])
             const successfulConfidenceScore = this._getConfidenceScore(parsedData) >= confidenceThreshold
+            const msgText = parsedData.data.message || ''
+            const msgLen = typeof msgText === 'string' ? msgText.length : 0
+            const msgPreview = typeof msgText === 'string' ? msgText.trim().substring(0, 80) : ''
             debug(`Message: ${parsedData.data.message} / Confidence Score: ${this._getConfidenceScore(parsedData)} (Threshold: ${confidenceThreshold})`)
+            _info('stt_final', {
+              sessionId: this.sessionId,
+              message: msgPreview,
+              messageLength: msgLen,
+              confidence: this._getConfidenceScore(parsedData),
+              threshold: confidenceThreshold,
+              accepted: successfulConfidenceScore
+            })
             // ORIGINAL: emit final message immediately, unless join hooks are active.
             if (
               (this.caps[Capabilities.VOIP_STT_MESSAGE_HANDLING] === 'ORIGINAL' && (_.isNil(this._getJoinLogicHook(this.convoStep))))
@@ -675,6 +729,19 @@ class BotiumConnectorVoip {
 
   async UserSays (msg) {
     debug('UserSays called')
+    const hasText = !!(msg && msg.messageText)
+    const hasVoiceMedia = !!(msg && msg.media && msg.media.length > 0 && msg.media[0].buffer)
+    const hasDtmf = !!(msg && msg.buttons && msg.buttons.length > 0)
+    const dtmfMatch = msg && msg.messageText && msg.messageText.match(/<DTMF>([^<]+)<\/DTMF>/i)
+    const inputType = hasDtmf || dtmfMatch ? 'dtmf' : (hasText && hasVoiceMedia ? 'mixed' : hasText ? 'text' : hasVoiceMedia ? 'media' : 'unknown')
+    const msgPreview = hasText && msg.messageText ? String(msg.messageText).trim().substring(0, 80) : ''
+    _info('user_says', {
+      sessionId: this.sessionId,
+      inputType,
+      message: msgPreview || undefined,
+      messageLength: hasText && msg.messageText ? msg.messageText.length : undefined,
+      mediaSize: hasVoiceMedia && msg.media[0] && Buffer.isBuffer(msg.media[0].buffer) ? msg.media[0].buffer.length : undefined
+    })
     // Avoid logging large buffers/base64 (can break job logs and overwhelm stdout)
     try {
       const safeLog = {
@@ -700,10 +767,21 @@ class BotiumConnectorVoip {
     return new Promise((resolve, reject) => {
       setTimeout(async () => {
         let duration = 0
+        const preferVoiceCapRaw = this.caps[Capabilities.VOIP_USER_INPUT_PREFER_VOICE]
+        const preferVoice = !!preferVoiceCapRaw
+        const skipTtsForMixedInput = preferVoice && hasText && hasVoiceMedia
+        debug(`UserSays routing: hasText=${hasText} hasVoiceMedia=${hasVoiceMedia} preferVoice=${preferVoice} preferVoiceRaw=${JSON.stringify(preferVoiceCapRaw)} skipTtsForMixedInput=${skipTtsForMixedInput}`)
+
         if (msg && msg.buttons && msg.buttons.length > 0) {
+          const digits = sanitizeDtmfDigits(msg.buttons[0].payload)
+          if (!digits) {
+            debug('sendDtmf skipped: no valid DTMF digits after sanitizing button payload')
+            return resolve()
+          }
+          debug(`Sending DTMF digits: ${digits}`)
           const request = JSON.stringify({
             METHOD: 'sendDtmf',
-            digits: msg.buttons[0].payload,
+            digits,
             sessionId: this.sessionId
           })
           this.ws.send(request)
@@ -711,8 +789,17 @@ class BotiumConnectorVoip {
           // Check for DTMF tag in messageText: <DTMF>1234</DTMF>
           const dtmfMatch = msg.messageText.match(/<DTMF>([^<]+)<\/DTMF>/i)
           if (dtmfMatch && dtmfMatch[1]) {
-            const digits = dtmfMatch[1]
-            debug(`Sending DTMF from messageText: ${digits}`)
+            const rawDigits = dtmfMatch[1]
+            const digits = sanitizeDtmfDigits(rawDigits)
+            if (!digits) {
+              debug(`sendDtmf skipped: no valid DTMF digits after sanitizing <DTMF> content (raw length=${String(rawDigits).length})`)
+              return resolve()
+            }
+            if (digits !== String(rawDigits).replace(/\s/g, '')) {
+              debug(`Sending DTMF from messageText (sanitized): "${rawDigits}" -> "${digits}"`)
+            } else {
+              debug(`Sending DTMF from messageText: ${digits}`)
+            }
             const request = JSON.stringify({
               METHOD: 'sendDtmf',
               digits,
@@ -721,56 +808,62 @@ class BotiumConnectorVoip {
             this.ws.send(request)
             return resolve()
           }
-          if (!this.axiosTtsParams) {
-            if (!(msg.media && msg.media.length > 0 && msg.media[0].buffer)) {
-              return reject(new Error('TTS not configured, only audio input supported'))
-            }
-          } else {
-            const ttsRequest = this._buildTtsRequest(msg.messageText)
-            if (!ttsRequest) return reject(new Error('TTS not configured, only audio input supported'))
-            msg.sourceData = ttsRequest
-
-            let ttsResult = null
-            try {
-              ttsResult = await this._getTtsAudio(ttsRequest, msg.messageText)
-            } catch (err) {
-              return reject(new Error(`TTS "${msg.messageText}" failed - ${this._getAxiosErrOutput(err)}`))
-            }
-            if (msg && msg.messageText && msg.messageText.length > 0) {
-              const apiKey = this._extractApiKey(this._getBody(Capabilities.VOIP_TTS_BODY))
-              this.eventEmitter.emit('CONSUMPTION_METADATA', this.container, {
-                type: _.isNil(apiKey) ? 'INBUILT' : 'THIRD_PARTY',
-                metricName: 'consumption.e2e.voip.tts.characters',
-                transactions: msg.messageText.length,
-                apiKey
-              })
-            }
-            if (ttsResult && Buffer.isBuffer(ttsResult.buffer)) {
-              duration = parseFloat(ttsResult.duration) || 0
-              const b64Buffer = ttsResult.buffer.toString('base64')
-              const request = JSON.stringify({
-                METHOD: 'sendAudio',
-                PESQ: false,
-                sessionId: this.sessionId,
-                b64_buffer: b64Buffer
-              })
-              if (this._lastBotSaysQueuedAt) {
-                const latencyMs = Date.now() - this._lastBotSaysQueuedAt
-                const botText = this._lastBotSaysText ? this._lastBotSaysText.substring(0, 120) : '<unknown>'
-                debug(`Latency (bot says -> sendAudio/TTS): ${latencyMs} ms (last bot: ${botText})`)
+          if (!skipTtsForMixedInput) {
+            if (!this.axiosTtsParams) {
+              if (!(msg.media && msg.media.length > 0 && msg.media[0].buffer)) {
+                return reject(new Error('TTS not configured, only audio input supported'))
               }
-              msg.attachments.push({
-                name: 'tts.wav',
-                mimeType: 'audio/wav',
-                base64: b64Buffer
-              })
-              this.ws.send(request)
             } else {
-              return reject(new Error('TTS failed, response is empty'))
+              debug('UserSays routing: executing TTS branch')
+              const ttsRequest = this._buildTtsRequest(msg.messageText)
+              if (!ttsRequest) return reject(new Error('TTS not configured, only audio input supported'))
+              msg.sourceData = ttsRequest
+
+              let ttsResult = null
+              try {
+                ttsResult = await this._getTtsAudio(ttsRequest, msg.messageText)
+              } catch (err) {
+                return reject(new Error(`TTS "${msg.messageText}" failed - ${this._getAxiosErrOutput(err)}`))
+              }
+              if (msg && msg.messageText && msg.messageText.length > 0) {
+                const apiKey = this._extractApiKey(this._getBody(Capabilities.VOIP_TTS_BODY))
+                this.eventEmitter.emit('CONSUMPTION_METADATA', this.container, {
+                  type: _.isNil(apiKey) ? 'INBUILT' : 'THIRD_PARTY',
+                  metricName: 'consumption.e2e.voip.tts.characters',
+                  transactions: msg.messageText.length,
+                  apiKey
+                })
+              }
+              if (ttsResult && Buffer.isBuffer(ttsResult.buffer)) {
+                duration = parseFloat(ttsResult.duration) || 0
+                const b64Buffer = ttsResult.buffer.toString('base64')
+                const request = JSON.stringify({
+                  METHOD: 'sendAudio',
+                  PESQ: false,
+                  sessionId: this.sessionId,
+                  b64_buffer: b64Buffer
+                })
+                if (this._lastBotSaysQueuedAt) {
+                  const latencyMs = Date.now() - this._lastBotSaysQueuedAt
+                  const botText = this._lastBotSaysText ? this._lastBotSaysText.substring(0, 120) : '<unknown>'
+                  debug(`Latency (bot says -> sendAudio/TTS): ${latencyMs} ms (last bot: ${botText})`)
+                }
+                msg.attachments.push({
+                  name: 'tts.wav',
+                  mimeType: 'audio/wav',
+                  base64: b64Buffer
+                })
+                this.ws.send(request)
+              } else {
+                return reject(new Error('TTS failed, response is empty'))
+              }
             }
+          } else {
+            debug('UserSays routing: skipping TTS for mixed input because VOIP_USER_INPUT_PREFER_VOICE is enabled')
           }
         }
         if (msg && msg.media && msg.media.length > 0 && msg.media[0].buffer) {
+          debug('UserSays routing: executing MEDIA branch')
           const request = JSON.stringify({
             METHOD: 'sendAudio',
             sessionId: this.sessionId,