E911 Dynamic Location Routing Testing Guide

This guide describes how you can send SIP requests to initiate 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 test call that communicates the caller’s location at call time.

If you're using Microsoft Teams for your unified communication direct routing calling, consult your Microsoft Teams support personnel for instructions on testing.

Important: Ensure that your locations have been added in the IntelePeer Customer Portal > Locations > Dynamic 911 Locations tab. If you are using the E911 Number Management API, include the locationID that can be found on the same tab. Once your E911 service is active, if a caller’s location can’t be found in the IntelePeer system, the call goes directly to the national Emergency Command Center (ECC), so the caller will be speaking to a call taker outside their area. Because of this, additional fees are assessed per call.

Making a Test Call to 933

For testing purposes, we provide a service called 933. When you dial 933, this service reads the calling phone number and the provisioned address back to you. This is a good way for you to verify the system is working and 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 IntelePeer Session Border Controllers (SBCs). You must put the exact endpoint identifier 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 can 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 IntelePeer SBC IP 124.124.124.124.

Note: You can send any valid SIP headers, whether it’s by Reference, Value, Geolocation header, or PIDF-LO attachment.

You can initiate a PIDF-LO call using:

Location by Reference
Location by Value
Location with a lat-lon in a Geolocation header
Location with a lat-lon in a PIDF-LO attachment

Note: RFC 6442 defines the semantics of the Geolocation-Routing header. IntelePeer ignores the value of this header. If you have SIP intermediaries between you and IntelePeer 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 following examples. 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 IntelePeer 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.intelepeer.com/locations/{account_number}/{location_reference}>

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

Let’s say your IntelePeer 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:

IntelePeer Account Number 123456
Caller's Location CorpOffice5thFloor

The URL would need to be formatted like this:

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

And the SIP INVITE would then look like this:

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
From: &lt;sip:9zdRwdQqYV88tX@123.123.123.123&gt;;tag=1901e743-13c4-57acf3bf-10bd778f-1e0db8d0.
To: &lt;sip:933@124.124.124.124:5060&gt;
Call-ID: CXC-1956-7052b170-1901e743-13c4-57acf3bf-10bd778e-3a245182
CSeq: 1 INVITE
Contact: Jane Smith &lt;sip:13215551234@example.com&gt;
Via: SIP/2.0/UDP 123.123.123.124:5060;branch=z9hG4bK-5c189-57acf3bf-10bd778f-3b0740c9
Max-Forwards: 63
P-Asserted-Identity: &lt;sip:9zdRwdQqYV88tX@sbc.example.com:5060&gt;
User-Agent: SomeUserAgent
Geolocation: &lt;https://emergency.intelepeer.com/locations/123456/CorpOffice5thFloor&gt;
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.

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 a geolocation with the call, you can also use the Location by Value method that 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 IntelePeer.

Important: Ignoring case, the standardized address you pass to IntelePeer in the PIDF mime attachment must match exactly what IntelePeer returns when the address is validated in IntelePeer or the API call. If IntelePeer doesn’t find an exact match, the call is 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:

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
From: &lt;sip:9zdRwdQqYV88tX@123.123.123.123&gt;;tag=1901e743-13c4-57acf3bf-10bd778f-1e0db8d0
To: &lt;sip:933@124.124.124.124:5060&gt;
Call-ID: CXC-1956-7052b170-1901e743-13c4-57acf3bf-10bd778e-3a245182
CSeq: 1 INVITE
Contact: Jane Smith &lt;13215551234@example.com&gt;
Via: SIP/2.0/TCP 123.123.123.124:5060;branch=z9hG4bK-5c189-57acf3bf-10bd778f-3b0740c9
Max-Forwards: 63
P-Asserted-Identity: &lt;sip:9zdRwdQqYV88tX@sbc.example.com:5060&gt;
User-Agent: IntelePeerVoice
Geolocation: &lt;cid:pidf-attachment@somewhere.example.com&gt;
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: &lt;pidf-attachment@somewhere.example.com&gt;
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;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"&gt;
&lt;dm:device id="target123-1"&gt;
&lt;gp:geopriv&gt;
&lt;gp:location-info&gt;
&lt;ca:civicAddress&gt;
&lt;ca:country&gt;us&lt;/ca:country&gt;
&lt;ca:HNO&gt;900&lt;/ca:HNO&gt;
&lt;ca:RD&gt;MAIN CAMPUS&lt;/ca:RD&gt;
&lt;ca:STS&gt;DR&lt;/ca:STS&gt;
&lt;ca:A1&gt;NC&lt;/ca:A1&gt;
&lt;ca:A3&gt;RALEIGH&lt;/ca:A3&gt;
&lt;ca:LOC&gt;Suite 500&lt;/ca:LOC&gt;
&lt;ca:PC&gt;27606&lt;/ca:PC&gt;
&lt;/ca:civicAddress&gt;
&lt;/gp:location-info&gt;
&lt;/gp:geopriv&gt;
&lt;/dm:device&gt;
&lt;/presence&gt;
--unique-boundarystring--

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 IntelePeer 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 IntelePeer 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 IntelePeer'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.intelepeer.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.intelepeer.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, IntelePeer pulls 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, IntelePeer first tries to find an exact match for the address in the location records in your account, including an exact match for the value of the 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, IntelePeer then tries 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 IntelePeer 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 a geolocation in IntelePeer without an Address Line 2 field. When you initiate the SIP INVITE, add the suite the caller is into the loc field PIDF element, and we'll send the suite information to the PSAP:

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
<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. IntelePeer accepts latitude-longitude (lat-lon) for 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.intelepeer.com/locations/{account_number}?lat={latitude}&lon={longitude}>

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

Let’s say your IntelePeer 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:

IntelePeer Account Number 123456
Latitude 38.573313
Longitude -92.177170

The URL would need to be formatted like this:

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

And the SIP INVITE would then look like this:

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
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.intelepeer.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 likely makes 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:

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
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: IntelePeerVoice
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 IntelePeer's systems, but do have that information at 933 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:

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

IntelePeer ignores the domain name in the SIP URI and only use the username portion. By default, the value of the Contact header is ignored for 911 calls. If you need it, contact your IntelePeer Customer Success specialist to set up your account to pass the caller name and callback number at call time.

Failover Testing

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

During this test, we'll provide you with a specific location server to dial from and simulate a scenario in which your 911 call is sent to your primary route and then fails 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 IntelePeer 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.