1. Bandwidth Support Center
  2. 911 Access Support
  3. E911 Dynamic Location Routing

E911 Dynamic Location Routing integration and testing guide

Follow

Larry Reeder

Updated

Click here to find out if your E911 endpoints are compliant with RAY BAUM’s Act

This guide describes how you can provision 911 endpoints in the Bandwidth Dashboard with a request to your account and send SIP requests to Bandwidth to initiate 911 or 933 calls. These instructions are meant to provide the minimum level of technical detail needed to get your developers set up and ready to make a 911 test call that communicates the caller’s location at call time. For more information, check out the References section at the bottom of this guide.

In this guide, we’ll explain how to:

  1. Provision the 911 geolocations (addresses)
  2. Provision the 911 caller endpoints
  3. Make a test call to 933
  4. Make a test call to 911

Note: For 911 Dynamic Location Routing (DLR) API instructions, please see our API guide.

Connection information

The Bandwidth Dashboard has two customer API environments: one for testing, known as interop, and one for production. The base API URLs for these environments are listed in the table below. There's no interop environment for making test calls, but you can validate your call flow by making 933 test calls in production.

Base API URL
Interop https://test.dashboard.bandwidth.com/api
Production https://dashboard.bandwidth.com/api
SIP connection information
SBC IPs Please speak with your Bandwidth Implementation Specialist about your allocated IPs.
Supported Codecs Bandwidth supports the following codecs:
  • G711ulaw, G729a, ILBC (will default to ptime 30)
  • G711ulaw, G729a (will default to ptime 20)
Supported Caller ID Types

Bandwidth supports both From and P-Asserted-Identity SIP header fields to identify the caller. We recommend using only the required From field. However, if you choose to provide the identifier in both fields, P-Asserted-Identity will be used instead of From.

Note: The SIP user=phone parameter must not be used in a caller ID SIP header if the username in the SIP URI isn't a valid phone number. In other words, if you're using an Alternate End User Identifier (AEUI) that contains alphabetic characters, you must not add user=phone to the SIP URI.
Allowed Ports for Media/Audio

If your PBX is protected by a firewall, please verify the manufacturing compliance to confirm the firewall can act as either a SIP ALG or a Back-­to­-Back User Agent (B2BUA). 

Bandwidth uses multiple IP addresses to allow media from its gateways. The following ports are required for the full 2-­way audio:

  • UDP port 5060 – must be opened to support SIP signaling.
  • UDP ports 1024–64,000 – must be opened either statically or dynamically (ALG) to allow for the audio path.
Note: The Location by Value method will require the equivalent TCP ports to be opened.

Geolocations

A geolocation includes a civic address plus any relevant in-building locations, such as the floor, suite, room, or quadrant. It may also be a latitude/longitude (X/Y). Geolocations are used for both emergency service routing and billing/taxation purposes, and must be provisioned before a call is made when you set up caller information in DLR. Latitude/longitude geolocations, however, don’t have to be provisioned before the call is made.

Important: Regardless of whether you’re using Location by Value in PIDF-LO or Location by Reference in the Geolocation header, all geolocations must be prevalidated and added to the Bandwidth Dashboard before you make a call.

Once provisioned, each geolocation has an associated geolocation ID that’s unique across your account. You can provision a geolocation, create a geolocation ID (or have Bandwidth auto-generate one for you), and get a standardized address in the Bandwidth Dashboard or via the Emergency Services API. You can then use geolocation IDs to provision endpoints, either in future API operations or when making 911 Location by Reference calls.

Note: If you're adding a dynamic geolocation via the Bandwidth Dashboard or E911 API with a Geolocation ID that already exists on this account, you'll overwrite the address associated with that existing Geolocation ID instead of adding a new one.

A newly created geolocation or updates to an existing geolocation may take several seconds or several minutes to propagate to the 911 call processing servers. You should not implement a design where a provisioned geolocation is immediately used in a 911 call, since this may result in an inappropriate call routing. The correct way to take a geolocation and use it immediately within a 911 call with no chance of erroneous routing is to convert the geolocation to a latitude-longitude (lat-lon) and use the X/Y routing function. Please see location with a lat-lon in the Geolocation header section for more information.

