Skip to main content

​
ICallOptions

Options passed to client.newCall(options) to configure call behavior.

​
Quick Reference

const call = client.newCall({
  destinationNumber: '+12345678900',  // Required
  audio: true,                        // Required
  callerName: 'John Doe',             // Optional caller ID
  trickleIce: true,                   // Faster call setup
});

​
Required Properties

PropertyTypeDescription
destinationNumberstringPhone number or SIP URI to call. Use E.164 format for PSTN (e.g., +12345678900) or sip:user@domain for SIP.
audiobooleanEnable audio for this call. Always true for voice calls.

​
Call Identity

Customize how the call appears to the remote party.
PropertyTypeDefaultDescription
callerNamestring—Display name shown to the remote party (Caller ID name)
callerNumberstring—Phone number shown to the remote party (Caller ID number)
customHeadersSipHeader[]—Custom SIP headers to include in the INVITE. Each header has name and value properties.
Example — Custom caller ID: 
const call = client.newCall({
  destinationNumber: '+12345678900',
  audio: true,
  callerName: 'Acme Corp',
  callerNumber: '+18005551234',
  customHeaders: [
    { name: 'X-Customer-ID', value: '12345' },
    { name: 'X-Agent-Name', value: 'john.doe' },
  ],
});

​
ICE & Network

Control how the call establishes media connectivity.
PropertyTypeDefaultDescription
trickleIcebooleantrueSend ICE candidates incrementally instead of waiting for all to gather. Keep enabled for faster call setup.
prefetchIceCandidatesbooleantruePre-gather ICE candidates before the call is placed. Reduces call setup time.
forceRelayCandidatebooleanfalseForce all media through TURN relay servers. Hides the client’s public IP. Adds latency.
iceServersRTCIceServer[]AutoCustom ICE servers. Overrides the SDK’s default STUN/TURN configuration.
Example — Force TURN for privacy: 
const call = client.newCall({
  destinationNumber: '+12345678900',
  audio: true,
  forceRelayCandidate: true,  // All media through TURN
});
Example — Custom ICE servers: 
const call = client.newCall({
  destinationNumber: '+12345678900',
  audio: true,
  iceServers: [
    { urls: 'stun:stun.custom.com:3478' },
    {
      urls: 'turn:turn.custom.com:443',
      username: 'myuser',
      credential: 'mypass',
    },
  ],
});
The SDK automatically provisions STUN/TURN servers. Only override iceServers if you have custom infrastructure. See Network Requirements.

​
Media Configuration

Control audio devices and streams.
PropertyTypeDefaultDescription
localElementHTMLAudioElementAuto-createdHTML element for playing local audio (hearing yourself)
remoteElementHTMLAudioElementAuto-createdHTML element for playing remote audio (hearing the other party)
localStreamMediaStream—Custom local media stream. Use to provide a pre-obtained stream.
remoteStreamMediaStream—Custom remote media stream.
preferred_codecsRTCRtpCodecCapability[]—Preferred audio codecs. Defaults to Opus.
sdpASBandwidthKbpsnumber—Bandwidth limit in kbps (set in SDP AS attribute)
Example — Custom audio elements: 
const remoteAudio = document.getElementById('remoteAudio');
const localAudio = document.getElementById('localAudio');

const call = client.newCall({
  destinationNumber: '+12345678900',
  audio: true,
  remoteElement: remoteAudio,
  localElement: localAudio,
});
Example — Pre-obtained media stream: 
// Get microphone access before placing the call
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });

const call = client.newCall({
  destinationNumber: '+12345678900',
  audio: true,
  localStream: stream,
});

​
Advanced

PropertyTypeDefaultDescription
sessionIdstring—Custom session ID for call correlation
retryBucketIdstring—ID for call retry bucket
timeoutSecsnumber—Call setup timeout in seconds
telnyxSessionIdstring—Telnyx session ID (for re-attach scenarios)
telnyxCallIdstring—Telnyx call ID (for re-attach scenarios)
isRecoveredboolean—Whether this call was recovered after reconnection

​
Common Patterns

​
Basic voice call

const call = client.newCall({
  destinationNumber: '+12345678900',
  audio: true,
});

​
Call with SIP URI

const call = client.newCall({
  destinationNumber: 'sip:agent@customer.sip.telnyx.com',
  audio: true,
});

​
Call with custom headers (for Call Control correlation)

const call = client.newCall({
  destinationNumber: '+12345678900',
  audio: true,
  customHeaders: [
    { name: 'X-Call-Session', value: sessionUuid },
  ],
});

​
Privacy-focused call (force TURN)

const call = client.newCall({
  destinationNumber: '+12345678900',
  audio: true,
  forceRelayCandidate: true,
});

​
See Also