9-1-1 Dynamic Location Routing Integration

Follow

Carissa Matton

Updated

Introduction

Connection Information

Provision Dynamic Location Routing Information

Locations

Example POST payload to create a location

Checking address validation and getting the standardized address

Example GET addresses response

Endpoints

Endpoint Attributes

Example payload - Creating an endpoint with an existing location

Example endpoint provisioning success response

Make a Test Call to 9-3-3

Notes on the Geolocation-routing header

Making a 9-3-3 call with a location reference

Making a 9-3-3 call with a location value

Making a 9-3-3 call with a lat-lng in the geolocation header

Making a 9-3-3 call with a lat-lon

Using the Contact header in a 9-3-3 call

Failover

Handling SBC Failures

Make a Test Call to 9-1-1 

Cleanup

References

Appendix A - Mapping Bandwidth Dashboard Address Elements to PIDF-LO 

 

Introduction

This integration document describes how to provision a 9-1-1 endpoint in Bandwidth Dashboard with a request to your account, as well as how you can send SIP requests to Bandwidth to initiate 9-1-1 or 9-3-3 calls.  The intent of this document is to provide the minimum level of technical details needed to get your developers set up and making a 9-1-1 test call which communicates the caller’s location at call time. For more details, refer to the References section at the bottom of this document.

The following steps are described in this document:

  1. Provision the 9-1-1 locations (addresses)
  2. Provision the 9-1-1 caller endpoints
  3. Make a test call to 9-3-3
  4. Make a test call to 9-1-1

Connection Information

Bandwidth Dashboard has two customer environments, one for testing (also known as Interop) and one for production.  The base API URLs for these environments is shown in the table below.

Base API URL

Production

https://dashboard.bandwidth.com/api

SIP Connection Information

SBC IPs

Please reach out to your Implementation Specialist at Bandwidth about your allocated IPs.

Supported Codecs

The following codecs are supported by Bandwidth:

  • G711ulaw, G729a, ILBC (will default to ptime 30)
  • G711ulaw, G729a  (will default to ptime 20)

Supported Caller ID Types

The following SIP header fields are supported to identify the caller:

  • From field – default option for endpoint identifier
  • Remote-Party-Id – secondary option
  • P­-Asserted-Identity – supported option

NOTE: The SIP user=phone parameter must not be used if a caller ID sip header if the username in the SIP URI is not a valid phone number.  That is, if you are using an Alternate End User Identifier that contains alphabetic characters, you must not add user=phone to the SIP URI.

Allowed Ports for Media/Audio

If a customer PBX is protected by a firewall, manufacturer compliance will need to be verified that the firewall has the ability to act as either a SIP ALG or a Back-­to­‐Back User Agent (B2BUA).  The following ports are required to allow for 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 audio path.
  • Bandwidth uses multiple IP addresses to allow media from its gateways

NOTE:  Location-by-value will require the equivalent TCP ports to be opened

 

Provision Dynamic Location Routing Information

When setting up caller information in Dynamic Location Routing, addresses are provisioned up front.  This is also known as adding locations (addresses) to your location pool. These addresses are assumed to be used in future 9-1-1 calls. Once provisioned, each address has an associated location id that is unique across your account. The location IDs can be used in subsequent API requests to provision endpoints. Endpoints represent the calling party, and are provisioned using a set of information representing an Alternate End User Identifier (AEUI).

LOCATIONS

Locations can be independently provisioned in a couple of ways. You can provision a location and have Bandwidth create the location id for you, or you can provide your own location ID. The examples below show the case where you provide your own location ID, which you will then use later to refer to the location, either in future API operations, or when making 9-1-1 location-by-reference calls.

API Operation endpoint: POST {Base API URL}/accounts/{accountId}/e911s

This method allows you to assign your own identifier to the address rather than letting Bandwidth Dashboard assigning one for you. The location id you provide must be unique across your account. The location id has the following limits:  it can only contain characters in the range [A-Za-z0-9], and it cannot be any larger than 32 characters.

Example POST payload to create a location:

<E911Order>

   <AdditionalAddresses>

     <Address>

       <LocationId>CorpOffice5thFloor</LocationId>