Endpoints

An endpoint represents the calling party that, depending on mobility, may not initiate an emergency call from a fixed geolocation. Each PIDF-LO enabled endpoint must have a taxation geolocation that will be used for billing/taxation purposes, as well as to identify a geolocation of record for law enforcement. Endpoints can be provisioned using one of the following methods:

  1. Specifying the endpoint attribute set and the geolocation ID of the default address for that endpoint. The address, in this case, has already been provisioned. This is the recommended option.
  2. Specifying the endpoint attribute set and the geolocation ID, plus associated address info. The address in this case hasn't been provisioned yet.
  3. Specifying the endpoint attribute set, plus the associated address info (no geolocation ID specified). The address in this case hasn't been provisioned yet. Once provisioned, a geolocation ID will be returned for that address.

Endpoint attributes

Each endpoint contains a set of attributes consisting of a PIDF-LO enabled flag, a unique Alternate End User Identifier (AEUI) (30 characters or fewer), a caller’s preferred language (English or French), a caller name, and a callback number. For more information about AEUI attributes, please visit our dev docs, click /Accounts, and select /accounts /{accountId} /e911s.

PIDFLOEnabled

Required and needs to be set to true.

Identifier

Required. It could be either the AEUI, which can be used as the caller identifier token in the SIP INVITE to identify the caller in place of a phone number, or the phone number itself. 

The identifier is used to identify the caller in the From and/or P-Asserted-Identity SIP headers. It must contain 10 to 30 characters in the A-Z, a-z, 0-9 range. Special characters aren't supported. This means that if you’re using an E.164 format, you’ll have an 11-digit identifier without the "+" sign in the Bandwidth Dashboard.

Important: The identifier in the SIP INVITE must match exactly what’s in the Bandwidth Dashboard. For instance, if you’re using a 10-digit number in your SIP INVITE, you must use a 10-digit number as the endpoint in the Bandwidth Dashboard. It also must be unique. If you attempt to enter an identifier that’s already used on another Bandwidth Dashboard account, you’ll receive an error. 

CallbackNumber

Required. The callback number, which must follow the 10-digit format in the Bandwidth Dashboard, is a NANPA-valid phone number at which the 911 caller can be reached. The callback number will be delivered to the Public Safety Answering Point (PSAP) at emergency call time so that they can use it if they need to contact the 911 caller after the initial 911 call has ended. The callback number can also be passed in the SIP messaging using the Contact header. See using the Contact header in a 933 call section for details.

PreferredLanguage

Optional. Valid values are en (English) or fr (French). Will default to en if no value is specified.

CallerName

Required. This is the business or caller name associated with the endpoint, which will be delivered to the PSAP. It can contain characters in the A-Z, a-z, 0-9 range, hyphens, or spaces. Special characters aren't supported. Similar to the callback number, the caller name can also be passed in SIP messaging in the Contact header. See using the Contact header in a 933 call section for details.

Provisioning limits and restrictions

Please see the Character Limit column in the table below for the maximum number of characters allowed in each field. Since Bandwidth may have to abbreviate or truncate one or more fields to deliver the information to the PSAP, we recommend not exceeding the number of characters in the Recommended Character Limit column.

Note: The Bandwidth Dashboard fields have different names from what is required in a PIDF-LO element. See the PIDF-LO column for how they should be mapped.

Field Name Required Character Limit Recommended Character Limit PIDF-LO
Number Prefix No 6 characters 4 characters HNP
House Number Yes 45 characters 6 characters HNO
Number Suffix No 6 characters 4 characters HNS
Pre Directional No 2 characters 2 characters PRD
Street Name Yes 200 characters 100 characters RD
Street Suffix No 45 characters 10 characters STS
Post Directional No 2 characters 2 characters POD
Address Line 2 No 60 characters. Our system will automatically abbreviate some common terms like APARTMENT or FLOOR. 20 characters LOC
City Yes 100 characters 100 characters A3
State/Province Yes 2 characters. Must be a valid USPS state code or Canada Post province code. 2 characters A1
Zip/Postal Code Yes 10 characters. Must be a valid USPS zip code or Canada postal code. 10 characters PC
Plus 4 No 10 characters 4 characters  
Country Yes 2 characters. Currently, only the US (United States) and CA (Canada) are supported. 2 characters country
Caller Name No 50 characters. Can contain characters in the A-Z, a-z, 0-9 range, hyphens, or spaces. 32 characters  

