Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt

Use this file to discover all available pages before exploring further.

​
INotification

The INotification object is emitted via the telnyx.notification event. It contains information about call state changes, media events, and SDK notifications.

​
Properties

PropertyTypeDescription
typestringNotification type (see below)
callCallThe call object this notification relates to (if applicable)
timestampnumberUnix timestamp of the notification

​
Notification Types

TypeDescriptionWhen It Fires
callUpdateCall state changedCall rings, connects, hangs up, etc.
userMediaErrorMedia access failedBrowser denied microphone/camera permissions
peerConnectionFailedErrorICE/DTLS connection failedMedia could not be established
signalingStateClosedPeerConnection signaling closedSIP signaling terminated unexpectedly
vertoClientReadyClient is readyInitial connection established

​
Type: callUpdate

The most common notification type. Fired whenever a call’s state changes. 
client.on('telnyx.notification', (notification) => {
  if (notification.type === 'callUpdate') {
    const call = notification.call;

    switch (call.state) {
      case 'new':
        // Call object created (before dialing)
        break;
      case 'requesting':
        // Outbound call: INVITE sent to server
        break;
      case 'ringing':
        // Inbound call: received INVITE
        // Outbound call: remote party is ringing
        break;
      case 'answering':
        // Inbound call: answering in progress
        break;
      case 'active':
        // Call connected — media flowing
        break;
      case 'held':
        // Call on hold
        break;
      case 'hangup':
        // Call ended
        break;
      case 'destroy':
        // Call object cleaned up
        break;
      case 'recovering':
        // Call being recovered after reconnection
        break;
    }
  }
});

​
Call State Diagram

​
Type: userMediaError

Fired when the browser denies or fails to access media devices (microphone/camera). 
client.on('telnyx.notification', (notification) => {
  if (notification.type === 'userMediaError') {
    console.error('Media error:', notification.call.state);
    // Common causes:
    // - User denied microphone permission
    // - No microphone available
    // - Another app is using the microphone
    showPermissionErrorUI();
  }
});
Common causes:
  • User clicked “Block” on the permission prompt
  • No microphone/camera detected
  • Another application is using the device
  • System-level permission denied (OS settings)
Recommended response: Show a clear message asking the user to grant microphone access, with a link to browser settings.

​
Type: peerConnectionFailedError

Fired when the WebRTC PeerConnection fails to establish media. This usually means ICE negotiation or DTLS handshake failed. 
client.on('telnyx.notification', (notification) => {
  if (notification.type === 'peerConnectionFailedError') {
    console.error('Peer connection failed');
    // Common causes:
    // - Firewall blocking TURN servers
    // - Symmetric NAT without TURN
    // - DTLS fingerprint mismatch
    showConnectionErrorUI();
  }
});
Common causes:
  • Firewall blocks UDP to TURN servers
  • Symmetric NAT prevents direct connectivity
  • VPN interfering with ICE
  • Docker/container network issues
Recommended response: Suggest the user check their network connection. See Network Requirements.

​
Type: signalingStateClosed

Fired when the PeerConnection’s signaling state becomes closed, indicating the SIP signaling channel has terminated. 
client.on('telnyx.notification', (notification) => {
  if (notification.type === 'signalingStateClosed') {
    console.warn('Signaling state closed for call:', notification.call.id);
    // The call will transition to hangup state shortly
  }
});
This is usually followed by a callUpdate with state hangup.

​
Type: vertoClientReady

Fired when the client has successfully connected and authenticated with the Telnyx signaling server. This is equivalent to the telnyx.ready event but delivered as a notification. 
client.on('telnyx.notification', (notification) => {
  if (notification.type === 'vertoClientReady') {
    console.log('Client ready for calls');
  }
});

​
Listening to Notifications

​
On the Client

client.on('telnyx.notification', (notification) => {
  switch (notification.type) {
    case 'callUpdate':
      handleCallUpdate(notification.call);
      break;
    case 'userMediaError':
      handleMediaError(notification.call);
      break;
    case 'peerConnectionFailedError':
      handleConnectionError(notification.call);
      break;
  }
});

​
On a Call

You can also listen on individual call objects: 
const call = client.newCall({
  destinationNumber: '+12345678900',
  audio: true,
});

call.on('telnyx.notification', (notification) => {
  // Only notifications for this specific call
  if (notification.call.state === 'active') {
    console.log('Call connected!');
  }
});
Listening on the client gives you notifications for ALL calls. Listening on a specific call gives you notifications for that call only. Choose based on your app’s architecture.

​
See Also