<HouseNumber>900</HouseNumber>

       <HouseSuffix />

       <PreDirectional />

       <StreetName>Main Campus</StreetName>

       <StreetSuffix>Drive</StreetSuffix>

       <PostDirectional />

       <AddressLine2>Suite 500</AddressLine2>

       <City>Raleigh</City>

       <StateCode>NC</StateCode>

       <Zip>27606</Zip>

       <PlusFour/>

       <County/>

       <Country>US</Country>

   </Address>

   ...

</E911Order>

 

Checking address validation and getting the standardized address

Address validation happens asynchronously, and usually takes just a few seconds.  Check order status to verify address validation, using this operation:

GET {Base API URL}/accounts/{accountId}/e911s/{orderId}

If you don’t want to poll for order status, you can set up an HTTP endpoint on your own servers and subscribe to order status changes. Once that’s done, Bandwidth will send order events to the endpoint you specify. This removes the pain of rechecking an order to see if it’s been updated, although it does require you to run a web service.  See “/accounts /{accountId}/subscriptions” on the online documentation for more info.  

For any addresses that were determined to be invalid, please refer to the ErrorList section in the response body of the GET request. If no ErrorList is present, then all addresses are valid in the order. For any valid address, Bandwidth may adjust the address you passed and convert it to a standardized version. If this happens, the response body in the GET request will indicate for each address whether it was adjusted or not.  If you expect to pass the address as location-by-value in the SIP INVITE (see Making a 9-3-3 call with a location value below), you must use Bandwidth’s version of the standardized address in the SIP invite.  

 

If the order has processed successfully,  then check the adjusted address with this call:

GET {Base API URL}/accounts/{accountId}/addresses?e911locationid={locationid}

Use the fields returned from this call to submit locations-by-value in a PIDF-LO 9-1-1 or 9-3-3 call. Here’s an example response for the order submitted above to create a new location:

 

Example GET addresses response

<AddressesResponse>

   <Addresses>

       <Address>

           <HouseNumber>900</HouseNumber>

           <HouseSuffix/>

           <PreDirectional/>

           <StreetName>Main Campus</StreetName>

           <StreetSuffix>Dr</StreetSuffix>

           <PostDirectional/>

           <AddressLine2>Suite 400</AddressLine2>

           <City>Raleigh</City>

           <StateCode>NC</StateCode>

           <Zip>27606</Zip>

           <PlusFour/>

           <County/>

           <Country>United States</Country>

           <AddressType>E911</AddressType>

           <LocationId>CorpOffice5thFloor</LocationId>

      </Address>

   </Addresses>

</AddressesResponse>

 

ENDPOINTS

An endpoint is a representation of the calling party, which, depending on mobility, may not initiate an emergency call from a fixed location.   Each endpoint contains a set of Alternate End User Identifier (AEUI) attributes consisting of a PIDF-LO enabled flag, a unique identifier (30 characters or less), the caller’s preferred language (en or fr), caller name, and callback number.  Also, a default location is required for each PIDF-LO enabled endpoint. This default location will be used for taxation purposes, and to identify a location of record for law enforcement. Provisioning of endpoints can be accomplished using one of the following methods:

  1. Specifying the endpoint attribute set and a location 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 location id plus associated address info.  The address in this case has not yet been provisioned.
  3. Specifying the endpoint attribute set plus the associated address info (no location id specified).  The address in this case has not yet been provisioned. Once provisioned a location id will be returned for that address.

The examples below show option #1 - creating an endpoint when the location has already been provisioned.

 

Endpoint Attributes

PIDFLOEnabled - Required.  Needs to be set to “true”.

Identifier - Required.  The alternate end user identifier can be used as the caller identifier token in the SIP INVITE to identify the caller in place of a phone number. It’s used to identify the caller in the “From” and/or “P-Asserted-Identity” SIP headers. It must be between 10 and 30 characters, inclusive. It can contain any characters in the range [A-Za-z0-9]. However, to avoid the possibility of confusion with dialed numbers in international dialing plans, it MUST contain at least one character in the range [A-Za-z]. The identifier must be unique - you cannot reuse an identifier that is being used elsewhere in your account.

CallbackNumber - Required. Callback number is the NANPA-valid phone number at which the 9-1-1 caller can be reached. The callback number will be delivered to the PSAP at emergency call time so they can use it if they need to contact the 9-1-1 caller after the initial 9-1-1 call has ended. The callback number can also be passed in the SIP messaging, in the Contact header - see section “Using the Contact header in a 9-3-3 call” for details.

PreferredLanguage - Optional. Valid values are “en” (English) or “fr” (French).  Defaults to “en” if value not specified.