Address Line 2

Since PSAPs across the country are generally limited to displaying 60 characters in Address Line 2, Bandwidth enforces a 60-character limit on all addresses being provisioned in that field.

Note: Some PSAPs can only display 20 characters, so we recommend sticking to that limit whenever possible.

If you provision 61 or more characters in the Address Line 2 field, you’ll receive the following error: loc cannot exceed 60 characters. To resolve this error, please edit your Address Line 2 down.

Address Line 2 can be a free-form text, although the typical format is:

    <unit type> <unit num> <unit type> <unit num>...

To fit more information into a smaller space, we try to abbreviate it. Here are some example Address Line 2 inputs and corresponding abbreviated outputs:

Input
Abbreviated output
suite AA
STE AA
building A floor 3 room 7
BLDG A FL 3 RM 7
wharf 7 pier A
WHARF 7 PIER A
Here's a full list of unit-type abbreviations:
Input unit type Abbreviated unit type
APARTMENT
APT
BASEMENT
BSMT
BUILDING
BLDG
DEPARTMENT
DEPT
FLOOR
FL
FRONT
FRNT
HANGAR
HNGR
LOBBY
LBBY
LOT
LOT
LOWER
LOWR
OFFICE
OFC
PENTHOUSE
PH
PIER
PIER
REAR
REAR
ROOM
RM
SIDE
SIDE
SLIP
SLIP
SPACE
SPC
STOP
STOP
SUITE
STE
TRAILER
TRLR
UNIT
UNIT
UPPER
UPPR

Important: If there's a specific value for Address Line 2 provisioned in the Bandwidth Dashboard, that exact value must be passed back to Bandwidth in the LOC value of the attached XML. Otherwise, the addresses won't match exactly and could cause call routing issues. You can also omit the value from Address Line 2 in the Bandwidth Dashboard, and pass that information at the time of the call in the LOC value of the attached XML. This is described in more detail in the Dynamically setting Address Line 2 at call time section.

Making a test call to 933

There's no interop environment for making 911 calls. However, for testing purposes, we provide a service called 933. When you dial 933, this service will read the calling phone number and the provisioned address back to you. This is a good way for you to verify that the system is working and that your number and geolocation are set up for the 911 service without actually calling 911.

To make a 933 test call, initiate a SIP INVITE to one of the Bandwidth SBCs. You must put the exact endpoint identifier created in the Bandwidth Dashboard into the From or the P-Asserted-Identity header field. We recommend using only the required From field. However, if you choose to provide the identifier in both fields, P-Asserted-Identity will be used instead of From. In the examples below, we'll assume your endpoint ID is 9zdRwdQqYV88tX and you're sending the SIP INVITE to Bandwidth SBC IP 124.124.124.124.  

You can initiate a PIDF-LO call using:

  1. Location by Reference
  2. Location by Value
  3. Location with a lat-lon in a Geolocation header
  4. Location with a lat-lon in a PIDF-LO attachment

Note: RFC 6442 defines the semantics of the Geolocation-Routing header. Bandwidth will ignore the value of this header. If you have SIP intermediaries between you and Bandwidth that would use the PIDF-LO values to make SIP routing decisions, set the value of this header to no. This option is shown in the examples below. Otherwise, don’t include the header. 

Location by Reference

In Location by Reference, you pass a short reference to a stored geolocation in the SIP INVITE. This method is recommended over other options for the following reasons:

  • There’s no risk of a mismatch between the version of the standardized address in the Bandwidth databases and your own database.
  • The SIP INVITE is much smaller, allowing UDP to be used without the risk of packet fragmentation.

When calling with a location reference, add the Geolocation header that contains a URL with the location reference. The URL should follow this format:

Geolocation: <https://emergency.bandwidth.com/locations/{account_number}/{location_reference}>

