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_fileandtls_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. Setapp_wss_listen, and restart pgw:
hostname and port. pgw accepts any path:
- Ask for the
sipsubprotocol (Sec-WebSocket-Protocol: sip). pgw answers every upgrade withsip, 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.
Create the web app and subscribe
1
Create the web app
A tenant can have one web app. Set pgw generates a VAPID key pair, and the output shows the public key in You don’t copy the key into the app, because pgw sends it in each REGISTER’s 200 OK.
--vapid-subject to a mailto: or https: URI that push services can use to contact you. --bundle-id is a label of your choice.vapid_public_key.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:
- Send a REGISTER with
pn-provider=webpushand nopn-pridin its Contact. The 200 OK carries the key in its Feature-Caps header, as+sip.vapid="<key>". This request registers nothing at the PBX. - Subscribe with that key:
registration.pushManager.subscribe({userVisibleOnly: true, applicationServerKey: key}). - Register with
pn-provider=webpushandpn-pridset to the subscription’sendpoint, percent-encoded. Leave outpn-param. Send the same+sip.instanceeach time, so that pgw recognizes the browser. The browser now gets calls. - 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.
--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.
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.