Emergency Workflow

Overview

The RapidSOS Emergency WorkFlow API packages our deep expertise on the technical and policy challenges associated with the antiquated, complex 9-1-1 system into a single API call, enabling you to focus on quickly implementing a safe and effective emergency solution for your users.

A wide variety of use cases - workflows - can be enabled through a simple API trigger from any connected device (or connected device host).

Workflows are a state-machine designed to be modular, and can constitute a straightforward connection initiated between the caller and 9-1-1, or a complex connection including multiple callers and 9-1-1 centers with tunable timing, SMS messaging, text-to-speech, and interactive voice response (IVR) components.

RapidSOS Workflow API

Supported Workflow Types

NOTE: These workflow types are also known as Solutions

The standard API solution facilitates the RapidSOS product offerings as provided in the following options:

  1. Connect
  2. Connect + Voice (inclusive of inbound calling to 911)
  3. Connect + Monitoring (inclusive of inbound calling to Agents and Video Verification)
  4. Puller

These Product offerings are the common ground across the various industries that RapidSOS solutions cater to.

Each of these workflows can include:

  • One-way SMS
  • Two-way SMS
  • IVR Calling
  • Multimedia (for more information, read about the Resource Manager API

Additional information about RapidSOS standard solution options and flows can be found here.

Getting Started with the Workflow API

  1. If you have not signed a contract with RapidSOS, RapidSOS will assign a Solutions Engineer to work with you to discuss optimal workflows that could be most efficient for your company and its users as well as fulfill the needs of the Public Safety Communicators and First Responders. Contact [email protected] or your RapidSOS Administrator if you'd like to get started
  2. Once the workflow is agreed upon by all parties, RapidSOS will provide you authorized credentials for triggering the Workflow along with any testing tools to assist.
    • Any flows utilized during the pre-sales process are subject to change by RapidSOS post-signing, unless otherwise specified.
  3. Upon agreement of contractual terms, the project will be transitioned and led by the RapidSOS Implementation Team until go-live date. At this point:
    • Once the API trigger and workflow have been finalized by RapidSOS, the company will need to develop their application to communicate with the RapidSOS API.
    • RapidSOS will continue to provide assistance through the development process, inclusive of formal testing of the applications
  4. Once the integration is signed off on by both parties, provisioning of obtaining API credentials for live production deployment.

Authentication

The standard offering for the Workflow API leverages OAuth2.0 as defined in the Authentication Token documentation.

Basic Authentication CAN be supported, but is not recommended. Speak with your RapidSOS Administrator for more information.

Making your first request

Once the token is obtained, leverage the OpenAPI spec on this developer portal to format your request: POST Triggers a RapidSOS workflow

You can also reference this sample code snippet, though it is important to remember that variable schemas are defined per customer:

#RapidSOS grants you a nonexclusive copyright license to use this programming code example (subject to your explicit agreement to RapidSOS Terms of Service) from which you can generate similar function tailored to your own specific needs. All sample code is provided by RapidSOS for illustrative purposes only. These examples have not been thoroughly tested under all conditions. RapidSOS, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs.

Token Request

Workflow API request

API Behavior

This section dives into some of the finer details about the Workflow API that will influence your development.

Base Requirements

  1. For all solutions, RapidSOS expects the partner to provide BOTH the emergency location and initial additional data about the event at the time of the workflow trigger.
  1. For solutions where the RapidSOS workflow is triggered by a phone call or SMS, RapidSOS still expects the emergency location and additional data about the event prior to escalation to emergency services.

If you anticipate these requirements will be a challenge, make sure to discuss the topic with your RapidSOS Administrator as soon as possible.

No Location Events

In some scenarios, the Tech Partner may not have the user's location at the time the workflow is triggered. RapidSOS can handle this incidents, but on a case-by-case basis.

If you anticipate your workflow requiring handling for this scenario, make sure to discuss the topic with your RapidSOS Administrator as soon as possible.

Duplicate Requests

In order to ensure fast response times with the most context possible, RapidSOS reserves the right to:

  1. Reject duplicate workflow triggers for the same user having the same emergency type OR
  2. Consolidate duplicate workflow triggers for a period of time when it is the same user with the same emergency type as the original request for help

The consolidation logic varies by solution type. Contact your RapidSOS Administrator for more details.

NOTE: While the duplicate handling logic can involve location and data updates, the two topics are treated separately. In other words, duplicates are more often viewed as "unwanted" or "unintentional" subsequent triggers.

Location and Data Updates

Emergency events are, by nature, dynamic and ever-changing. Some examples include:

  • An emergency in an Uber ride that could involve location updates
  • A heart rate reading device could have additional readings after an initial spike
  • A building security solution could have new video footage after detecting movement in a new area

The RapidSOS Workflow API is capable of handling mid-event updates to:

  1. Location
  2. Data
  3. Multimedia

The details of how this works can be found in the Open API specs. There are 3 ways to send RapidSOS updates to a running workflow - the one you implement will vary by use case:

  1. Preferred/Standard Method: POST Triggers a RapidSOS workflow
  2. Variable-driven method: PUT Updates a running RapidSOS workflow
    • Requires additional handling in your Workflow to process
  3. Event-driven state-machine method: POST Updates a running RapidSOS workflow

If you are sending updates, we recommend:

  1. No more frequent than every 5m of displacement, or every 5 seconds
  2. Location accuracy of <= 75m
  3. Stop sending updates after the alarm is canceled

Workflow Cancellations

As previously mentioned, emergency events are, by nature, dynamic and ever-changing. Therefore, RapidSOS also supports canceling a request for emergency services on workflows that are still active at the time of cancellation. The methods for doing this are the same as those in the Location and Data Updates section.

Timers

Given the Workflow API is a state-machine, you may not want your workflow to take certain actions until after a set period of time or you may want certain actions to occur for a specifed period of time.,

The standard behavior for certain actions is as follows:

ActionTimeout
Calling User60s
Waiting for SMS response from user30s
Waiting for data payload to accompany inbound call5s

If you would like to change these timers, contact your RapidSOS Administrator for more details.

Scripting

If you use SMS, IVR, or Monitoring capabilities with RapidSOS, the messaging to your users matters. RapidSOS allows Tech Partners to control the messaging for these services:

  • SMS
  • IVR

Monitoring

If you use the RapidSOS Monitoring solution, our agents will use our Standard Call Handling scripts. A sample can be provided by your RapidSOS Administrator.

Webhooks & Reporting

  • All workflow solutions include webhooks as the primary source of live updates for the Tech Partner and users. The list of possible webhooks is defined here.
  • RapidSOS also offers a live-view Dashboard of your events. Contact your RapidSOS Administrator for more details.

Workflow Redundancy

  • Webhooks: If there is an issue delivering a webhook to the partner server, RapidSOS will attempt 1 retry.
  • Failsafes: In the event there is a failure preventing your workflow from escalating an emergency, RapidSOS will work with you to identify preferred failsafe measures that ensure you and your users are in the know and ideally, still able to receive assistance.
  • Monitoring Redundancy: Contact your RapidSOS Administrator for more details.

Workflow Testing

Sandbox

When working in the RapidSOS Sandbox (api-sandbox.rapidsos), your workflow by default WILL NOT escalate an emergency to a real Monitoring Agent or ECC/PSAP.

  • Instead, RapidSOS will configure automated robocalls to take the place of these humans.

Production

When a partner wants to deploy new logic to their production environment for the application that interacts with the RapidSOS API, it is best practice to ensure the workflow functions as expected.

Unless specified, triggering the RapidSOS Workflow in the Production environment (api.rapidsos) WILL escalate an emergency to a real Monitoring Agent or ECC/PSAP. This can result in unintended dispatch.

In order to prevent this, the Workflow API offers a test_mode boolean variable. When true, the workflow will not allow a live emergency call to 911 (live_call cannot be true) and will not escalate the event to a real Monitoring agent.

  • Instead, the workflow will mimic the robot behavior seen in Sandbox

ECC Testing

There are times when a partner may want to run a coordinated test with an ECC that involves the emergency escalating all the way to Emergency Services.

  • In these scenarios, you would leverage ecc_test

Product Demo

Logic to enable live demos of the Partner's Workflow implementation in a Production environment can be implemented on a case-by-case basis.