You would need to replace {account_number} with your own Bandwidth Dashboard account number, and {location_reference} with the reference ID of a previously registered location.     

Let’s say your Bandwidth Dashboard account number is 123456 and the user associated with an endpoint ID 9zdRwdQqYV88tX makes a 933 call at a location CorpOffice5thFloor. The following would need to be specified at call time:

Bandwidth Account Number 123456
Caller's Location CorpOffice5thFloor

The URL would need to be formatted like this:

Geolocation: <https://emergency.bandwidth.com/locations/123456/CorpOffice5thFloor>

And the SIP INVITE would then look like this:

INVITE sip:933@124.124.124.124:5060;transport=udp SIP/2.0
From: <sip:9zdRwdQqYV88tX@123.123.123.123>;tag=1901e743-13c4-57acf3bf-10bd778f-1e0db8d0.
To: <sip:933@124.124.124.124:5060>
Call-ID: CXC-1956-7052b170-1901e743-13c4-57acf3bf-10bd778e-3a245182
CSeq: 1 INVITE
Contact: Jane Smith <sip:13215551234@example.com>
Via: SIP/2.0/UDP 123.123.123.124:5060;branch=z9hG4bK-5c189-57acf3bf-10bd778f-3b0740c9
Max-Forwards: 63
P-Asserted-Identity: <sip:9zdRwdQqYV88tX@sbc.example.com:5060>
User-Agent: SomeUserAgent
Geolocation: <https://emergency.bandwidth.com/locations/123456/CorpOffice5thFloor>
Geolocation-Routing: no
Accept: application/sdp, application/pidf+xml
Content-Type: application/sdp
Content-Length: 275
v=0
o=- 1168077819 1168077819 IN IP4 111.222.123.123
s=Customer Media Gateway
c=IN IP4 234.234.234.234
t=2208988800 2208988800
m=audio 12560 RTP/AVP 0 101
a=rtpmap:0 PCMU/8000
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-16
a=ptime:20
a=sendrecv

Note: There's no PIDF element in this SIP INVITE. Instead, the location of the caller is communicated in the Geolocation header.

Using Location by Reference with lat-lon

Let’s assume you’re making an emergency call from a mobile device near one of your registered geolocations, for example, your apartment building. If you’d like Bandwidth to use the "best" value for routing your call, which in this case is the pre-registered location of the apartment building rather than the lat-lon, you can do this by passing the geolocation reference, the lat-lon pair, and an optional radius. If not provided, the value of this optional radius is 50 meters.

If the lat-lon pair is close enough to the geolocation, as defined by the radius, Bandwidth will use that geolocation as the address for call routing and PSAP purposes. If the lat-lon pair is outside of the radius surrounding the geolocation, the lat-lon will be used as the location for call routing.   

For example, in the SIP INVITE initiating the call below, the caller is mostly associated with the geolocation "MyHouse", but you've determined they’re at lat-lon 34.407, -105.883. You'd like Bandwidth to use the registered geolocation unless the caller's actual location, as determined by the lat-lon pair, is more than 100 meters away. You can tell Bandwidth to do this by passing all this information in the Geolocation URL.

INVITE sip:911@254.253.252.251:5060;transport=udp SIP/2.0
From: <sip:15554211234@192.168.3.194>;tag=1901e743-13c4-57acf3bf-10bd778f-1e0db8d0
To: <sip:911@254.253.252.251:5060>
Call-ID: CXC-1956-7052b170-1901e743-13c4-57acf3bf-10bd778e-3a245182
CSeq: 1 INVITE
Via: SIP/2.0/UDP 192.168.3.194:5060;branch=z9hG4bK-5c189-57acf3bf-10bd778f-3b0740c9
Max-Forwards: 63
P-Asserted-Identity: <sip:1555444333@example.com:5060>
User-Agent: Acme
Geolocation: <https://emergency.bandwidth.com/locations/customer1234/MyHouse?lat=34.407&lon=-105.883&r=100>
Geolocation-Routing: no
Accept: application/sdp
Content-Type: application/sdp
Content-Length: 275

