How do I provision emergency notifications in the 911 Access Portal?

This article explains how you can provision emergency notifications in the 911 Access Portal. Looking to provision emergency notifications via the API instead? Check out our developer docs!

When a 911 call is placed from within an enterprise, like a corporate campus, college, or university, certain individuals need to be aware of the emergency or situation occurring so they can react quickly and assist the first responders.

Recipients of notifications can include the front desk reception area, security teams, or facility managers. These individuals need to be notified in a variety of ways, including email, text (SMS), IVR call, and HTTP Webhook. The Webhook method simply provides the 911 call notification via HTTP, allowing customers to integrate with a variety of applications they specify. 

The required elements of the notification are:

• Time of call 
• Phone number that originated the call 
• Subscriber name
• Address on file (including Address Line 2, if populated)

The key driver of this is the FCC mandate known as Kari’s Law, which was signed into law on February 16, 2018. Kari’s Law applies to multi-line telephone systems (MLTS) “manufactured, imported, offered for first sale or lease, first sold or leased, or installed” after the compliance date of February 16, 2020. It requires: 

• Elimination of a prefix digit such as an “8” or “9” when calling 911.
• Notification of designated personnel when a 911 call is placed. This could include a security team or a front desk attendant.

Adding a notification contact

1. Log into the 911 Access Portal. 
2. From the target account, click Emergency and then Notifications. 
3. In the New Notification Recipient section, enter a unique Notification ID and Recipient, and select Notification Type. The drop-down options are:
   • Email
   • HTTP (see HTTP Callback below)
   • SMS (the Caller ID will be 877-547-5146)
   • Voice (the Caller ID will be 877-579-3712)
4. Click Save.

Note:

• Limits to the notification recipient ID include: "The ID can only contain the following: "letters, numbers, and the characters: , . - @ and _".
• SMS notifications must be submitted in 11-digit format. Example: 19195557777.
• HTTP requires Username and Password, and “Recipient” is the URL. 

Notification HTTP callback

Along with SMS, voice, and email notifications, you can tell Bandwidth to send an HTTP message to an HTTP service you provide. One of the notification types is HTTP. The HTTP notification type requires three pieces of information:

• Recipient: This is the URL that the message will be sent to
• Username: Username for HTTP basic authentication
• Password: Password for HTTP basic authentication

When one of your subscribers calls 911 or 933, and they have an HTTP notification type assigned to their phone number, Bandwidth will send the caller information to the URL you specified using HTTP POST.

Notification message

The message that Bandwidth sends will have the fields in the table below. Some fields aren't always in the caller address. For example, if there's no Address Line 2, the "loc" field won't be in the message. Also, we can process a call without an address if one hasn't been assigned to the phone number when the call was sent to us. In those cases, we won't provide the missing fields in the message. If a field might not be sent, it's marked as Optional in the table below.

Field Name	Meaning	Optional/Required	Type
a1	Two-character state or province code	Optional	string
a3	Town, city, or community name	Optional	string
addr1	Address line 1	Optional	string
callback	Callback phone number that can be used to contact the caller.	Always	string
caller_name	Name of caller	Always	string
call_time	Time of call in UTC and RFC 3339 format and UTC zone	Always	string
country	Two-character country code	Optional	string
lat	Latitude of the caller in decimal degrees	Always	number
loc	The secondary location of the caller (sometimes referred to as "Address Line 2"), such as the floor, apartment, suite, etc.	Optional	number
lon	Longitude of the caller in decimal degrees	Always
notification_id	ID for the notification recipient that caused this notification to be sent.	Always	string
pc	Postal code for the caller's location	Optional	string
type	Type of call. Will be "EMERGENCY" for 911 calls, or "ADDRESS_VALIDATION" for 933 calls.	Always	string

The field will be encoded as JSON. Here's an example message:

POST /your_callback_endpoint_here HTTP/1.1
Host: example.com
Content-Type: application/json
Content-Length: 325

{
  "addr1": "1000 ELM ST",
  "loc": "UNIT 17",
  "a3": "WINNIPEG",
  "a1": "MB",
  "pc": "R3M3P5",
  "country": "ca",
  "lat": 49.871234,
  "lon": -91.181234,
  "notification_id": "TestWebHook",
  "call_time": "2019-11-23T18:16:48.234Z",
  "caller_name": "Test Caller",
  "callback": "15553211234",
  "type": "EMERGENCY"}

Security and authorization

We recommend that your callback endpoint support HTTPS. In addition, Bandwidth will attempt to use HTTP Basic Authentication to connect to your callback endpoint. When setting up your notification, you must provide a username and password that Bandwidth can use to connect to your service.   

Failures and retries

Bandwidth will treat any HTTP responses besides 2xx and 3xx as a failure. If we get a failure response from your service, we'll attempt to send the message two more times.

Adding recipient to endpoint(s)  

1. Select Emergency, and then click Endpoints.
2. Search for the target endpoint you want to edit by clicking the endpoint.
3. Select Add Recipient.

Note: You can have a maximum of 3 notification recipients per endpoint.

4. On the pop-up, choose the proper recipient, and then click Save.

5. If the recipient has been successfully added, your endpoint will look like this: 

Note: The Find Notification Recipients is a search-as-you-type field. If you see too many choices in the drop-down, you can start typing and it'll only show recipients where the email address or recipient ID contains characters that match what you typed.

Batch uploads/edits

If you want to batch edit endpoint notification recipients, you can do bulk updates using the following steps:

1. In the top navigation bar, click Emergency and select Bulk Import.
2. Download the CSV file for Batch CSV Notification Recipient Import. 

The CSV file will contain the following fields:

• Endpoint is a required field that should be a valid telephone number already provisioned in the system. AEUI/ACIDs are also supported, but AEUI provisioning only happens through the Bandwidth App where the notifications aren't supported.
• Type indicates the type of notification that will be sent. Valid values are:
  
  • EMAIL - the notification will be sent by email, and the recipient value will be a valid email address.  
  • SMS - the notification will be sent via text message. The recipient value must be a US or Canadian 10-digit phone number with the country code "1" prepended.
  • VOICE - the notification will be sent in the form of a voice message. The recipient value must also be a US or Canadian 10-digit phone number with the country code "1" prepended.
  • HTTP - the notification will be in the form of an HTTP callback message to an HTTP server provided by you. In this case, the recipient value must be a valid HTTP URL.
• Recipient URI/ID is a required field that contains the notification value for the recipient or the ID for a previously created notification recipient. A notification recipient value must be valid for the given Type.
  • If a recipient value like an email address is given, it'll be added as a new notification recipient to the system even if that address is already in the system. The system will assign a recipient ID to the new address.
  • If the recipient ID is given, then we'll search your account for a matching recipient ID and assign it to the endpoint.
• Username and Password are for HTTP notification recipient types. If you provided a URL to a service that requires basic HTTP authentication, you can provide the username and password for that service in these fields.

The header row in the CSV isn't necessary, especially since including it will typically cause the batch job to show an error. 

Emergency notification response examples

Webhook / HTTP Callback

Email

In addition to the caller address, name, and callback number, the email notification shows Bandwidth's name for the PSAP and the FCC ID for the PSAP. If the call wasn't provisioned correctly and was routed to the ECC, "ECC" is displayed as the PSAP name. In a small percentage of cases, the local PSAP is not yet capable of receiving the information directly from Bandwidth, and the call is sent to Bandwidth's ECC. You're not charged ECC fees for this call, so the PSAP name is still displayed instead of "ECC".

SMS

Voice

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