Network Connectivity Requirements

For the Telnyx WebRTC JS SDK to function properly, the client must be able to reach Telnyx’s signaling and media infrastructure.

Overview

The SDK requires connectivity to three types of endpoints:

Signaling

The SDK uses a persistent WebSocket connection for call signaling (invite, answer, hangup, etc.).

Property	Value
Host	`rtc.telnyx.com`
Port	443
Protocol	WSS (WebSocket Secure / TLS)
Direction	Outbound

Requirements:

Outbound WebSocket connections must be allowed on port 443
No HTTP long-polling fallback — WebSocket is required
Connection must remain open for the duration of the session

Custom endpoint: You can override the signaling server using IClientOptions env property, but this is not recommended for production.

STUN

STUN servers help the client discover its public IP address for ICE negotiation.

Property	Value
Primary	`stun.telnyx.com:3478`
Fallback	`stun.l.google.com:19302`
Protocol	UDP
Direction	Outbound

The SDK automatically uses these STUN servers. No configuration required.

TURN

TURN servers relay media when direct peer-to-peer connectivity is not possible (e.g., symmetric NAT, restrictive firewalls).

Property	Value
Host (UDP/TCP)	`turn.telnyx.com`
Host (TURNS)	`turn2.telnyx.com`
Port (UDP)	3478
Port (TCP)	3478
Port (TURNS)	443
Protocol	UDP (preferred) / TCP (fallback) / TLS over 443 (last resort)
Authentication	Automatic (long-term credentials)
Direction	Outbound

The SDK automatically provisions TURN credentials. No manual configuration required. UDP vs TCP vs TURNS/443:

UDP (preferred) — Lower latency, better for real-time audio
TCP (fallback) — Higher latency, used when UDP is blocked
TURNS over 443 (last resort) — TURN over TLS on port 443, used when both UDP and TCP/3478 are blocked by restrictive firewalls or proxies

TURN credentials are automatically provisioned by the SDK. You do not need to configure TURN usernames or passwords.

Starting with SDK v2.27.4, the default ICE server list includes a TURNS (TURN over TLS) entry on port 443 (turns:turn2.telnyx.com:443) in addition to the existing TURN UDP/3478 and TCP/3478 entries. This provides a last-resort relay fallback for networks that block both UDP/3478 and TCP/3478 but allow outbound TCP/443.

Firewall Configuration

Minimum required rules

Direction	Destination	Port	Protocol	Purpose
Outbound	`rtc.telnyx.com`	443	WSS	Signaling
Outbound	`stun.telnyx.com`	3478	UDP	STUN
Outbound	`turn.telnyx.com`	3478	UDP	TURN (media relay, preferred)
Outbound	`turn.telnyx.com`	3478	TCP	TURN (fallback)
Outbound	`turn2.telnyx.com`	443	TLS	TURN over TLS (restrictive-network fallback)

Optional but recommended

Direction	Destination	Port	Protocol	Purpose
Outbound	`stun.l.google.com`	19302	UDP	STUN fallback

Media ports

RTP media uses dynamic ports allocated by the browser. These are ephemeral and cannot be whitelisted by port number. Instead:

Ensure TURN is accessible — TURN handles media relay when direct connectivity fails
Allow UDP outbound to Telnyx media servers (the remote_media_ip seen in SDP)
Don’t restrict outbound UDP to specific ports — this will break WebRTC

Restrictive Network Scenarios

STUN fails (error 701)

Symptom: Client cannot discover its public IP. No srflx or prflx ICE candidates. Fix:

Check firewall allows UDP to stun.telnyx.com:3478
If STUN is blocked, TURN may still work — the SDK falls back automatically
If both STUN and TURN are blocked, calls cannot connect

TURN fails

Symptom: Client is on a restrictive network (symmetric NAT), can’t get relay candidates. Fix:

Check firewall allows UDP to turn.telnyx.com:3478
If UDP is blocked, check firewall allows TCP to turn.telnyx.com:3478
If both UDP/3478 and TCP/3478 are blocked, TURNS over TLS on port 443 to turn2.telnyx.com will work — this is included in the default ICE server list since SDK v2.27.4
If all TURN paths are blocked, use forceRelayCandidate: true to skip direct connectivity attempts:

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

Custom ICE servers with `TELNYX_ICE_SERVERS`

Starting with SDK v2.27.4, the SDK exports a public TELNYX_ICE_SERVERS catalog of ready-to-use ICE server entries. Import it and compose any combination into the iceServers option to override the defaults:

import { TelnyxRTC, TELNYX_ICE_SERVERS } from '@telnyx/webrtc';

const client = new TelnyxRTC({
  login_token: jwt,
  iceServers: [
    TELNYX_ICE_SERVERS.TELNYX_STUN,
    TELNYX_ICE_SERVERS.TELNYX_TURN_UDP_3478,
    TELNYX_ICE_SERVERS.TELNYX_TURNS_TCP_443,
  ],
});

Available entries:

Constant	URL	Protocol
`TELNYX_ICE_SERVERS.GOOGLE_STUN`	`stun:stun.l.google.com:19302`	UDP
`TELNYX_ICE_SERVERS.TELNYX_STUN`	`stun:stun.telnyx.com:3478`	UDP
`TELNYX_ICE_SERVERS.TELNYX_TURN_UDP_3478`	`turn:turn.telnyx.com:3478?transport=udp`	UDP
`TELNYX_ICE_SERVERS.TELNYX_TURN_TCP_3478`	`turn:turn.telnyx.com:3478?transport=tcp`	TCP
`TELNYX_ICE_SERVERS.TELNYX_TURNS_TCP_443`	`turns:turn2.telnyx.com:443`	TLS

When you omit iceServers, the SDK uses its built-in defaults (DEFAULT_PROD_ICE_SERVERS) which include STUN + TURN UDP/3478 + TURN TCP/3478 + TURNS/443. Providing an explicit iceServers array replaces the defaults entirely.

Corporate VPN

Symptom: Calls fail or have poor quality through VPN. Fix:

Whitelist rtc.telnyx.com, stun.telnyx.com, turn.telnyx.com, and turn2.telnyx.com in VPN split-tunneling config
Ensure VPN doesn’t block UDP traffic to TURN servers or TLS to turn2.telnyx.com:443
Consider split-tunneling so WebRTC traffic bypasses the VPN

Docker / Container environments

Symptom: STUN errors, no ICE candidates, one-way audio. Fix:

Docker’s default bridge network (172.x or 10.x) can interfere with ICE candidate gathering
Use --network host mode for the container
Or configure the Docker network to use the host’s network stack

Testing Connectivity

Quick test

Open your browser’s DevTools console and run:

// Test WebSocket signaling
const ws = new WebSocket('wss://rtc.telnyx.com:443');
ws.onopen = () => console.log(' WebSocket OK');
ws.onerror = () => console.error(' WebSocket FAILED');

// Test STUN + TURN (including TURNS/443)
const pc = new RTCPeerConnection({
  iceServers: [
    { urls: 'stun:stun.telnyx.com:3478' },
    {
      urls: 'turn:turn.telnyx.com:3478?transport=udp',
      username: 'testuser',
      credential: 'testpassword',
    },
    {
      urls: 'turns:turn2.telnyx.com:443',
      username: 'testuser',
      credential: 'testpassword',
    },
  ],
});
pc.createDataChannel('test');
pc.createOffer().then(offer => pc.setLocalDescription(offer));
pc.onicecandidate = (e) => {
 if (e.candidate) {
 const type = e.candidate.type;
 console.log(`ICE candidate type: ${type}`);
 if (type === 'srflx') console.log(' STUN works');
 if (type === 'relay') console.log(' TURN works');
 }
};

Debug tools

SDK debug mode: Set debug: true and debugOutput: 'socket' in IClientOptions
Debug visualizer: Upload debug data to https://webrtc-debug.telnyx.com/
Call reports: Enable enableCallReports: true for programmatic access to ICE stats

See Debug Data & Call Quality Analysis for interpreting debug output.

Bandwidth Requirements

Codec	Bitrate	Notes
Opus	6-510 kbps	Default, adaptive. Typical: ~30 kbps
PCMU (G.711)	64 kbps	Fallback codec
PCMA (G.711)	64 kbps	Fallback codec

Recommended minimum bandwidth per call:

Audio only: 100 kbps (including overhead)
With video: 500-2000 kbps depending on resolution

RTT requirements:

Quality	RTT
Excellent	< 100ms
Good	< 150ms
Acceptable	< 300ms
Poor	> 300ms

Getting Started

Authentication

Push Notifications

Tutorials

Use Cases

Troubleshooting

SDKs

API Reference

For AI Agents

Network Connectivity Requirements

Network Connectivity Requirements

Overview

Signaling

STUN

TURN

Firewall Configuration

Minimum required rules

Optional but recommended

Media ports

Restrictive Network Scenarios

STUN fails (error 701)

TURN fails

Custom ICE servers with `TELNYX_ICE_SERVERS`

Corporate VPN

Docker / Container environments

Testing Connectivity

Quick test

Debug tools

Bandwidth Requirements

See Also

​Network Connectivity Requirements

​Overview

​Signaling

​STUN

​TURN

​Firewall Configuration

​Minimum required rules

​Optional but recommended

​Media ports

​Restrictive Network Scenarios

​STUN fails (error 701)

​TURN fails

​Custom ICE servers with TELNYX_ICE_SERVERS

​Corporate VPN

​Docker / Container environments

​Testing Connectivity

​Quick test

​Debug tools

​Bandwidth Requirements

​See Also

Network Connectivity Requirements

Overview

Signaling

STUN

TURN

Firewall Configuration

Minimum required rules

Optional but recommended

Media ports

Restrictive Network Scenarios

STUN fails (error 701)

TURN fails

Custom ICE servers with `TELNYX_ICE_SERVERS`

Corporate VPN

Docker / Container environments

Testing Connectivity

Quick test

Debug tools

Bandwidth Requirements

See Also