CallerName - Required. A business or caller name to associate with the endpoint. This name will be delivered to the PSAP. Similar to the callback number, the caller name can also be passed in SIP messaging in the Contact header. See section “Using the Contact header in a 9-3-3 call” for details.

API Operation Endpoint: POST {Base API URL}/accounts/{accountId}/e911s

 

Example payload - Creating an endpoint with an existing location

In this example, the location identified by “CorpOffice5thFloor” has already been added to Bandwidth Dashboard, and is being associated to the endpoint.

<E911Order>

   <CustomerOrderId>CustomOrderId1</CustomerOrderId>

   <AlternateEndUserIdentifiers>

       <AlternateEndUserIdentifier>

            <PIDFLOEnabled>true</PIDFLOEnabled>

            <Identifier>9zdRwdQqZW99uYr</Identifier>

            <CallbackNumber>5555561234</CallbackNumber>

            <CallerName>5th Floor Conference Phone</CallerName>

            <PreferredLanguage>en</PreferredLanguage>

            <LocationId>CorpOffice5thFloor</LocationId>

       </AlternateEndUserIdentifier>

   </AlternateEndUserIdentifiers>

</E911Order>

Upon successful submission, a POST request will return a “HTTP 201 Created” with a response body indicating a status of RECEIVED. Additionally a Location header will be returned with a link to the created order, which can be used to obtain subsequent status, or given the order id, you can make the following request to get the order status:

GET {Base API URL}/accounts/{accountId}/e911s/{orderId}

 

Which, for a successful order will return something like this:

Example endpoint provisioning success response

<E911OrderResponse>

       <E911Order>

   <OrderCreateDate>2017-05-01T15:00:00.000Z</OrderCreateDate>

   <AccountId>123</AccountId>

   <CreatedByUser>api_user</CreatedByUser>

   <OrderId>42d06090-a54f-4469-bb55-97eb5c0f3fea</OrderId>

   <LastModifiedDate>2017-05-01T15:00:01.000Z</LastModifiedDate>

   <CustomerOrderId>CustomOrderId1</CustomerOrderId>

   <ProcessingStatus>RECEIVED</ProcessingStatus>

   <AlternateEndUserIdentifiers>

       <AlternateEndUserIdentifier>

            <PIDFLOEnabled>true</PIDFLOEnabled>

            <Identifier>9zdRwdQqZW99uYr</Identifier>

            <CallbackNumber>5555561234</CallbackNumber>

            <CallerName>5th Floor Conference Phone</CallerName>

            <PreferredLanguage>en</PreferredLanguage>

            <Address>

               <HouseNumber>900</HouseNumber>

               <HouseSuffix />

               <PreDirectional />

               <StreetName>Main Campus</StreetName>

               <StreetSuffix>Dr</StreetSuffix>

               <PostDirectional />

               <AddressLine2>Suite 200</AddressLine2>

               <City>Raleigh</City>

               <StateCode>NC</StateCode>

               <Zip>27606</Zip>

               <PlusFour />

               <County />

               <Country>US</Country>

             </Address>

       </AlternateEndUserIdentifier>

   </AlternateEndUserIdentifiers>

</E911Order>

<E911OrderResponse>

 

Unsuccessful requests will return an HTTP 400 Bad Request with a response payload indicating the error, along with an error description and code.

 

Example endpoint provisioning error response on POST request

<E911OrderResponse>

       <E911Order>

   <OrderCreateDate>2017-05-01T15:00:00.000Z</OrderCreateDate>

   <AccountId>123</AccountId>

   <CreatedByUser>api_user</CreatedByUser>

   <OrderId>42d06090-a54f-4469-bb55-97eb5c0f3fea</OrderId>

   <LastModifiedDate>2017-05-01T15:00:01.000Z</LastModifiedDate>

   <CustomerOrderId>CustomOrderId1</CustomerOrderId>

   <ProcessingStatus>FAILED</ProcessingStatus>

   <AlternateEndUserIdentifiers>

       <AlternateEndUserIdentifier>

            <PIDFLOEnabled>true</PIDFLOEnabled>

            <Identifier>9zdRwdQqZW99uYr</Identifier>

            <CallbackNumber>5555561234</CallbackNumber>

            <CallerName>5th Floor Conference Phone</CallerName>

            <PreferredLanguage>en</PreferredLanguage>

            <Address>

               <HouseNumber>900</HouseNumber>

               <HouseSuffix />

               <PreDirectional />

               <StreetName>Main Campus</StreetName>

               <StreetSuffix>Dr</StreetSuffix>

               <PostDirectional />

               <AddressLine2>Suite 200</AddressLine2>

               <City>Raleigh</City>

               <StateCode>NC</StateCode>

               <Zip>27606</Zip>

               <PlusFour />

               <County />

               <Country>US</Country>

             </Address>

       </AlternateEndUserIdentifier>

   </AlternateEndUserIdentifiers>