v=0
o=- 1168077819 1168077819 IN IP4 111.222.123.123
s=Customer Media Gateway
c=IN IP4 54.172.60.57
t=2208988800 2208988800
m=audio 12560 RTP/AVP 0 101
a=rtpmap:0 PCMU/8000
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-16
a=ptime:20
a=sendrecv

Location by Value

In Location by Value, the geolocation is passed by an XML attachment in the SIP INVITE. Although Location by Reference is the recommended way to send geolocation with the call, you can also use the Location by Value method which lets you insert the standardized value of the location in the PIDF mime attachment to the SIP INVITE. 

You can get the standardized value of the location in the Bandwidth Dashboard. For API information, see the Checking Address Validation And Getting The Standardized Address section in our API guide.

Important: Ignoring case, the standardized address you pass to Bandwidth in the PIDF mime attachment must match exactly what Bandwidth returns when the address is validated in the Bandwidth Dashboard or the API call. If Bandwidth doesn’t find an exact match, the call will be routed to the emergency call center as an unprovisioned call. Also, adding the PIDF attachment to the SIP INVITE is likely to make the SIP INVITE too large to fit into a UDP packet.. Therefore, if you're sending location as a value, you must use TCP.

Let’s assume our example address is 900 Main Campus Drive, Suite 500, Raleigh, NC, 27606 and it has been standardized to this:

House Number Street Name Street Type Address Line 2 City State Zip Country
900 MAIN CAMPUS DR SUITE 500 RALEIGH NC 27606 us

Then, assuming the call is initiated by the same caller (Jane Smith) with the same callback number, the SIP INVITE in the location reference example call above would look like this:

INVITE sip:933@124.124.124.124:5060;transport=tcp SIP/2.0
From: <sip:9zdRwdQqYV88tX@123.123.123.123>;tag=1901e743-13c4-57acf3bf-10bd778f-1e0db8d0
To: <sip:933@124.124.124.124:5060>
Call-ID: CXC-1956-7052b170-1901e743-13c4-57acf3bf-10bd778e-3a245182
CSeq: 1 INVITE
Contact: Jane Smith <13215551234@example.com>
Via: SIP/2.0/TCP 123.123.123.124:5060;branch=z9hG4bK-5c189-57acf3bf-10bd778f-3b0740c9
Max-Forwards: 63
P-Asserted-Identity: <sip:9zdRwdQqYV88tX@sbc.example.com:5060>
User-Agent: BandwidthVoice
Geolocation: <cid:pidf-attachment@somewhere.example.com>
Geolocation-Routing: no
Accept: application/sdp, application/pidf+xml
Content-Type: multipart/mixed;boundary=unique-boundarystring
Content-Length: 1296

--unique-boundarystring

Content-Type: application/sdp
v=0
o=root 877375136 877375136 IN IP4 192.168.8.84
s=Asterisk PBX 11.25.1
c=IN IP4 192.168.8.84
t=0 0
m=audio 19830 RTP/AVP 0 97 101
a=rtpmap:0 PCMU/8000
a=rtpmap:97 iLBC/8000
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-16
a=ptime:20
a=sendrecv

--unique-boundarystring

Content-Type: application/pidf+xml
Content-ID: <pidf-attachment@somewhere.example.com>
<?xml version="1.0" encoding="UTF-8"?>
<presence 
xmlns="urn:ietf:params:xml:ns:pidf" 
xmlns:gp="urn:ietf:params:xml:ns:pidf:geopriv10"
xmlns:gbp="urn:ietf:params:xml:ns:pidf:geopriv10:basicPolicy"
xmlns:ca="urn:ietf:params:xml:ns:pidf:geopriv10:civicAddr"
xmlns:gml="http://www.opengis.net/gml"
xmlns:dm="urn:ietf:params:xml:ns:pidf:data-model"
entity="pres:9zdRwdQqYV88tX@123.123.123.123">
<dm:device id="target123-1">
 <gp:geopriv>
  <gp:location-info>
   <ca:civicAddress>
    <ca:country>us</ca:country>
    <ca:HNO>900</ca:HNO>
    <ca:RD>MAIN CAMPUS</ca:RD>
    <ca:STS>DR</ca:STS>
    <ca:A1>NC</ca:A1>
    <ca:A3>RALEIGH</ca:A3>
    <ca:LOC>Suite 500</ca:LOC> 
    <ca:NAM>Bandwidth</ca:NAM>
    <ca:PC>27606</ca:PC>
    </ca:civicAddress>
   </gp:location-info>
  </gp:geopriv>
 </dm:device>
