Skip to main content

Build your own web phone

What you'll build​

A web page that is a phone. It signs in as one of your Telebroad phone lines, rings when someone calls that line, and can dial out — all in the browser, with no app to install. It works the same way as Teleconsole, Telebroad's own web phone: the page talks to our phone system over a secure WebSocket using JsSIP, a free JavaScript library for internet calling (SIP).

┌────────────────┐ 1. "give me my line" ┌──────────────┐ 2. GET /me ┌─────────────────┐
│ Your web page │ ──────────────────────► │ Your server │ ────────────────────► │ Telebroad API │
│ (JsSIP) │ ◄────────────────────── │ (holds key) │ ◄──────────────────── │ │
└───────┬────────┘ one line's login └──────────────┘ your lines └─────────────────┘
│
│ 3. register + calls, over wss://websocket.telebroad.com:8443
▼
┌─────────────────────────┐
│ Telebroad phone system │ ← rings your line, connects your calls
└─────────────────────────┘

Three pieces: your server gets the line's login from the API, your page uses it to register, and from then on the page is a phone on your account.

Before you start​

You need:

  1. A credential with the "Read your profile and phone line logins" scope (profile:read). It is off by default — tick it on purpose.
    • An API key: the lines you get are the ones owned by the key's run-as user.
    • Or an OAuth app: the lines you get are the ones owned by the person who approved the app. Use this when each of your staff signs in and should get their own phone.
  2. A user who owns at least one phone line. A credential that is not tied to a user gets 403, and a user with no lines gets an empty list.
  3. A page served over HTTPS (or http://localhost while testing). Browsers only allow the microphone on secure pages.
Good to know
  • Audio only. Video is off on calls made this way.

  • Some things we have not confirmed yet, so test them early:

    • whether the WebSocket server accepts a browser page hosted on your own website (it may only accept Telebroad's own sites);
    • whether a line with an IP lock (the line only accepts phones from set internet addresses) accepts a browser at an address it does not know.

    If either one blocks you, see Troubleshooting and contact Telebroad support.

The connection details are the same for every account, so they are written here rather than returned by the API:

WebSocket addresswss://websocket.telebroad.com:8443
SIP domainreg.telebroad.com:5060
JsSIP version3.10.1 — the version Teleconsole uses

Step 1 — Get your line login​

Ask the API for your own profile. The answer is your user record plus a lines list, and each line carries the SIP username and password a phone signs in with. It also has what Teleconsole shows on your profile (account, role, contact details, photo, status, and the numbers you can text and fax from), so your page can show who is signed in.

curl https://api.account.telebroad.com/api/public/v1/me \
-H "Authorization: Bearer $TB_KEY"
{
"data": {
"id": 481920,
"username": "dspencer",
"firstName": "Dana",
"lastName": "Spencer",
"title": "Support Lead",
"email": "dana@acme.example",
"mobile": "13475550188",
"company": "Acme Inc",
"timeZone": "America/New_York",
"extension": "204",
"extensions": ["204"],
"numbers": ["12125550188"],
"voicemails": ["204"],
"account": { "id": 651, "name": "Acme Inc", "callerId": "12125550100" },
"role": { "id": 1, "name": "Account Owner" },
"telephone": "12125550188",
"fax": "",
"address": { "line1": "1 Main St", "line2": "", "line3": "", "city": "Brooklyn", "state": "NY", "postalCode": "11201", "other": "" },
"country": "us",
"language": "en",
"photoUrl": "https://cdn.telebroad.com/photos/481920.png",
"status": { "id": 12207, "name": "In a meeting", "description": "", "emoji": "📅", "expiresAt": "2026-11-10T19:30:00Z" },
"lines": [
{
"sipUsername": "acme-204",
"sipPassword": "s3cr3t-EXAMPLE",
"description": "Dana's desk",
"extension": "204",
"callerId": "default",
"callerIdNumber": "12125550100",
"featureCode": "*204"
}
],
"smsNumbers": [{ "number": "12125550100", "name": "Acme Main", "userIds": [], "bulkEnabled": false }],
"faxNumbers": [{ "number": "12125550101", "name": "Acme Fax" }]
}
}

The phone only needs sipUsername and sipPassword. Use firstName, photoUrl and status if you want to show who is signed in, and callerIdNumber to show which number people will see when you call (callerId is "default" when the line uses the default caller ID).

Pick the line you want the web phone to be. Skip any line whose sipPassword is empty — that line has no stored SIP password, so it cannot sign in.

If the person also has a desk phone on the same line, we have not confirmed that both can be registered at once — it depends on the line's settings, so test it. Never call ua.unregister({all: true}): it signs out every phone on the line, desk phone included.

Full details: GET /me.

Step 2 — Keep the API key on your server​

Never put the API key in the web page. Anyone can read a page's code, and the key opens your whole account, not just one phone. So add a small endpoint to your own server that calls /me and hands the page only one line's username and password — and only to someone who is signed in to your site.

First set up a small Node project (Node 18 or newer):

npm init -y && npm pkg set type=module && npm install express

Then save this as server.js:

// server.js — Node 18+ with Express
import express from 'express';

const app = express();
const TB_KEY = process.env.TB_KEY; // tbk_live_… — lives only on the server

app.get('/phone-login', async (req, res) => {
// This sample has no sign-in, so it only answers this computer (localhost).
if (!['127.0.0.1', '::1', '::ffff:127.0.0.1'].includes(req.ip)) return res.sendStatus(403);
// if (!req.user) return res.sendStatus(401); ← replace the line above with your own sign-in check

const r = await fetch('https://api.account.telebroad.com/api/public/v1/me', {
headers: {Authorization: `Bearer ${TB_KEY}`},
});
if (!r.ok) return res.status(502).json({error: 'could not read the line login'});
const {data} = await r.json();
// Pick which of the run-as user's lines this page should be.
// Here: the first one that has a SIP password.
const line = data.lines.find((l) => l.sipPassword);
if (!line) return res.status(404).json({error: 'this user has no phone line with a SIP password'});
res.set('Cache-Control', 'no-store');
res.json({sipUsername: line.sipUsername, sipPassword: line.sipPassword});
});

app.use(express.static('public')); // serves the phone page
app.listen(3000);

Start it with your API key in the TB_KEY environment variable (create the key under API keys):

# macOS / Linux
TB_KEY=tbk_live_... node server.js

# Windows PowerShell
$env:TB_KEY = "tbk_live_..."; node server.js
This sample has no sign-in

Run it only on your own computer. Before you put it on the internet, replace the localhost check with your real sign-in check. Otherwise anyone can fetch your SIP password and make calls billed to you.

Who gets which line: with an API key, every visitor gets the run-as user's line. That is fine for one person, or for a shared phone like a front-desk kiosk. For one phone per staff member, use OAuth and call /me with that person's access token instead of TB_KEY — each person then gets their own line.

Step 3 — Connect and register​

Load JsSIP, fetch the login from your server, and start the phone. These are the same connection settings Teleconsole uses.

Put this code in a <script type="module"> tag — the import line only works there. If your app has a build step (Vite, webpack, Next.js…), install it instead with npm install jssip@3.10.1 and write import JsSIP from 'jssip';.

import JsSIP from 'https://cdn.jsdelivr.net/npm/jssip@3.10.1/+esm';

const {sipUsername, sipPassword} = await (await fetch('/phone-login')).json();

const socket = new JsSIP.WebSocketInterface('wss://websocket.telebroad.com:8443');
socket.via_transport = 'auto';

const ua = new JsSIP.UA({
sockets: [socket],
uri: `${sipUsername}@reg.telebroad.com:5060`,
password: sipPassword,
instance_id: sessionStorage.phoneId ||= crypto.randomUUID(), // one id per browser tab
user_agent: 'MyWebPhone', // your app's name (Teleconsole sends "TeleConsole")
});

ua.on('registered', () => console.log('Ready — your line is online'));
ua.on('registrationFailed', (e) => console.log('Sign-in failed:', e.cause));
ua.on('disconnected', () => console.log('Connection lost — JsSIP will retry'));

ua.start(); // connects and registers by itself

// Sign out when the tab closes, so calls don't ring a closed page.
addEventListener('pagehide', () => ua.stop());

The instance_id is kept in sessionStorage, so it stays the same when the tab reloads (Teleconsole does the same). A new id on every reload would leave the old sign-in on the line for up to 10 minutes, and calls could ring that dead page.

That is all it takes: once you see registered, calls to that line ring this page. JsSIP renews the registration on its own (each one lasts 10 minutes) and reconnects by itself if the connection drops.

Step 4 — Make a call​

Pass a plain number — JsSIP adds the SIP domain for you. Use 11 digits for US numbers (1 + area code + number), or an extension.

const callOptions = {
mediaConstraints: {audio: {echoCancellation: true, noiseSuppression: true}, video: false},
pcConfig: {
rtcpMuxPolicy: 'require',
iceServers: [{urls: ['stun:stun.l.google.com:19302']}],
},
};

let session = ua.call('12125550123', callOptions);
sendEarly(session);
playRemoteAudio(session); // Step 6

// Send the call as soon as we know our public address,
// instead of waiting for every network path to be checked.
function sendEarly(s) {
s.on('icecandidate', (e) => {
if (e.candidate.type === 'srflx' && e.candidate.relatedAddress !== null && e.candidate.relatedPort !== null) {
e.ready();
}
});
}

Teleconsole uses the same icecandidate trick. Without it, JsSIP waits until the browser has checked every network path before it sends the call. On computers with a VPN or several network adapters, that can delay the call by many seconds.

The caller ID the other person sees is set on the line in the admin center — you do not set it here.

Step 5 — Answer an incoming call​

Every call, in or out, arrives as a newRTCSession event. Incoming ones have originator: 'remote'. JsSIP tells the caller "ringing" by itself; you decide when to answer.

ua.on('newRTCSession', ({session: s, originator}) => {
if (originator !== 'remote') return; // our own outgoing call
if (session) { // already on a call: tell the caller we're busy
s.terminate({status_code: 486, reason_phrase: 'Busy Here'});
return;
}
session = s;
const caller = s.remote_identity.display_name || s.remote_identity.uri.user;
console.log('Incoming call from', caller);

s.on('ended', () => console.log('Call ended'));
s.on('failed', () => console.log('Call missed or rejected'));

// Later, when the user clicks "Answer":
// sendEarly(s); (Step 4 — answers faster too)
// s.answer(callOptions);
// playRemoteAudio(s);
});

To decline instead, call s.terminate({status_code: 486, reason_phrase: 'Busy Here'}).

Ringing in a background tab

Browsers block sound until the person has clicked somewhere on the page. Play your ringtone only after that first click, and consider a browser notification so calls aren't missed while the tab is hidden.

Step 6 — Hear the other side​

The other person's voice arrives as a media track. Put it into an <audio> element and press play.

const remoteAudio = new Audio();

function playRemoteAudio(s) {
const attach = (pc) => pc.addEventListener('track', (e) => {
remoteAudio.srcObject = e.streams[0];
remoteAudio.play().catch(() => {});
});
// The audio connection normally exists already; if not, wait for it.
if (s.connection) attach(s.connection);
else s.on('peerconnection', (e) => attach(e.peerconnection));
}

Call this right after ua.call() or session.answer() — both happen on a button click, which is what lets the browser play sound.

Step 7 — Mute, hold, keypad and hang up​

To…CodeWhat happens
Mute / unmutesession.mute() / session.unmute()Your microphone is silenced in the browser
Hold / resumesession.hold() / session.unhold()The call is put on hold (the other person hears your hold music, if one is set)
Press a keysession.sendDTMF('1')Sends the digit — for menus ("press 1 for sales")
Hang upsession.terminate()Ends the call (or cancels it while ringing)
Transfersession.refer('205'); session.terminate();Sends the caller to another number or extension, then you drop off

That is how Teleconsole does it too, including transfers. To show the right button label, ask the call itself: session.isMuted().audio and session.isOnHold().local are true while muted or on hold.

The whole thing in one file​

Save this as public/index.html next to the server from Step 2, start the server as shown there, and open http://localhost:3000. Click Start phone first — browsers need a click before they allow the microphone and sound.

<!doctype html>
<html>
<head>
<meta charset="utf-8">
<title>My web phone</title>
<style>
body { font-family: system-ui, sans-serif; max-width: 360px; margin: 40px auto; }
button, input { font-size: 16px; padding: 8px; margin: 4px 0; }
input { width: 100%; box-sizing: border-box; }
#status { font-weight: bold; }
</style>
</head>
<body>
<h1>My web phone</h1>
<p>Status: <span id="status">offline</span></p>
<button id="start">Start phone</button>

<input id="number" placeholder="Number to call, e.g. 12125550123">
<button id="call">Call</button>
<button id="answer" disabled>Answer</button>
<button id="hangup" disabled>Hang up</button>
<button id="mute" disabled>Mute</button>
<button id="hold" disabled>Hold</button>
<button id="transfer" disabled>Transfer</button>
<p>Keypad: <span id="keys"></span></p>

<script type="module">
import JsSIP from 'https://cdn.jsdelivr.net/npm/jssip@3.10.1/+esm';

const WSS = 'wss://websocket.telebroad.com:8443'; // same for every account
const DOMAIN = 'reg.telebroad.com:5060'; // same for every account
const LOGIN_URL = '/phone-login'; // ← your server endpoint (Step 2)

const $ = (id) => document.getElementById(id);
const setStatus = (text) => ($('status').textContent = text);
const remoteAudio = new Audio();
const callOptions = {
mediaConstraints: {audio: {echoCancellation: true, noiseSuppression: true}, video: false},
pcConfig: {rtcpMuxPolicy: 'require', iceServers: [{urls: ['stun:stun.l.google.com:19302']}]},
};
let ua, session;

function inCall(on) {
$('hangup').disabled = $('mute').disabled = $('hold').disabled = $('transfer').disabled = !on;
if (!on) { session = null; $('mute').textContent = 'Mute'; $('hold').textContent = 'Hold'; }
}

function playRemoteAudio(s) {
const attach = (pc) => pc.addEventListener('track', (e) => {
remoteAudio.srcObject = e.streams[0];
remoteAudio.play().catch(() => {});
});
if (s.connection) attach(s.connection);
else s.on('peerconnection', (e) => attach(e.peerconnection));
}

function sendEarly(s) { // send the call as soon as we know our public address (Step 4)
s.on('icecandidate', (e) => {
if (e.candidate.type === 'srflx' && e.candidate.relatedAddress !== null && e.candidate.relatedPort !== null) e.ready();
});
}

function watch(s) {
session = s;
s.on('confirmed', () => { setStatus('in a call'); inCall(true); });
s.on('ended', () => { setStatus('online'); inCall(false); });
s.on('failed', (e) => { setStatus('online (last call: ' + e.cause + ')'); $('answer').disabled = true; inCall(false); });
}

$('start').onclick = async () => {
try { // ask for the microphone now, then let it go again
(await navigator.mediaDevices.getUserMedia({audio: true})).getTracks().forEach((t) => t.stop());
} catch {
return setStatus('microphone blocked');
}
const r = await fetch(LOGIN_URL);
if (!r.ok) return setStatus('could not get line login (' + r.status + ')');
const {sipUsername, sipPassword} = await r.json();

const socket = new JsSIP.WebSocketInterface(WSS);
socket.via_transport = 'auto';
ua = new JsSIP.UA({
sockets: [socket],
uri: `${sipUsername}@${DOMAIN}`,
password: sipPassword,
instance_id: sessionStorage.phoneId ||= crypto.randomUUID(),
user_agent: 'MyWebPhone',
});

ua.on('registered', () => setStatus('online'));
ua.on('registrationFailed', (e) => setStatus('sign-in failed: ' + e.cause));
ua.on('disconnected', () => setStatus('reconnecting…'));
ua.on('newRTCSession', ({session: s, originator}) => {
if (originator !== 'remote') return;
if (session) return s.terminate({status_code: 486, reason_phrase: 'Busy Here'}); // already busy
watch(s);
setStatus('ringing: ' + (s.remote_identity.display_name || s.remote_identity.uri.user));
$('answer').disabled = $('hangup').disabled = false; // Hang up = decline
});

ua.start();
$('start').disabled = true;
};

addEventListener('pagehide', () => ua?.stop()); // sign out when the tab closes

$('call').onclick = () => {
const number = $('number').value.replace(/[^0-9*#]/g, '');
if (!ua || !number || session) return;
watch(ua.call(number, callOptions));
sendEarly(session);
playRemoteAudio(session);
setStatus('calling ' + number + '…');
inCall(true);
};

$('answer').onclick = () => {
sendEarly(session);
session.answer(callOptions);
playRemoteAudio(session);
$('answer').disabled = true;
};

$('hangup').onclick = () => session?.terminate();
$('mute').onclick = () => {
session.isMuted().audio ? session.unmute() : session.mute();
$('mute').textContent = session.isMuted().audio ? 'Unmute' : 'Mute';
};
$('hold').onclick = () => {
const wasHeld = session.isOnHold().local; // hold() finishes a moment later
wasHeld ? session.unhold() : session.hold();
$('hold').textContent = wasHeld ? 'Hold' : 'Resume';
};
$('transfer').onclick = () => {
const to = prompt('Transfer to number or extension:');
if (to) { session.refer(to); session.terminate(); }
};

for (const key of '123456789*0#') {
const b = document.createElement('button');
b.textContent = key;
b.onclick = () => session?.sendDTMF(key);
$('keys').append(b);
}
</script>
</body>
</html>

Events you'll use​

On the phone — ua.on(...)

EventFires when
connectedThe WebSocket to the phone system is open
disconnectedThe WebSocket closed. JsSIP keeps retrying by itself
registeredYour line is signed in and can receive calls
registrationFailedSign-in was refused. e.cause says why (see Troubleshooting)
newRTCSessionA call starts, in or out. originator is 'local' or 'remote'

On a call — session.on(...)

EventFires when
peerconnectionThe audio connection is created
progressThe other side is ringing
acceptedThe call was answered
confirmedThe call is fully set up and audio is flowing
hold / unholdEither side put the call on or off hold. e.originator says who
endedA connected call hung up normally
failedThe call never connected — busy, no answer, declined, cancelled, or the microphone was blocked. e.cause says which

The full list is in the JsSIP documentation.

Troubleshooting​

What you seeWhat it usually meansWhat to do
registrationFailed with cause Authentication Error (a 401 or 407 that never succeeds)Wrong SIP username or passwordFetch /me again — the password may have been changed. Check that uri is <sipUsername>@reg.telebroad.com:5060.
registrationFailed with cause Rejected (403)Often an IP-locked line: it only accepts phones from set addresses, and the browser's address is not one of themAsk your admin to remove or update the line's IP lock in the admin center.
disconnected straight away, never registeredThe WebSocket could not connect. A firewall may block port 8443, or the server may not accept pages from your website's addressTry from another network. If it still fails, contact Telebroad support — tell them the web address your page is served from.
getUserMedia error, or no microphone promptThe page is not on HTTPS, or the person said no to the microphoneServe the page over HTTPS (or localhost), and allow the microphone in the browser's site settings.
Call connects but you hear nothingThe browser blocked sound because nobody clicked anythingStart calls and answers from a button click, as in the example. Check remoteAudio.play() is reached.
One-way or no audio on some networksA strict firewall or router (symmetric NAT). The settings above use a public STUN server only, with no relay (TURN) serverTry another network. Adding your own TURN server to iceServers helps on strict networks.
Call drops on hold or resume with Incompatible send directionTeleconsole sees this when its calls offer to receive video: the phone system answers with a video setting JsSIP refuses. Teleconsole fixes it by rewriting that video line to a=sendonlyKeep calls audio-only (video: false, as above).
Works, then stops ringing after a whileThe browser froze or discarded the tab, or the connection dropped quietlyShow disconnected in your page so people notice, and keep the phone in a tab that stays open.
Worked yesterday, fails todayThe line's password was changed or the line was removedFetch /me again on each page load instead of saving the password.

To see every SIP message JsSIP sends and receives, add JsSIP.debug.enable('JsSIP:*') right after the import line and reload. The messages show in the browser console.

Security checklist​

  • The API key stays on your server. The page only ever sees one line's login, and only after your own sign-in check.
  • Treat a SIP password like a password. Anyone who has it can make calls on your account, billed to you, from anywhere. Don't log it, don't put it in a URL, and don't save it in the browser — fetch it fresh when the page loads.
  • Every /me read is recorded. profile:read is a sensitive scope, and each fetch of the phone logins is audited on your account.
  • Only own lines. /me returns the lines of the person behind the credential and never a colleague's — give each person their own run-as user or OAuth sign-in.
  • If a password leaks, change the line's SIP password in the admin center right away. Phones using the old one stop working the next time they sign in, so fetch /me again to get the new one. If the API key leaked, rotate it too.