<ErrorList>

   <AEUIError>

<AlternateEndUserIdentifiers>

       <AlternateEndUserIdentifier>

            <PIDFLOEnabled>true</PIDFLOEnabled>

            <Identifier>9zdRwdQqZW99uYr</Identifier>

            <CallbackNumber>5555561234</CallbackNumber>

            <CallerName>5th Floor Conference Phone</CallerName>

            <PreferredLanguage>en</PreferredLanguage>

            <Address>

               <HouseNumber>900</HouseNumber>

               <HouseSuffix />

               <PreDirectional />

               <StreetName>Main Campus</StreetName>

               <StreetSuffix>Dr</StreetSuffix>

               <PostDirectional />

               <AddressLine2>Suite 200</AddressLine2>

               <City>Raleigh</City>

               <StateCode>NC</StateCode>

               <Zip>27606</Zip>

               <PlusFour />

               <County />

               <Country>US</Country>

             </Address>

       </AlternateEndUserIdentifier>

   </AlternateEndUserIdentifiers>

   <Code>8033</Code>

   <Description>This order is a duplicate of another E911 request(orderId=’4901d3bc-b5a6-401f-aea2-f8e76023faca’), and will be canceled. The state of the E911 service will be reflected in the competing order.</Description>

     </AEUIError>

</ErrorList>

</E911Order>

<E911OrderResponse>

 

Make a test call to 9-3-3

There is no testing environment for making 9-1-1 calls.  However, for testing purposes, Bandwidth provides a service called “9-3-3”.  When users dial 9-3-3, this Bandwidth service will read their calling phone number and the provided address back to the caller.  This is a good way for callers to verify the system is working and that their number and location are setup for 9-1-1 service without actually calling 9-1-1.

To make a 9-3-3 test call, initiate a SIP INVITE to one of the Bandwidth SBCs. You must put the endpoint  identifier in the P-Asserted-Identity, Remote-Party-Id, or From header. The examples below assume you are sending the SIP INVITE to Bandwidth SBC IP 124.124.124.124.

There are three ways to initiate a PIDF-LO call:

  1. Pass the location reference of a location you’ve already registered.
  2. Pass the standardized location value in a PIDF mime attachment to the SIP invite.
  3. Pass the lat-lon of the caller in a PIDF mime attachment to the SIP invite.

 

Option #1 (location-by-reference) is recommended over option #2 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 risk of packet fragmentation.

 

However, it does have a limitation in that it requires all potential caller locations to be pre-provisioned.

 

NOTES ON THE GEOLOCATION-ROUTING HEADER

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 examples below. Otherwise, don’t include the header.

 

MAKING A 9-3-3 CALL WITH A LOCATION REFERENCE

When calling with a location reference, add a header “Geolocation”  which contains a URL with the location reference. The URL should follow the format:

Geolocation: <https://emergency.bandwidth.com/locations/123456/{LOCATION_REFERENCE}>

Replace the 123456 with your own Bandwidth Dashboard account number, and replace {LOCATION_REFERENCE} with the reference id of a previously registered location.     

Let’s say that the user associated with an endpoint AEUI “9zdRwdQqYV88tX” makes a 9-3-3 call.  Although that endpoint’s primary location has been registered as “CorpOffice2ndFloor” in the Locations section above, the user is actually at location “CorpOffice5thFloor” when they make the call.  

So, the following should be specified at the call time:

CALLER'S LOCATION

CorpOffice5thFloor

 

In the location reference calling case, the Geolocation URL indicating the caller’s location and caller name would be:

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

 

And here’s what the SIP INVITE should look like:

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 is no PIDF element in this SIP INVITE - the location of the caller is communicated in the Geolocation header.

 

MAKING A 9-3-3 CALL WITH A LOCATION VALUE