</presence>
--unique-boundarystring--

Please note the following differences compared to the Location by Reference example:

  • The content of the SIP message is broken into two attachments: one for the SDP and one for the PIDF-LO element.
  • The PIDF-LO element contains the fields corresponding to the standardized address. See the table in the provisioning limits and restrictions section for a description of how to map Bandwidth Dashboard Address fields to PIDF-LO fields. The XML has been indented in the example for readability, but we recommend you remove unnecessary whitespace from the XML to reduce the message size.  
  • The caller name is placed in the NAM field of the PIDF-LO element.
  • The Geolocation header HTTP URL is replaced with a CID URL (see RFC 2392) that refers to the Content-ID in the PIDF part of the MIME attachment.

Dynamically setting Address Line 2 at call time

Since the dispatch location doesn’t change for high-rise buildings, you can provision one address without the Address Line 2 element as the "front door" of the building, and then send the location element in the SIP INVITE to indicate where the caller is in the building. This approach allows you to tell Bandwidth the building’s location in the call routing phase, without defining all the units in the building.

Setting Address Line 2 when using Location by Reference

As described previously in the Location By Reference section, you can pass a location identifier in the SIP Geolocation header to refer to a Geolocation stored in Bandwidth's database. You can also dynamically pass Address Line 2 as a loc parameter in the URL. Here's the format for the Geolocation URL if you want to do that (assuming your account ID is 123456):

Geolocation: <https://emergency.bandwidth.com/locations/123456/{LOCATION_REFERENCE}?loc={URL_ENCODED_LOCATION}>

For example, if you created a geolocation for your San Jose office with an identifier of SanJoseOffice, and someone called from Suite #20, the following Geolocation header could be used to pass "STE #20" as the location:

Geolocation: <https://emergency.bandwidth.com/locations/123456/SanJoseOffice?loc=STE%20%2320>

Note: The URL must be encoded using standard URL encoding.

When the loc parameter is passed as in the Geolocation URL with a valid location identifier, Bandwidth will pull the geolocation matching the location identifier and replace the value that location had for Address Line 2 with the value you passed with the loc parameter.

Setting Address Line 2 when using Location by Value

If you're using Location by Value, you can also pass Address Line 2 at call time. Given a Location by Value with Address Line 2 in the LOC PIDF-LO field, Bandwidth will first try to find an exact match for the address in the location records in your account, including an exact match for the value of Address Line 2. If we find an exact match, we'll use the matching location for the 911 call.  

If an exact match can't be found, Bandwidth will then try to find an exact match where the Address Line 2 value is empty but all other location fields match. If we find an exact match, but with an empty Address Line 2, we'll use that record. We'll plug the value you passed in the LOC field into the record that we send to the PSAP.  

Finally, if Bandwidth can't find a location record where the Address Line 2 field is empty, but all other fields match exactly, we'll send the call to the ECC.

For example, if you have a large organization with many offices at 1000 Water Street, Des Moines, IA, 50309, you can just add that as geolocation in the Bandwidth Dashboard without an Address Line 2 field. When you initiate the SIP INVITE, add the suite the caller is in to the LOC field PIDF element, and we'll send the suite information to the PSAP:

<presence...
   <ca:civicAddress>
   <ca:HNO>1000</ca:HNO>
   <ca:RD>WATER</ca:RD>
   <ca:STS>ST</ca:STS>
   <ca:A3>DES MOINES</ca:A3>
   <ca:A1>IA</ca:A1>
   <ca:LOC>Suite #180</ca:LOC>
   <ca:PC>50309</ca:PC>
   <ca:country>us</ca:country>
  </ca:civicAddress>
  ... 
  </presence>

Location with a lat-lon in the Geolocation header

