Adds Call Status events for granular call insights

CHANGELOG.md

@@ -1,5 +1,14 @@
 :warning: **Important**: If you are upgrading to version 2.3.0 or later and have firewall rules or network configuration that blocks any unknown traffic by default, you need to update your configuration to allow connections to the new DNS names and IP addresses. Please refer to this [changelog](#230-january-23-2023) for more details.
 
+*Next Release*
+====================
+
+New Features
+------------
+
+- Added `Call` [status](https://github.com/twilio/twilio-voice.js/commit/887ce625730b1cd96d08f453177e2a8db70014a9) events with [Call.CallStatus](https://github.com/twilio/twilio-voice.js/commit/9164ae8bd4e51ca258ed2573d69a1a3051e8a803) providing granular insight into the current call. [@cybex-dev](https://github.com/cybex-dev)
+
+
 2.13.0 (May 6, 2025)
 ====================
 

lib/twilio/call.ts

@@ -581,6 +581,7 @@ class Call extends EventEmitter {
         this._log.debug('#disconnect');
         this.emit('disconnect', this);
       }
+      this.emit('status', Call.CallStatus.Closed);
     };
 
     this._pstream = config.pstream;
@@ -644,6 +645,7 @@ class Call extends EventEmitter {
     };
 
     this._status = Call.State.Connecting;
+    this.emit('status', Call.CallStatus.Connecting);
 
     const connect = () => {
       if (this._status !== Call.State.Connecting) {
@@ -780,6 +782,7 @@ class Call extends EventEmitter {
     if (this._onIgnore) {
       this._onIgnore();
     }
+    this.emit('status', Call.CallStatus.Closed);
   }
 
   /**
@@ -855,6 +858,8 @@ class Call extends EventEmitter {
     this._status = Call.State.Closed;
     this._log.debug('#reject');
     this.emit('reject');
+    this.emit('status', Call.CallStatus.Rejected);
+    this.emit('status', Call.CallStatus.Closed);
   }
 
   /**
@@ -1158,6 +1163,7 @@ class Call extends EventEmitter {
           this._log.debug('#accept');
           this.emit('accept', this);
         }
+        this.emit('status', Call.CallStatus.Connected);
       }
     }
   }
@@ -1197,6 +1203,7 @@ class Call extends EventEmitter {
     this._setCallSid(payload);
     this._isAnswered = true;
     this._maybeTransitionToOpen();
+    this.emit('status', Call.CallStatus.Answer);
   }
 
   /**
@@ -1216,6 +1223,7 @@ class Call extends EventEmitter {
       this._log.debug('#cancel');
       this.emit('cancel');
       this._pstream.removeListener('cancel', this._onCancel);
+      this.emit('status', Call.CallStatus.Closed);
     }
   }
 
@@ -1232,6 +1240,7 @@ class Call extends EventEmitter {
         this._signalingReconnectToken,
       );
     }
+    this.emit('status', Call.CallStatus.Connected);
   }
 
   /**
@@ -1349,6 +1358,7 @@ class Call extends EventEmitter {
 
       this._log.debug('#reconnecting');
       this.emit('reconnecting', mediaReconnectionError);
+      this.emit('status', Call.CallStatus.Reconnecting);
     }
   }
 
@@ -1369,6 +1379,7 @@ class Call extends EventEmitter {
       this._log.debug('#reconnected');
       this.emit('reconnected');
       this._status = Call.State.Open;
+      this.emit('status', Call.CallStatus.Reconnected);
     }
   }
 
@@ -1437,6 +1448,7 @@ class Call extends EventEmitter {
     this._publisher.info('connection', 'outgoing-ringing', { hasEarlyMedia }, this);
     this._log.debug('#ringing');
     this.emit('ringing', hasEarlyMedia);
+    this.emit('status', Call.CallStatus.Ringing);
   }
 
   /**
@@ -1517,6 +1529,7 @@ class Call extends EventEmitter {
       this._log.debug('#reconnected');
       this.emit('reconnected');
       this._status = Call.State.Open;
+      this.emit('status', Call.CallStatus.Reconnected);
     }
   }
 
@@ -1533,9 +1546,11 @@ class Call extends EventEmitter {
       this._signalingStatus = Call.State.Reconnecting;
       this._log.debug('#reconnecting');
       this.emit('reconnecting', new SignalingErrors.ConnectionDisconnected());
+      this.emit('status', Call.CallStatus.Reconnecting);
     } else {
       this._status = Call.State.Closed;
       this._signalingStatus = Call.State.Closed;
+      this.emit('status', Call.CallStatus.Closed);
     }
   }
 
@@ -1774,6 +1789,22 @@ namespace Call {
     Ringing = 'ringing',
   }
 
+  /**
+   * Possible statuses of the {@link Call}.
+   * These statuses are used to indicate the current state of the call, to provide integration with 3rd party plugins or
+   * to provide a way to track the call state in a UI.
+   */
+  export enum CallStatus {
+    Closed = 'closed',
+    Connecting = 'connecting',
+    Connected = 'connected',
+    Reconnecting = 'reconnecting',
+    Reconnected = 'reconnected',
+    Ringing = 'ringing',
+    Rejected = 'rejected',
+    Answer = 'answer',
+  }
+
   /**
    * Different issues that may have been experienced during a call, that can be
    * reported to Twilio Insights via {@link Call}.postFeedback().

lib/twilio/device.ts

@@ -1600,6 +1600,7 @@ class Device extends EventEmitter {
         parameters: call.parameters,
       }));
       this.emit(Device.EventName.Incoming, call);
+      call.emit('status', Call.State.Ringing);
     });
   }