Using a location reference is the recommended way to send a location with the call. However, you can also choose to 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 from Bandwidth Dashboard. See section Checking address validation and getting the standardized address.

Ignoring case, the standardized address you give us must exactly match the address we returned to you when you provided the address. If Bandwidth doesn’t find an exact match  (with the exception of the “loc” element as described below), the call will be routed to the emergency call center as an unprovisioned call. So, assuming our example address of “900 Main Campus Drive, Suite 500, Raleigh, NC, 27606” has been standardized to this:

 

HNO

Street Name

Street Type

Addr 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 should be modified to 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’ <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: 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:PC>27606</ca:PC>

       

       </ca:civicAddress>

     </gp:location-info>

 </dm:device>

</presence>

 

--unique-boundarystring--

 

Note the following changes from the previous location-by-reference example:

  • The content of the SIP message has been 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 Appendix A 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 it’s recommended 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 has been replaced with a CID URL (see RFC 2392) that refers to the Content-ID in the PIDF part of the MIME attachment.

 

NOTE: If you are using UDP with PIDF attachments in the SIP message, Bandwidth is unable to reassemble fragmented UDP packets when the initial packet size is over 5000 bytes. The SIP INVITE above is less than 2000 bytes large, so the risk of going over 5000 bytes is low, but be sure not to add unnecessary whitespace or unused information to the SIP message.

 

NOTE:  Adding the PIDF attachment to the SIP INVITE is likely to make the INVITE too large to fit into a UPD packet. If you are sending location as a value, you must use TCP.

 

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 provisioning phase, without defining all the units in the building.

 

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 a location to 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 like this:

  
<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>

 

and we will send the suite information to the PSAP.

MAKING A 9-3-3 CALL WITH A LAT-LNG IN THE GEOLOCATION HEADER

In this option, the geometric coordinates of the caller are included in the Geolocation header in the SIP INVITE. Bandwidth accepts latitude-longitude for coordinates of the caller. The lat-lng must be formatted as decimal degrees, using the WGS84 coordinate system.

The Geolocation header value should be formatted like this:  

Geolocation: <https://emergency.bandwidth.com/locations/123456?lat={LATITUDE}&lon={LONGITUDE}>

Replace the 123456 with your own Bandwidth Dashboard account number, and replace {LOCATION_REFERENCE} with the reference id of a previously registered location.  Here’s an example 9-3-3 SIP INVITE for a caller in Jefferson City, MO:

 

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

MAKING A 9-3-3 CALL WITH A LAT-LON

The final option is sending the geometric coordinates of the caller. Bandwidth accepts latitude-longitude for coordinates of the caller. The lat-lon must be formatted as decimal degrees, using the WGS84 coordinate system.   

 

Here’s an example 9-3-3 SIP INVITE for a caller in Jefferson City, MO.

 

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 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 Lat/Lon in the Geo-location header

INVITE sip:911@10.10.10.10:5060;transport=udp SIP/2.0.

From: <sip:15554211234@192.168.3.194>;tag=1901e743-13c4-57acf3bf-10bd778f-1e0db8d0.

To: <sip:911@254.xxx.xxx.xxx: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:15555555555@cxc.dashcs.com:5060>.

User-Agent: Acme.

Geolocation: <https://emergency.bandwidth.com/locations/customer1234?lat=34.407&lon=-105.883>

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.xxx.xx.xx

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

 

 

USING THE CONTACT HEADER IN A 9-3-3 CALL

If you can’t set up your caller name or callback number for the caller when you add your endpoint to the Bandwidth systems, but do know that information at 9-3-3 (or 9-1-1) 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 format for the Contact header is:

 

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”. So, the following should be specified at the call time:

Caller's Name

Jane Smith

Call Back Number

13215551234

And you would send this Contact header in the SIP INVITE:

 

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 9-1-1 calls. If you need it, contact your implementation specialist to set up your account to pass caller name and callback number at call time.

 

Failover

FAILOVER TESTING

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

During this test we will provide you with a specific 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 will not respond at all (in the case of a hard-down situation).

The non-response or the error message must be handled appropriately on the customer side to fail over to the other functioning SBC. 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.

 

Make a Test Call to 9-1-1

The test call to 9-1-1 has the same parameters and flow as the 9-3-3 call, with the exception that the username (DNIS) in the SIP URI must be “911” instead of “933”

