> ## 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.

# Network Connectivity Requirements

> Required endpoints, ports, and firewall configuration for the Telnyx WebRTC JS SDK.

# 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:

```mermaid theme={null}
graph LR
 A[Client Browser] -->|WebSocket WSS| B[rtc.telnyx.com:443]
 A -->|STUN UDP| C[stun.telnyx.com:3478]
 A -->|TURN UDP/TCP| D[turn.telnyx.com:3478]
 A -->|TURNS TLS/443| F[turn2.telnyx.com:443]
 B --> E[Telnyx SIP Platform]
 D --> E
 F --> E
```

***

## 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](/development/webrtc/js-sdk/interfaces/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

<Callout type="info">
  TURN credentials are automatically provisioned by the SDK. You do not need to configure TURN usernames or passwords.
</Callout>

<Callout type="info">
  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.
</Callout>

***

## 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:**

1. Check firewall allows UDP to `stun.telnyx.com:3478`
2. If STUN is blocked, TURN may still work — the SDK falls back automatically
3. 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:**

1. Check firewall allows UDP to `turn.telnyx.com:3478`
2. If UDP is blocked, check firewall allows TCP to `turn.telnyx.com:3478`
3. 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
4. If all TURN paths are blocked, use `forceRelayCandidate: true` to skip direct connectivity attempts:

```javascript theme={null}
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:

```javascript theme={null}
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      |

<Callout type="info">
  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.
</Callout>

### Corporate VPN

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

**Fix:**

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

### Docker / Container environments

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

**Fix:**

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

***

## Testing Connectivity

### Quick test

Open your browser's DevTools console and run:

```javascript theme={null}
// 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](/development/webrtc/js-sdk/interfaces/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](/development/webrtc/js-sdk/how-to/debug-call-issues) 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  |

***

## See Also

* [IClientOptions](/development/webrtc/js-sdk/interfaces/iclientoptions) — ICE and network configuration
* [Debug Data & Call Quality Analysis](/development/webrtc/js-sdk/how-to/debug-call-issues) — Interpreting ICE and quality data
* [Best Practices](/development/webrtc/js-sdk/how-to/production-best-practices) — Production deployment guide
* [Error Handling](/development/webrtc/js-sdk/how-to/error-handling) — ICE and WebSocket error codes