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:
- A credential with the "Read your profile and phone line logins" scope
(
profile:read). It is off by default — tick it on purpose. - 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. - A page served over HTTPS (or
http://localhostwhile testing). Browsers only allow the microphone on secure pages.
-
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 address | wss://websocket.telebroad.com:8443 |
| SIP domain | reg.telebroad.com:5060 |
| JsSIP version | 3.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
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'}).
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… | Code | What happens |
|---|---|---|
| Mute / unmute | session.mute() / session.unmute() | Your microphone is silenced in the browser |
| Hold / resume | session.hold() / session.unhold() | The call is put on hold (the other person hears your hold music, if one is set) |
| Press a key | session.sendDTMF('1') | Sends the digit — for menus ("press 1 for sales") |
| Hang up | session.terminate() | Ends the call (or cancels it while ringing) |
| Transfer | session.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(...)
| Event | Fires when |
|---|---|
connected | The WebSocket to the phone system is open |
disconnected | The WebSocket closed. JsSIP keeps retrying by itself |
registered | Your line is signed in and can receive calls |
registrationFailed | Sign-in was refused. e.cause says why (see Troubleshooting) |
newRTCSession | A call starts, in or out. originator is 'local' or 'remote' |
On a call — session.on(...)
| Event | Fires when |
|---|---|
peerconnection | The audio connection is created |
progress | The other side is ringing |
accepted | The call was answered |
confirmed | The call is fully set up and audio is flowing |
hold / unhold | Either side put the call on or off hold. e.originator says who |
ended | A connected call hung up normally |
failed | The 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 see | What it usually means | What to do |
|---|---|---|
registrationFailed with cause Authentication Error (a 401 or 407 that never succeeds) | Wrong SIP username or password | Fetch /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 them | Ask your admin to remove or update the line's IP lock in the admin center. |
disconnected straight away, never registered | The WebSocket could not connect. A firewall may block port 8443, or the server may not accept pages from your website's address | Try 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 prompt | The page is not on HTTPS, or the person said no to the microphone | Serve the page over HTTPS (or localhost), and allow the microphone in the browser's site settings. |
| Call connects but you hear nothing | The browser blocked sound because nobody clicked anything | Start calls and answers from a button click, as in the example. Check remoteAudio.play() is reached. |
| One-way or no audio on some networks | A strict firewall or router (symmetric NAT). The settings above use a public STUN server only, with no relay (TURN) server | Try another network. Adding your own TURN server to iceServers helps on strict networks. |
| Call drops on hold or resume with Incompatible send direction | Teleconsole 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=sendonly | Keep calls audio-only (video: false, as above). |
| Works, then stops ringing after a while | The browser froze or discarded the tab, or the connection dropped quietly | Show disconnected in your page so people notice, and keep the phone in a tab that stays open. |
| Worked yesterday, fails today | The line's password was changed or the line was removed | Fetch /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
/meread is recorded.profile:readis a sensitive scope, and each fetch of the phone logins is audited on your account. - Only own lines.
/mereturns 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
/meagain to get the new one. If the API key leaked, rotate it too.