Before making a 9-1-1 call, verify you have full duplex audio enabled, and that the PSAP can reach the callback number you are providing. Test calls should not be made during a PSAP’s busiest times, which is usually during local morning or afternoon rush hour, or lunch time. An ideal time for test calls is late evenings or very early morning.  Bandwidth support can be available to facilitate a test call to the PSAP.

After initiating the call, you will hear a prompt warning that you are connecting to 9-1-1, then you’ll be connected to the PSAP.  Tell the call taker it’s a test call, and verify you’ve reached the correct PSAP. Here’s an example calling script:

 

You:  “Hello, this is not an emergency, this is a test call. Is this (PSAP you expected to reach)?”

Call taker: Yes (or no), this is (PSAP you expected to reach).

You: “Thank you for your help, goodbye.”  

You: (hang up).

 

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

 

Cleanup

As you finish testing, or as your subscriber data changes, you may want to remove old locations or endpoints.

To remove endpoints, issue a POST with the AEUIs of the endpoints you want to delete, and set the DeleteTNSpecificE911Address to “true”. The example below deletes the endpoint with identifier “9zdRwdQqZW99uYr” location created earlier in this document.

API Operation endpoint: POST {Base API URL}/accounts/{accountId}/e911s

 

EXAMPLE POST PAYLOAD TO DELETE AN ENDPOINT

<E911Order>

  <CustomerOrderId>YourCustomOrderId2</CustomerOrderId>

  <AlternateEndUserIdentifiers>

    <AlternateEndUserIdentifier>

      <Identifier>9zdRwdQqZW99uYr</Identifier>

    </AlternateEndUserIdentifier>

  </AlternateEndUserIdentifiers>

  <DeleteTNSpecificE911Address>true</DeleteTNSpecificE911Address>

</E911Order>

 

This call will not delete the locations from your location pool, it just deletes the endpoints.


A similar API call deletes the locations.  To remove locations, issue a POST with the identifiers of the locations you want to delete, and again set the DeleteTNSpecificE911Address to “true”.  The example below deletes the CoreOffice5thFloor location you created earlier in this document.


API Operation endpoint: POST {Base API URL}/accounts/{accountId}/e911s

 

EXAMPLE POST PAYLOAD TO DELETE A LOCATION

<E911Order>

   <CustomerOrderId>YourCustomOrderId1</CustomerOrderId>

   <AdditionalAddresses>

     <Address>

       <LocationId>CorpOffice5thFloor</LocationId>

     </Address>

   </AdditionalAddresses>

   <DeleteTNSpecificE911Address>true</DeleteTNSpecificE911Address>

</E911Order>

 

If you try to delete a location that is the primary location for an endpoint, you’ll get an error in your order.  You must first delete any endpoints that use the location (or update them to use a new location) before you can delete that location.

Note: Before you delete locations or endpoints, make sure they are not in use.  If you send Bandwidth a 9-1-1 call with that uses an AEUI or location identifier that has been deleted, Bandwidth will not know how to route the call, and will send the call to our Emergency Call Center.

 

References

This document describes how to set up a number for Dynamic Location Routing, with enough details to define a basic successful flow, but not so many details to be overwhelming.  You’ll need more information to build a robust system. The following references will provide you with those details.

https://dev.bandwidth.com/docs/phone-numbers/

Introduction to the Bandwidth Dashboard (Iris) API

https://dev.bandwidth.com/docs/phone-numbers/apiReference.html

Detailed API Documentation. Includes detailed descriptions of Bandwidth Dashboard API calls, example parameters and XML payloads, as well as responses to requests.

https://dev.bandwidth.com/docs/phone-numbers/errors.html

Refer to section 6.4 to the list of all possible E911 errors that can be returned in the the response payload either from the POST request or from a GET request on a specific E911 order.

 

Appendix A - Mapping Bandwidth Dashboard Address Elements to PIDF-LO

The Bandwidth Dashboard AdditionalAddress fields have different names from what is required in a PIDF-LO element.  Here is how those field names should be mapped:

AdditionalAddress Field Name

PIDF-LO Field Name

HouseNumber

HNO

HouseSuffix

HNS

PreDirectional

PRD

StreetName

RD

StreetSuffix

STS

PostDirectional

POD

AddressLine2

LOC

City

A3

StateCode

A1

Zip

PC

Country

country (Note: this should be lower-case.)

 

Still have questions? Open a ticket on the Bandwidth Support Center.

Article is closed for comments.