This option lets you include the geometric coordinates of the caller in the Geolocation header of the SIP INVITE. Bandwidth accepts latitude-longitude (lat-lon) for the coordinates of the caller. The lat-lon must be formatted as decimal degrees, using the WGS84 coordinate system.

The URL should follow this format:

Geolocation: <https://emergency.bandwidth.com/locations/{account_number}?lat={latitude}&lon={longitude}>

You'd need to replace {account_number} with your own Bandwidth Dashboard account number, and {latitude} and {longitude} with the latitude and longitude of the caller.

Let’s say your Bandwidth Dashboard account number is 123456 and the user associated with an endpoint ID 9zdRwdQqYV88tX makes a 933 call in Jefferson City, MO. The following would need to be specified at call time:

Bandwidth Account Number 123456
Latitude 38.573313
Longitude -92.177170

The URL would need to be formatted like this:

Geolocation: <https://emergency.bandwidth.com/locations/123456?lat=38.573313&lon=-92.177170>

And the SIP INVITE would then look like this:

INVITE sip:933@124.124.124.124:5060;transport=udp SIP/2.0
From: <sip:9zdRwdQqYV88tX@123.123.123.123>;tag=1901e743-13c4-57acf3bf-10bd778f-1e0db8d0.
To: <sip:933@124.124.124.124:5060>
Call-ID: CXC-1956-7052b170-1901e743-13c4-57acf3bf-10bd778e-3a245182
CSeq: 1 INVITE
Contact: Jane Smith <sip:13215551234@example.com>
Via: SIP/2.0/UDP 123.123.123.124:5060;branch=z9hG4bK-5c189-57acf3bf-10bd778f-3b0740c9
Max-Forwards: 63
P-Asserted-Identity: <sip:9zdRwdQqYV88tX@sbc.example.com:5060>
User-Agent: SomeUserAgent
Geolocation: <https://emergency.bandwidth.com/locations/123456?lat=38.573313&lon=-92.177170>
Geolocation-Routing: no
Accept: application/sdp, application/pidf+xml
Content-Type: application/sdp
Content-Length: 275

v=0
o=- 1168077819 1168077819 IN IP4 111.222.123.123
s=Customer Media Gateway
c=IN IP4 234.234.234.234
t=2208988800 2208988800
m=audio 12560 RTP/AVP 0 101
a=rtpmap:0 PCMU/8000
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-16
a=ptime:20
a=sendrecv

Location with a lat-lon in a PIDF-LO attachment

This final option lets you send the geometric coordinates of the caller in a PIDF-LO gml:Point element. Similar to the previous option, the latitude and longitude must be formatted as decimal degrees, using the WGS84 coordinate system.   

Note: As with Location by Value, adding the lat-lon in a PIDF attachment to the SIP INVITE will likely make the SIP INVITE too large to fit into a UDP packet. Therefore, if you're sending lat-lon in PIDF-LO, you must use TCP. 

Here’s the same example 933 SIP INVITE for a caller in Jefferson City, MO, this time with PIDF-LO:

INVITE sip:933@124.124.124.124:5060;transport=tcp SIP/2.0
From: <sip:9zdRwdQqYV88tX@123.123.123.123>;tag=1901e743-13c4-57acf3bf-10bd778f-1e0db8d0
To: <sip:933@124.124.124.124:5060>
Call-ID: CXC-1956-7052b170-1901e743-13c4-57acf3bf-10bd778e-3a245182
CSeq: 1 INVITE
Contact: Jane Smith <sip:13215551234@example.com>
Via: SIP/2.0/TCP 192.168.3.194:5060;branch=z9hG4bK-5c189-57acf3bf-10bd778f-3b0740c9
Max-Forwards: 63
P-Asserted-Identity: <sip:9zdRwdQqYV88tX@sbc.example.com:5060>
User-Agent: BandwidthVoice
Geolocation: <cid:pidf-attachment@somewhere.example.com>
Geolocation-Routing: no
Accept: application/sdp, application/pidf+xml
Content-Type: multipart/mixed;boundary=unique-boundarystring
Content-Length: 1054

--unique-boundarystring

