Getting Started: VaxVoIP WebPhone SDK Tutorial for DevelopersVaxVoIP WebPhone SDK is a JavaScript library designed to bring SIP-based voice, video, and messaging capabilities directly into web applications using WebRTC. This tutorial walks through the essentials: installation, core concepts, initialization, handling calls and messages, common integration patterns (React/Angular), security considerations, debugging tips, and production deployment recommendations. By the end you’ll have a working knowledge to integrate a browser softphone or in-app calling feature.
What the SDK provides (at a glance)
- Browser SIP over WebRTC: Register and handle SIP signaling in the browser while using secure WebRTC media.
- Call control: Make, receive, hold, transfer, and end calls.
- Video and audio: Negotiation and media stream handling for 1:1 and conference scenarios.
- Messaging: In-band SIP MESSAGE support for text chat.
- Events and hooks: Fine-grained event model to wire UI and application logic.
- Pluggable transport/backends: Works with standard SIP servers and popular VoIP backends.
Prerequisites
- Intermediate familiarity with JavaScript/TypeScript and modern front-end frameworks (React/Angular/Vue).
- Basic understanding of SIP and WebRTC concepts (SIP registration, SDP, ICE, STUN/TURN).
- A SIP account (username, password, SIP server/edge) or access to a SIP backend for testing.
- HTTPS hosting (browsers require secure context for getUserMedia and WebRTC).
- Optional: TURN server credentials if testing across NATs/firewalls.
Installation
Install via npm (recommended):
npm install vaxvoip-webphone-sdk
Or include via a CDN/script tag:
<script src="https://cdn.example.com/vaxvoip-webphone-sdk/latest/vaxvoip-webphone-sdk.min.js"></script>
(Adjust URL to actual CDN path provided by VaxVoIP.)
Core Concepts
- User Agent (UA): The SDK typically exposes a UA/client object which manages SIP registration, transports, and active sessions.
- Session: Represents an active call (incoming or outgoing). Sessions expose media streams, state, and control methods (answer, hangup, hold, transfer).
- Events: The SDK emits events for registration state, incoming call, call progress, track added/removed, message received, and errors.
- Media constraints: Control over audio/video capture, codecs, and device selection.
- ICE/DTLS: WebRTC uses ICE for connectivity checks and DTLS/SRTP for encrypting media. The SDK surfaces configuration for STUN/TURN and ICE options.
Quick start: Minimal example
Below is a concise example showing initialization, registration, making and receiving a call, and attaching local/remote streams to the DOM.
import VaxWebPhone from 'vaxvoip-webphone-sdk'; const config = { uri: 'sip:[email protected]', authorizationUser: 'alice', password: 'alicePassword', wsServers: ['wss://sip-ws.example.com'], displayName: 'Alice', stunServers: ['stun:stun.l.google.com:19302'], turnServers: [{ urls: 'turn:turn.example.com:3478', username: 'turnuser', credential: 'turnpass' }], iceTransportPolicy: 'all', media: { audio: true, video: true } }; const ua = new VaxWebPhone.UA(config); // DOM elements const localVideo = document.getElementById('localVideo'); const remoteVideo = document.getElementById('remoteVideo'); ua.on('registered', () => console.log('Registered')); ua.on('registrationFailed', (err) => console.error('Registration failed', err)); ua.on('incomingCall', async (session) => { console.log('Incoming call from', session.remoteIdentity.uri.toString()); // auto-answer example: await session.answer({ media: { audio: true, video: true } }); attachSessionStreams(session); }); function attachSessionStreams(session) { session.on('track', (event) => { // event.streams[0] is remote stream remoteVideo.srcObject = event.streams[0]; }); // get local stream and show navigator.mediaDevices.getUserMedia({ audio: true, video: true }) .then(stream => { localVideo.srcObject = stream; session.sessionDescriptionHandler?.peerConnection.getSenders().forEach((s) => { // senders already attached by SDK typically; code depends on SDK specifics }); }); } async function call(target) { const session = ua.invite(`sip:${target}`, { media: { audio: true, video: true } }); session.on('progress', () => console.log('Ringing...')); session.on('accepted', () => attachSessionStreams(session)); session.on('terminated', () => console.log('Call ended')); }
Note: exact API names (UA, invite, events) depend on the SDK’s implementation; consult the SDK reference for exact method signatures.
const devices = await navigator.mediaDevices.enumerateDevices(); const audioInputs = devices.filter(d => d.kind === 'audioinput'); const videoInputs = devices.filter(d => d.kind === 'videoinput');
- Select a specific camera/microphone when creating/getting media:
const stream = await navigator.mediaDevices.getUserMedia({ audio: { deviceId: selectedAudioId ? { exact: selectedAudioId } : undefined }, video: { deviceId: selectedVideoId ? { exact: selectedVideoId } : undefined } });
- Switch devices mid-call by obtaining a new track and replacing the sender’s track:
const newStream = await navigator.mediaDevices.getUserMedia({ video: { deviceId: { exact: newVideoId } } }); const videoTrack = newStream.getVideoTracks()[0]; const sender = session.sessionDescriptionHandler.peerConnection.getSenders() .find(s => s.track && s.track.kind === 'video'); sender.replaceTrack(videoTrack);
Call control features
- Answer: session.answer({ media: { audio: true, video: false } })
- Hangup: session.terminate() or session.bye()
- Hold/resume: session.hold() / session.unhold() (may use re-INVITE/SDP
a=sendonly/a=recvonly)
- Transfer: session.transfer(target) or attended transfer flow via REFER
- Mute/unmute: stop local track or use RTCRtpSender.setParameters() to adjust encoding
Messaging (SIP MESSAGE)
Send a text message via the UA/session:
ua.sendMessage('sip:[email protected]', 'Hello from VaxWebPhone SDK');
Listen for incoming messages:
ua.on('message', (msg) => { console.log('Message from', msg.remoteIdentity.uri.toString(), msg.body); });
Integration patterns
React
- Keep UA as a singleton or in React context so components can access registration state and sessions.
- Use useEffect to initialize/cleanup UA on mount/unmount.
- Store active sessions in state; render call UI from session events.
Example pattern:
// PhoneContext.js import React, { createContext, useEffect, useState } from 'react'; import VaxWebPhone from 'vaxvoip-webphone-sdk'; export const PhoneContext = createContext(); export function PhoneProvider({ children }) { const [ua, setUa] = useState(null); useEffect(() => { const client = new VaxWebPhone.UA(config); setUa(client); return () => client.stop(); }, []); return <PhoneContext.Provider value={{ ua }}>{children}</PhoneContext.Provider>; }
Angular
- Create an injectable service that manages the UA lifecycle and exposes Observables for registration and sessions.
- Use ngOnDestroy to unregister and cleanup.
Security best practices
- Always use WSS/WSS+TURN over HTTPS. Avoid plain WS/WSS without TLS.
- Use short-lived credentials and OAuth/IMS tokens rather than long-lived static passwords where possible.
- Use TURN servers to handle NAT traversal securely; restrict TURN credentials per user/session if supported.
- Sanitize and validate incoming SIP headers/messages if exposing any UI that reflects them.
- Ensure proper content security policy (CSP) headers and HTTPS configuration on your hosting.
Debugging tips
- Enable SDK logging (if available) and route logs to console.
- Use browser WebRTC internals: chrome://webrtc-internals (Chrome) to inspect ICE candidates, DTLS, RTP, and stats.
- Check STUN/TURN connectivity with samples like testRTC or simple WebRTC test pages.
- Monitor SIP signaling with your SIP server logs; use ngrep/tcpdump on the SIP edge if permitted.
- Verify device permissions and HTTPS context if getUserMedia fails.
Testing and staging
- Test on multiple browsers — Chrome and Edge use Chromium engine, Firefox has different codec/DTLS behavior, and Safari has specific constraints for autoplay and media capture.
- Validate mobile browsers and in-app webviews; some webviews restrict WebRTC or require special configuration.
- Use network throttling and simulated packet loss to ensure call quality under adverse conditions.
Production deployment checklist
- Use HTTPS and WSS endpoints with valid certificates.
- Configure TURN with geographic redundancy and authentication.
- Implement rate-limiting and access controls on SIP edge servers.
- Monitor call quality (MOS, packet loss, jitter) via periodic stats collection and alerts.
- Implement fallback UX for when media or signaling fails (e.g., offer callback or PSTN fallback).
Advanced topics & next steps
- Conferencing: server-mixed (MCU) vs. client-mixed (SFU) approaches; WebPhone SDK can be used as a client to both models—choose based on scale and bandwidth.
- Recording: capture media streams server-side or use media-server integrations (Asterisk, FreeSWITCH, Janus, Jitsi, mediasoup) to record calls.
- Analytics: collect RTCP stats and use them to display per-call diagnostics and historical reporting.
- Custom codecs and transcoding: understand browser codec support (Opus, VP8, H.264) and transcode server-side if necessary.
Example resources
- SDK API reference (consult vendor docs for exact method names and signatures).
- SIP and WebRTC specs (RFC 3261, RTCWEB, etc.).
- WebRTC debugging guides and chrome://webrtc-internals.
If you want, I can: provide a full React example app using VaxVoIP WebPhone SDK, draft a minimal server-side token auth flow for registration, or generate code snippets for call transfer and hold/resume flows.