Emergency Location Service (Windows and macOS)¶

Cloud Softphone for Windows and macOS includes an Emergency Location Service that helps meet E911 dispatchable-location requirements (for example Kari’s Law and RAY BAUM’s Act). The service determines the caller’s physical address by matching the current network environment (public IP, local subnet, and Wi-Fi BSSID) against pre-configured locations provisioned by the service provider.

Emergency Address Format (JSON)¶

Emergency addresses are supplied through the emergencyLocations preference key as a JSON array string. Each element describes one location that the service can match against.

Example ¶

[
  {
    "BSSID": "AA:BB:CC:DD:EE:FF",
    "PublicIP": "203.0.113.42",
    "InternalSubnet": "10.1.0.0/16",
    "CivicAddress": {
      "HNO": "100",
      "RD":  "Main",
      "STS": "St",
      "LOC": "Suite 200",
      "A3":  "Springfield",
      "A1":  "IL",
      "PC":  "62704",
      "country": "US"
    }
  }
]

Location fields ¶

Field	Required	Description
`BSSID`	No	Wi-Fi access-point MAC address. Enables the highest-priority match. Omit for wired-only locations.
`PublicIP`	No	The public (NAT-external) IPv4 or IPv6 address that traffic from this location exits through.
`InternalSubnet`	No	CIDR notation (for example `10.1.0.0/16` or `fd00::/64`). Used together with `PublicIP` for subnet-level matching.
`CivicAddress`	Yes	The physical address sent in the SIP PIDF-LO body.

BSSID, PublicIP, and InternalSubnet are optional individually, but a location entry must include a valid match key to ever be selected. In practice, the entry must contain at least one of these matchable patterns: BSSID, PublicIP + InternalSubnet, or PublicIP alone.

CivicAddress fields ¶

The values are based on RFC 4119 and RFC 5139 civic-address elements. All fields are optional individually, but the CivicAddress object itself must be present.

Key	Meaning
`HNO`	House number (numeric part)
`HNS`	House number suffix
`PRD`	Leading street direction (for example `N`, `SW`)
`RD`	Primary road/street name
`STS`	Street suffix (for example `St`, `Ave`)
`POD`	Trailing street direction
`LOC`	Additional location info (floor, suite, room)
`A3`	City/township
`A1`	State/province
`PC`	Postal/ZIP code
`country`	ISO 3166 alpha-2 country code

Emergency Numbers ¶

Emergency numbers are stored in the emergencyNumbers preference key as a comma-separated list (for example "911,112").

If the service finds a matching location, emergency-location data is always embedded into SIP INVITE requests sent to numbers in emergencyNumbers (for example test number 933). These emergency INVITE requests include:

Geolocation and Geolocation-Routing: yes headers
Accept: application/pidf+xml
A multipart/mixed body with SDP and a PIDF-LO part that carries the matched civic address

This behavior guarantees that matched emergency calls carry dispatchable location data in standards-based SIP geolocation fields.

Provisioning ¶

The emergencyLocations and emergencyNumbers preference keys can be populated through several channels:

Main app provisioning: Both keys can be included in the standard provisioning profile. Contact Acrobits support for details.
Global External Provisioning: The keys can be delivered through the global external provisioning web service, allowing per-user data and periodic refresh.
NetSapiens/Metaswitch connector: Emergency locations are downloaded from the switch automatically.

The service is active only when both emergencyLocations and emergencyNumbers are set and the locations JSON parses successfully. Alerts are shown for misconfiguration.

Condition	Behaviour
Locations set, numbers empty	Alert: no emergency numbers configured
Locations string unparseable	Alert: emergency locations could not be processed
Active but no address matched	Alert: emergency address could not be determined

Public IP Detection ¶

The service needs to know the device public IP address to match against configured locations. It uses two sources.

SIP channel address (primary)¶

When a SIP account registers, the SIP stack learns the mapped address (public IP as seen by the registrar) and the local address (the interface address used for the connection). The mapped address is the primary source for public IP detection.

STUN probe (fallback)¶

If a STUN/TURN server is configured on any enabled SIP account, the service sends a STUN Binding Request in parallel. The server response reveals the public IP independently of SIP registration. This is useful when no account is registered yet, or when the network has changed and re-registration has not completed.

Resolution order ¶

Priority	Source	Used when
1	SIP mapped address	The SIP layer returned a valid public address
2	SIP local address	No mapped address, but the local address itself is a public IP
3	STUN mapped address	Neither SIP source is usable

Candidates from VPN/tunnel interfaces or stale network interfaces are automatically discarded.

Location Matching ¶

The matching algorithm uses three inputs: the current BSSID, the detected public and local IP addresses, and the configured emergency locations. It evaluates candidates in strict priority order and returns the first match.

Priority 1: BSSID match ¶

for each location:
    if location.BSSID == current BSSID  (case-insensitive):
        return location.CivicAddress        -> FOUND

This is the most specific match, identifying an individual access point.

Important

Reading the Wi-Fi BSSID requires Location permission on both platforms: Location Services on macOS (10.15+) and the Location capability on Windows (10+). If not granted, the app prompts the user. Without permission, BSSID matching is skipped and the service falls through to the IP-based tiers.

Priority 2: Public IP + internal subnet match ¶

for each location:
    if location.PublicIP matches detected public IP:
        if location.InternalSubnet contains the local IP:
            track as candidate (prefix size, CivicAddress)

return candidate with the longest prefix     -> FOUND

When multiple locations share the same public IP but differ by subnet (for example different floors behind the same NAT), the longest-prefix match wins.

Priority 3: Public IP match only ¶

for each location:
    if location.PublicIP matches detected public IP
        AND no BSSID or InternalSubnet is configured on this entry:
            return location.CivicAddress     -> FOUND

This tier only considers entries intentionally configured as catch-all (no BSSID, no subnet). Entries with a BSSID or subnet that simply failed to match are not eligible here.

No match ¶

If no tier produces a result, an alert is shown to the user.

Data Flow ¶

All inputs are observed reactively. Any change in network state, SIP registration, STUN result, BSSID, or configuration triggers an immediate re-evaluation.

emergencyLocations ----------.
emergencyNumbers ------------+--> Configuration
SIP registration ------------+--> Public IP
STUN probe ------------------'
Network interface state ---------> Location matching --> Civic address or alert
Wi-Fi BSSID ---------------------^