Skip to main content
When you finish this page, a softphone that runs in a browser tab receives calls after the user has closed the tab. This works for apps built on SIP.js, JsSIP, or any other SIP over WebSocket library.

How a browser app differs from a mobile app

A browser softphone connects to pgw over a secure WebSocket instead of TLS, and pgw wakes it with Web Push, the push service that every major browser includes. Plan for these differences:
  • You need no developer account. Web Push has no developer console. pgw generates a key pair for your app, called a VAPID key, and signs each push with it.
  • A push can’t ring by itself. A mobile push starts the app, and the phone rings. A Web Push only lets the app’s service worker show a notification. The call connects when the user clicks the notification and the page opens. That must happen while pgw still holds the call, which is 30 seconds by default (hold_seconds).

Before you begin

  • A certificate from a public certificate authority in tls_cert_file and tls_key_file. Browsers refuse a self-signed certificate. See Install a TLS certificate.
  • A browser softphone that you can change, because it must subscribe to Web Push and send the subscription to pgw.

Open the WebSocket listener

The WebSocket listener is off by default. Set app_wss_listen, and restart pgw:
The app connects to this URL, with your hostname and port. pgw accepts any path:
On this connection, the app must do the following:
  • Ask for the sip subprotocol (Sec-WebSocket-Protocol: sip). pgw answers every upgrade with sip, and a browser closes a WebSocket when the server picks a subprotocol that the browser didn’t ask for.
  • Send the whole upgrade request within app_handshake_timeout, which is 10 seconds by default, and keep it to 8 KB or less. Otherwise pgw closes the connection.
  • Keep one WebSocket open and send every request on it. Calls reach the app only on that connection, and a request on another connection gets 403 Forbidden.
A browser app that holds no SIP password can register with a token from your own sign-in service. See Authenticate apps with a Bearer token.

Create the web app and subscribe

1

Create the web app

A tenant can have one web app. Set --vapid-subject to a mailto: or https: URI that push services can use to contact you. --bundle-id is a label of your choice.
pgw generates a VAPID key pair, and the output shows the public key in vapid_public_key.
You don’t copy the key into the app, because pgw sends it in each REGISTER’s 200 OK.
2

Back up the private key

If you ever create the app again with a new key, every subscription ends. Export the key, so that you can create the app again with the same one.
pgw writes the file readable only by you, and refuses to overwrite an existing file. To restore the app on another pgw, pass the file to pgw app create --vapid-key-file, or name it in vapid_private_key_pem_file in a tenant file.
3

Check the allowed push services

pgw pushes only to the hosts in webpush_hosts. The default lists the push services of Chrome, Edge, Firefox, and Safari: fcm.googleapis.com, updates.push.services.mozilla.com, web.push.apple.com, and *.notify.windows.com. Add the host of any other browser that you support.
4

Subscribe and register in the app

In the app, connect over WebSocket, and then do the following:
  1. Send a REGISTER with pn-provider=webpush and no pn-prid in its Contact. The 200 OK carries the key in its Feature-Caps header, as +sip.vapid="<key>". This request registers nothing at the PBX.
  2. Subscribe with that key: registration.pushManager.subscribe({userVisibleOnly: true, applicationServerKey: key}).
  3. Register with pn-provider=webpush and pn-prid set to the subscription’s endpoint, percent-encoded. Leave out pn-param. Send the same +sip.instance each time, so that pgw recognizes the browser. The browser now gets calls.
  4. In the service worker, show a notification for every push. Browsers stop sending pushes to a service worker that doesn’t. When the user opens the notification, open the app, which registers again.
To change --vapid-subject later, send PATCH /api/v1/apps/{id} with a new vapid_subject. An app’s VAPID key can’t change.

How long a browser stays registered

An open page registers again before its expiry. A closed page can’t, and pgw can’t wake it silently to renew its registration, as it wakes a mobile app. What happens at the expiry depends on the mode:
  • In passthrough mode, the registration ends at its expiry.
  • In managed mode, pgw keeps the registration while the push subscription works. It ends when the push service reports the subscription gone, or when the page hasn’t registered for the time in credential_silence_purge.
For a browser softphone that should ring after the tab is closed, use managed mode.

Next steps

Managed mode

Keep a browser registered while its page is closed.

Sign in with a Bearer token

Register a browser app without giving it a SIP password.

Push payload

Look up the headers of each Web Push, to debug a push service’s refusal.