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.
Quickstart
Get the Telnyx WebRTC JS SDK running in your app — make your first call in under 5 minutes.
Before You Begin
You’ll need:
Portal Setup
Set up everything you need in the Telnyx Portal — no API calls required.
1. Buy a number
Go to Numbers → Buy Numbers in the Portal. Purchase a number in your desired country and area code.
2. Create a Credential Connection
Go to Call Connections → Create → SIP Credential Connection. This defines how your WebRTC client authenticates with the SIP network. Give it a name and keep the defaults.
3. Create a Telephony Credential
Go to Call Connections → [Your Connection] → Credentials → Create. Each user (or device) needs its own credential. Note the username and password — you’ll use these to generate a JWT.
4. Assign your number to the connection
Go to Numbers → Your Numbers, select your number, and assign it to the Credential Connection you created.
5. Generate a JWT
Still in the Credentials section, click Generate Token for the credential you created. Copy the JWT — this is what you’ll pass to the SDK as login_token.
Install
npm install @telnyx/webrtc
Create a Client
The SDK connects to Telnyx via WebSocket and establishes WebRTC media sessions. Here’s the minimal setup:
import { TelnyxRTC } from '@telnyx/webrtc';
const client = new TelnyxRTC({
login_token: 'YOUR_JWT_TOKEN', // Generate from your backend
});
client.on('telnyx.ready', () => {
console.log(' Connected to Telnyx');
});
client.on('telnyx.error', (error) => {
console.error(' Connection error:', error.code, error.message);
});
client.on('telnyx.notification', (notification) => {
// Handle call updates (incoming calls, state changes)
console.log('Notification:', notification.type);
});
client.connect();
Always wait for telnyx.ready before making calls. The client needs to establish a WebSocket connection and authenticate before it can place calls.
Authentication
The SDK supports three authentication methods:
| Method | Property | Use Case | Security |
|---|
| JWT (recommended) | login_token | Production apps | Token expires in 24h |
| Credential | login + password | Call Control apps, development | Long-lived, no rotation |
| Anonymous | anonymous_login | AI assistant connections | No identity, limited features |
const client = new TelnyxRTC({
login_token: 'eyJhbGciOi...', // From your backend
});
const client = new TelnyxRTC({
login: 'gencred...', // SIP username from Portal
password: 'your-password', // SIP password
});
const client = new TelnyxRTC({
anonymous_login: {
target_type: 'ai_assistant',
target_id: 'YOUR_AI_ASSISTANT_ID',
},
});
For the full authentication guide including JWT generation, token refresh, and security best practices, see Authenticating Your App. Make an Outbound Call
client.on('telnyx.ready', () => {
const call = client.newCall({
destinationNumber: '+12345678900', // E.164 format
audio: true,
});
// Listen for call state changes
call.on('telnyx.notification', (notification) => {
switch (notification.call.state) {
case 'ringing':
console.log(' Ringing...');
break;
case 'active':
console.log(' Call connected!');
break;
case 'hangup':
console.log(' Call ended');
break;
}
});
});
Receive an Inbound Call
client.on('telnyx.notification', (notification) => {
if (notification.type === 'callUpdate') {
const call = notification.call;
if (call.state === 'ringing') {
// Incoming call — answer it
console.log(' Incoming call from', call.remotePartyNumber);
call.answer();
}
}
});
For more control, show an “Accept/Reject” UI instead of auto-answering.
Play Audio
The SDK handles audio elements automatically, but you can provide your own:
const call = client.newCall({
destinationNumber: '+12345678900',
audio: true,
// Optional: provide audio elements for playback
remoteElement: document.getElementById('remoteAudio'),
localElement: document.getElementById('localAudio'),
});
<!-- The SDK auto-creates audio elements and appends them to the body -->
<!-- Or provide specific elements: -->
<audio id="remoteAudio" autoplay></audio>
Handle Errors
import { TELNYX_ERROR_CODES } from '@telnyx/webrtc';
client.on('telnyx.error', (error) => {
switch (error.code) {
case TELNYX_ERROR_CODES.WEBSOCKET_CONNECTION_FAILED:
console.error('WebSocket failed — check network');
break;
case TELNYX_ERROR_CODES.ICE_CONNECTION_FAILED:
console.error('ICE failed — check firewall/TURN config');
break;
default:
console.error('Error:', error.code, error.message);
}
});
Disconnect
Always disconnect when the user leaves or the app unloads:
// User clicks "logout"
document.getElementById('logout').addEventListener('click', () => {
client.disconnect();
});
// Page unload (tab close, navigation)
window.addEventListener('beforeunload', () => {
client.disconnect();
});
Next Steps
Quick Reference
import { TelnyxRTC } from '@telnyx/webrtc';
// 1. Create client
const client = new TelnyxRTC({ login_token: 'YOUR_JWT' });
// 2. Listen for events
client.on('telnyx.ready', () => { /* Connected */ });
client.on('telnyx.error', (err) => { /* Handle errors */ });
client.on('telnyx.notification', (notif) => {
if (notif.type === 'callUpdate' && notif.call.state === 'ringing') {
notif.call.answer();
}
});
// 3. Connect
client.connect();
// 4. Make a call
const call = client.newCall({ destinationNumber: '+12345678900' });
// 5. Call control
call.hangup(); // End call (async in 2.26+)
call.muteAudio(); // Mute microphone
call.unmuteAudio(); // Unmute
// 6. Disconnect
client.disconnect();
