web-sip-phone
v0.1.0
Published
Browser softphone on sip.js. Connect, register, and control calls from any project.
Maintainers
Readme
web-sip-phone
Browser softphone built on sip.js. Your app passes a config and calls a short list of functions. SIP registration, WebRTC, and call audio stay inside this package.
Install
npm install web-sip-phoneThe package is ESM. Import it from the browser bundle of your app (Vite, Webpack, or another bundler). The page must be a secure context: https:// or http://localhost. The microphone is blocked on plain http:// to a LAN address.
Configure
Create one phone and pass only the fields that differ from the defaults. Empty strings are ignored, so a missing env var does not wipe a default.
import { createSoftphone } from "web-sip-phone";
const phone = createSoftphone({
server: "wss://pbx.example.com:7443",
domain: "pbx.example.com",
username: "2002",
password: "2002",
displayName: "Agent"
});username and password are required before start(). Every other field has a default.
| Field | Default | What it does |
|---|---|---|
| server | wss://10.1.1.144:7443 | SIP WebSocket URL. Use wss:// when the page is HTTPS. |
| domain | 10.1.1.144 | SIP domain. The extension becomes sip:username@domain. |
| username | none | Extension / SIP auth user. |
| password | none | SIP auth password. |
| displayName | none | Name shown on outbound calls. |
| iceServers | [{ urls: "stun:stun.l.google.com:19302" }] | WebRTC ICE servers. |
| iceGatheringTimeout | 2000 | How long to wait for ICE candidates, in milliseconds. |
| registerExpires | 600 | REGISTER expiry, in seconds. |
| registerTimeout | 15000 | How long start() waits for a successful REGISTER, in milliseconds. |
| dtmfMode | "rtp" | "rtp" sends telephone-event. "info" sends SIP INFO. rtp falls back to INFO if the browser cannot send the tone. |
| dtmfDuration | 160 | Tone length in milliseconds when DTMF is sent as SIP INFO. |
| debug | false | Log SIP details in the browser console. |
| remoteAudioElement | created for you | An existing <audio autoplay> element. When omitted, a hidden element is added to the page. |
Read the built-in defaults, or preview a merged config without creating a phone:
import { defaultConfig, resolveConfig } from "web-sip-phone";
defaultConfig.server; // "wss://10.1.1.144:7443"
const config = resolveConfig({
username: "2002",
password: "2002"
});Change config after login
Call configure() before start(), or after stop(). It merges into the current config. Pass only the fields that changed.
const phone = createSoftphone();
phone.configure({
server: import.meta.env.VITE_SIP_WEBSOCKET,
domain: import.meta.env.VITE_SIP_DOMAIN,
username: agent.extension,
password: agent.sipPassword,
displayName: agent.name
});
await phone.start();configure() throws if the phone is already connected. Call stop() first, then configure(), then start().
getConfig() returns the resolved config, including defaults you did not pass.
Override one call
call() accepts optional SIP headers for that invite only. The phone config stays the same.
await phone.call("4099", {
extraHeaders: ["X-Call-Source: click-to-call"]
});Use
Subscribe to events before start(). on() returns a function that removes that listener.
const stopRegistered = phone.on("registered", ({ uri }) => {
console.log("registered", uri);
});
phone.on("registrationFailed", ({ message, statusCode }) => {
console.error(message, statusCode);
});
phone.on("incoming", ({ from, uri, displayName }) => {
// show Answer / Reject for `from`
});
phone.on("established", ({ direction, remote }) => {
// direction is "inbound" or "outbound"
});
phone.on("terminated", ({ reason, direction, remote }) => {
// "local" | "remote" | "rejected" | "invite-failed" | "invite-<status>"
});
await phone.start(); // connect the WebSocket and REGISTER
await phone.call("4099");
phone.mute(); // toggle. phone.mute(true) or phone.mute(false) sets it
await phone.hold(); // toggle. phone.hold(true) or phone.hold(false) sets it
await phone.dtmf("1"); // one or more tones: "1" or "*123"
await phone.hangup();
await phone.stop(); // hang up if needed, unregister, disconnect
stopRegistered();| Function | When to call it |
|---|---|
| start() | After login, when this extension should be reachable. Resolves after REGISTER succeeds. |
| stop() | On logout or when the page is closing. |
| call(number) | Dial an extension or PSTN number. Same function for a test call to 4099 and for click-to-call. |
| answer() | After an "incoming" event, while it is still ringing. |
| reject() | Decline a ringing inbound call. |
| hangup() | Cancel an outbound attempt, or end an established call. |
| mute(muted?) | During an established call. No argument toggles. |
| hold(held?) | During an established call. No argument toggles. |
| dtmf(tones) | During an established call. Tones are 0-9, A-D, #, and *. |
| getState() | Read { started, registered, inCall, direction, remote, muted, held, sessionState }. |
A second inbound call is rejected with 486 Busy while one call is already active. call() throws if a call is already in progress. answer(), reject(), hangup(), mute(), hold(), and dtmf() throw when they are used in the wrong state.
Incoming call
let ringing = false;
phone.on("incoming", ({ from, displayName }) => {
ringing = true;
showIncoming(displayName || from);
});
phone.on("established", () => {
ringing = false;
});
phone.on("terminated", () => {
ringing = false;
showIdle();
});
async function onAnswerClick() {
if (ringing) {
await phone.answer();
}
}
async function onRejectClick() {
if (ringing) {
await phone.reject();
}
}Click to call
async function onNumberClick(number) {
const { registered, inCall } = phone.getState();
if (!registered || inCall) {
return;
}
await phone.call(number);
}Browser notes
- Allow the microphone when
call()oranswer()runs. Both ask for it before sending or accepting audio. - Keep one tab registered for an extension. Two tabs fight over the same SIP registration.
- Remote audio plays through
remoteAudioElement, or through a hidden<audio autoplay>element the package creates.
