Action Requests

Overview

The Action Request service enables you to display high-priority modal prompts to specific mobile app users. Action Requests require acknowledgment or interaction before users can continue using the mobile app.

NOTE: This feature is only supported in version 1.59 or later.

Common use cases include:

Severe weather warnings
Document scan requests
Safety policy acknowledgments
Load assignment acceptances

IMPORTANT: Action Requests block all mobile app interaction until the user responds. To avoid safety risks, we strongly recommend limiting the use of this feature.

How It Works

Submit an Action Request using the PUT API. The Platform synchronizes the request to the target user’s mobile app. When conditions allow, the mobile app displays the Action Request as an overlay on top of the current screen. Users must respond before interacting with other areas of the mobile app unless snoozing is enabled.

By default, delivery is postponed while a user is in turn-by-turn navigation or during In-Motion Locking. To display an Action Request in these states, refer to Action Requests in Motion.

Key Components

When creating an Action Request, define the following required properties:

username: Identifies the user who receives the Action Request
handle: Defines a unique per-user identifier used for tracking and completion handling
title: Specifies the primary heading text displayed to the user
actions: Defines the available response actions presented within the request
IMPORTANT: The actions array must contain at least one action object and cannot contain more than two action objects.

TIP: Disable the show_form_editor flag on an actions properties when a simple acknowledgment button is sufficient. This configuration allows users to respond with a single tap without opening the form editor.

Snooze Behavior

Action Requests support configurable snooze behavior through the snooze object. When enabled is set to true, users can temporarily snooze the Action Request and continue interacting with the mobile app until the snooze period expires. Set the duration with the snooze_duration_minutes field.e

NOTE: enabled is set to true by default.

The snooze_duration_minutes field supports values from 15 minutes up to 1,439 minutes (just under 24 hours). After the configured expiration, the Action Request reappears automatically and the user must respond before continuing use of the mobile app.

Users can manually redisplay a snoozed Action Request through the app menu at any time.

IMPORTANT: Setting enabled to false disables snoozing entirely and blocks all mobile app interaction until the user responds to the Action Request.

Action Button Sizing

Use the action_button_size property to control the size of action buttons displayed within the Action Request.

Available sizes are: default, large, and null.

Use larger button sizing for workflows that require increased visibility or easier interaction within the mobile app.

Action Requests in Motion

By default, Action Requests are postponed during turn-by-turn navigation and In-Motion Locking. Set hide_while_in_motion to false to display an Action Request in these states. Use this only when the message must reach the user regardless of driving state.

NOTE: Delivering Action Requests in motion is only supported in version 1.64 or later.

WARNING: In-motion Action Requests require every action to have show_form_editor set to false. Attempting to send an in-motion Action Request with this set to true will result in an error.

Recommended Configuration

For safety, keep in-motion Action Requests short and easy to act on:

Keep title and body brief
Set action_button_size to large
Use a single acknowledgment action whenever possible

Text-to-Speech

Use text-to-speech (TTS) so users can listen to the Action Request without reading the screen:

text_to_speech_announcement: The message is read aloud to the user.
text_to_speech_autoplay_enabled: When true, the announcement plays automatically when the Action Request is displayed.
text_to_speech_replay_limit: Limits how many times the user can replay the announcement (must be greater than 0; unlimited if omitted).

TIP: Enable text_to_speech_autoplay_enabled for in-motion Action Requests so users do not need to interact with the screen to hear the message.

Delivery Behavior

The Platform manages the timing and volume of Action Requests to ensure safety and system stability:

Only one Action Request can remain active per user at a time.
If an Action Request is no longer needed, delete it via the API to remove it from the user's device.