Content-Type: application/sdp
v=0
o=root 877375136 877375136 IN IP4 192.168.8.84
s=Asterisk PBX 11.25.1
c=IN IP4 192.168.8.84
t=0 0
m=audio 19830 RTP/AVP 0 97 101
a=rtpmap:0 PCMU/8000
a=rtpmap:97 iLBC/8000
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-16
a=ptime:20
a=sendrecv

--unique-boundarystring

Content-Type: application/pidf+xml
Content-ID: <pidf-attachment@somewhere.example.com>
<?xml version="1.0" encoding="UTF-8"?>
<presence xmlns="urn:ietf:params:xml:ns:pidf"
 xmlns:dm="urn:ietf:params:xml:ns:pidf:data-model"
 xmlns:gp="urn:ietf:params:xml:ns:pidf:geopriv10"
 xmlns:cl="urn:ietf:params:xml:ns:pidf:geopriv10:civicAddr"
 xmlns:gml="http://www.opengis.net/gml"
 entity="pres:point2d@example.com">
 <dm:device id="point2d">
  <gp:geopriv>
   <gp:location-info>
    <gml:Point srsName="urn:ogc:def:crs:EPSG::4326">
     <gml:pos>38.573313 -92.177170</gml:pos>
    </gml:Point>
   </gp:location-info>
  </gp:geopriv>
 </dm:device>
</presence>
--unique-boundarystring--

Using the Contact header in a 933 call

If you can’t set up your caller name or callback number for the caller when you add your endpoint to Bandwidth's systems, but do have that information at 933 (or 911) call time, your account can be configured to allow you to pass that information in a Contact header when you send us the call. The Contact header should follow this format:

Contact: {caller_name} <sip:{callback_number}.domain>

Let’s say you determine at call time that the call has been initiated by a caller Jane Smith and callback number 13215551234. The following would need to be specified at call time:

Caller Name Jane Smith
Callback Number 13215551234

The Contact header in the SIP INVITE would need to be formatted like this:

Contact: Jane Smith <sip:13215551234@example.com>

Bandwidth will ignore the domain name in the SIP URI and only use the username portion. By default, the value of the Contact header will be ignored for 911 calls. If you need it, please contact your Bandwidth Implementation Specialist to set up your account to pass the caller name and callback number at call time.

Failover testing

This test will validate your system’s ability to successfully redirect failed calls to your secondary route.

During this test, we'll provide you with a specific Automatic Number Identification (ANI) to dial from and will simulate a scenario in which your 911 call is sent to your primary route and will then fail with a SIP 410 response. When you receive a 410, you should send the SIP INVITE to the alternate SBC.

Handling SBC failures

In the event of a live SBC failure, the Bandwidth SBC may respond with a 4xx, 5xx, or 6xx SIP status, or won't respond at all (in the case of a hard-down situation). The non-response or the error message must be handled appropriately on your side to fail over to the other functioning SBC.

Note: The one exception is a 487 response, which is a normal response to you sending a CANCEL for the call. If you receive a 487, do not fail over to the alternate SBC.

Making a test call to 911

The test call to 911 has the same parameters and flow as the 933 call, with the exception that the username (DNIS) in the SIP URI must be 911 instead of 933. Before making a 911 call, verify that you have the full duplex audio enabled and that the PSAP can reach the callback number you're providing. For more information, check out our tips for a successful 911 test call.

Note: If your account is in testing, you can send the call without connecting to the PSAP. Your call will be rejected, but Bandwidth can verify that your SIP request was correct.

References

This guide explained how to set up a number for DLR with enough details to define a basic successful flow. However, you’ll need the following information to build a robust system: 

Introduction to the Bandwidth Dashboard phone numbers API

https://dev.bandwidth.com/numbers/about.html
API docs that include detailed descriptions of the Bandwidth Dashboard API calls, example parameters and XML payloads, as well as responses to requests.

https://dev.bandwidth.com/numbers/apiReference.html
List of all possible E911 errors that can be returned in the response payload either from a POST request or a GET request on a specific E911 order.

https://dev.bandwidth.com/numbers/error.html

Questions? Please open a ticket with your Bandwidth Support Team or hit us up at (855) 864-7776!

Article is closed for comments.